Knowl v0.5.0

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:

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.

Published artifact

ghcr.io/baldaworks/knowl@sha256:367fa037eaa3f8ce0133bbfbf1c416293e24353ca0a9f3b0a19f21b3328c3bea