# Knowl v0.5.0 — Policy-Aware Maintenance and Isolated Validation

Knowl v0.5.0 makes source maintenance respond safely to policy changes even
when source revisions do not change. It also preserves open-world links from
accepted source material while preventing one invalid generated document from
blocking unrelated valid updates.

## Highlights

### Policy-aware source maintenance

- A deterministic, non-secret policy generation now participates in durable
  maintenance identity. Changing an output-affecting rule, including the
  effective read ceiling, makes an unchanged source revision eligible for one
  new bounded maintenance cycle.
- Documents that previously failed the former 32,768-character ceiling can be
  reconsidered under the current 262,144-character default without editing the
  source. Repeated scans under the same generation converge without duplicate
  work.
- Automatic reconsideration remains limited to safe source-policy transitions.
  Staging, provider, and unknown failures retain their explicit manual retry
  gate.

### Open-world links and provenance isolation

- Unresolved original links proven to exist in accepted Markdown are preserved
  and reported through bounded, redacted diagnostics instead of invalidating
  source staging.
- Newly invented unresolved links, malformed paths, and escaping targets remain
  rejected.
- Invalid Knowl-owned provenance such as `citation.unknown_source` is isolated
  to the affected document. Valid sibling documents can still commit and reach
  the index, while the prior canonical version of a rejected document remains
  readable.
- Catalog edits that would publish a broken graph are withheld with the smallest
  deterministic dependent closure.

### Durable recovery and Git source hardening

- SQLite and PostgreSQL persist maintenance generation and bounded diagnostics
  with equivalent retry, restart, and idempotent replay behavior.
- Legacy rows use an explicit compatibility path, including safe replay of
  empty pre-diagnostics state, without weakening malformed-state checks.
- Git cache lineage and repository identity checks reject stale, rebound, or
  structurally incomplete cache state while preserving bounded recovery.

## Compatibility and upgrade

The HTTP, MCP, provider, source configuration, and canonical Markdown contracts
remain compatible. This release adds operational-store migrations for
maintenance generation and diagnostics. The migrations preserve existing
operations and source history.

1. Stop active writers and back up the workspace and operational store.
2. Deploy `ghcr.io/baldaworks/knowl:v0.5.0` and wait for `/readyz`.
3. Run `knowl run` or the configured synchronization workflow.
4. Inspect `knowl source status` for policy-triggered work, unresolved original
   links, isolated document rejections, and any failures that still require a
   manual class-filtered retry.

Rolling back across the new operational migrations requires restoring the
pre-upgrade operational database. Canonical Markdown and accepted raw source
history remain unchanged and portable.

## Published artifact

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

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

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

## Validation

The release gate verifies modules and generated OpenAPI bindings, runs the full
race-enabled Go suite, vulnerability and architecture checks, strict linting,
the PostgreSQL integration contract, and a release-shaped persistent-volume
sidecar smoke test before publishing.
