# Knowl v0.3.1 — Legacy Provenance Backfill

Knowl v0.3.1 fixes source-filtered retrieval after upgrading a workspace whose
raw revisions were accepted before configured-source provenance was stored in
raw manifests.

## Fix

- Reconciliation enriches a legacy raw manifest with its validated
  `source_document` identity while reusing the already accepted immutable
  source bytes; unchanged documents are not fetched from the connector again.
- The enrichment is one-way and conflict-safe: existing provenance cannot be
  replaced by a different document identity.
- The projection rebuilt by the same source sync now records
  `source_documents` and page-to-source relations for semantic pages that cite
  those legacy revisions. `knowl retrieve --source <id>` therefore returns the
  same relevant semantic evidence as unfiltered retrieval.

Bootstrap and `sync.on_start` remain optional. Source documents remain outside
the portable semantic wiki, and legacy `wiki/sources/<source_id>/**` mirrors
remain excluded.

## Upgrade

1. Stop active writers and back up the complete workspace and operational
   store.
2. Deploy `ghcr.io/baldaworks/knowl:v0.3.1`.
3. Run `knowl source sync --all` once. The sync backfills legacy provenance and
   rebuilds the projection even when all maintenance operations are already
   terminal.
4. Verify both unfiltered retrieval and `--source` retrieval for an existing
   semantic page.

## Published artifact

The release workflow publishes and attests a multi-platform Linux image for
`amd64` and `arm64` to:

```text
ghcr.io/baldaworks/knowl:v0.3.1
```

Pin the digest emitted by the GitHub Release for production deployments.

