data-olympus 0.4.2__tar.gz → 0.5.0__tar.gz

{data_olympus-0.4.2 → data_olympus-0.5.0}/CHANGELOG.md

@@ -12,6 +12,59 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-07-12
+
+### Added
+
+- **Version-immutability release guard (`scripts/check_version_free.py`).** A
+  published version (PyPI, the ghcr `:vX.Y.Z` image tag, or a GitHub
+  release/tag) is immutable, so the release process now refuses to republish an
+  existing version. The guard runs as the first step of `tag-release.yml`'s
+  `decide` job (before the tag is pushed, so a duplicate never leaves an
+  orphaned public tag) and in PR CI (to catch a duplicate declared version
+  before merge). A legitimate reconcile (local tag `vX.Y.Z` already at HEAD) is
+  allowed and skips the registry lookups; a registry outage fails closed. The
+  operator can override a stuck registry with `KB_BYPASS_VERSION_CHECK=1`.
+  (gh #148 / KNA-67)
+- **First-class reverse-proxy Host allowlist (`KB_PUBLIC_HOSTNAMES`).** New
+  config knob mapped onto fastmcp's Host-header allowlist when the HTTP app is
+  built, so operators configure data-olympus directly instead of reaching for
+  the dependency's `FASTMCP_HTTP_ALLOWED_HOSTS` env var (both are honoured and
+  merged). The server now emits a startup WARN when Host protection is on, it
+  binds a non-loopback address, and no public hostname is allowed: the exact
+  silent-breakage shape (readiness green, every proxied request 421) behind the
+  2026-07-09 kn-dev outage. A regression test boots the app with a configured
+  public hostname and asserts the good Host reaches the route while a foreign
+  Host is answered 421. (gh #139 / KNA-70)
+- **Prometheus `/metrics` endpoint (optional `metrics` extra).**
+  `prometheus-client` is an OPTIONAL dependency; with it installed, `GET
+  /metrics` serves the standard exposition format (pending/push queue depths,
+  frozen count, push-failure counter, staleness, live sessions, per-tool call
+  counters, index-build duration + last-build timestamp). Without the extra the
+  route returns `501` and every metric update inside the core background loops
+  is a silent no-op, so a standard deployment is unaffected. (gh #69 / KNA-71)
+- **Cached update-available signal.** The server now checks PyPI/GitHub for a
+  newer published `data-olympus` version in a background task and surfaces
+  `latest_version` / `update_available` in `kb_health` and
+  `GET /api/v1/health`. The health request path reads the cache only, and
+  compact health includes `latest_version` only when `update_available` is true.
+  Air-gapped deployments can set `KB_DISABLE_VERSION_CHECK=on` to make zero
+  outbound version-check calls. (gh #146 / KNA-68)
+- **Legacy corpus status migration.** Status-less documents from pre-0.4.0
+  corpora now default to `active` in the SQLite index when
+  `KB_STATUS_AUTOFILL=on` (the default), preserving in-force retrieval without
+  mutating source markdown during index builds. Operators can persist the same
+  default explicitly with the idempotent `data-olympus migrate status --apply`
+  command. (gh #147 / KNA-69)
+
+### Fixed
+
+- **`kb_consult` demoted_writes CTA count.** The maintenance CTA now counts only
+  the session's live pending entries and is omitted once none remain, instead of
+  reporting stale "N write(s) awaiting operator review" after every demoted entry
+  had been resolved (the demoted_writes / pending_actions surface shipped since
+  v0.4.0 via #131). (gh #137 / KNA-72)
+
 ## [0.4.2] - 2026-07-11
 
 ### Added
@@ -1551,7 +1604,8 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `docs/adoption.md`: bring-your-own-KB guide (author, lint, index, serve, wire an agent).
 - `docs/comparison.md`: how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 
-[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.4.1...HEAD
+[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/knaisoma/data-olympus/compare/v0.4.2...v0.5.0
 [0.4.1]: https://github.com/knaisoma/data-olympus/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/knaisoma/data-olympus/compare/v0.3.5...v0.4.0
 [0.3.5]: https://github.com/knaisoma/data-olympus/compare/v0.3.4...v0.3.5

{data_olympus-0.4.2 → data_olympus-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-olympus
-Version: 0.4.2
+Version: 0.5.0
 Summary: Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server
 Project-URL: Homepage, https://github.com/knaisoma/data-olympus
 Project-URL: Repository, https://github.com/knaisoma/data-olympus
@@ -33,6 +33,7 @@ Provides-Extra: dev
 Requires-Dist: fastembed<0.9,>=0.8; extra == 'dev'
 Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.3; extra == 'dev'
@@ -41,6 +42,8 @@ Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
 Requires-Dist: types-regex>=2024.5; extra == 'dev'
 Provides-Extra: embeddings
 Requires-Dist: fastembed<0.9,>=0.8; extra == 'embeddings'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
 Description-Content-Type: text/markdown
 
 # data-olympus

{data_olympus-0.4.2 → data_olympus-0.5.0}/SPEC.md

@@ -281,6 +281,13 @@ The serving transport MUST be streamable HTTP (not stdio). The MCP endpoint is `
 
 **Readiness probes MUST NOT target `/api/v1/health`.** A load balancer or orchestrator readiness check MUST use `GET /readyz` (200 once the process is up and the index is loaded, independent of data staleness). `/api/v1/health` keeps a 503-on-degraded contract for data-freshness alerting; wiring it as a readiness probe would eject a healthy single replica from its Service on a transient git-remote staleness. See [`docs/serving.md`](docs/serving.md).
 
+**Update-available signal.** A server MAY surface cached `latest_version` and
+`update_available` fields in `kb_health` / `GET /api/v1/health` when a newer
+data-olympus package is published. These are informational serving-layer fields
+only: they MUST NOT affect `degraded` or readiness, and the health request path
+MUST read a cache rather than perform outbound registry calls. Deployments MAY
+disable the check entirely for air-gapped operation.
+
 **Enforcement endpoints.** A server MAY expose an enforcement surface that turns the advisory KB into a gated consultation proxy for code and architectural decisions. The endpoints are:
 
 - `POST /api/v1/consult`: record a consultation for a `(source_session, workspace)` pair and return the governing rules for the supplied intent.
@@ -351,6 +358,8 @@ The `spec_version` field is optional in bundles targeting this `0.1` draft. It b
 
 **Issue #114 (write-path `status` enforcement) does NOT bump this version.** `status` has been a required field under section 4.2 — and a `kb lint` error when absent — since the `0.1` draft; no prior version of this document ever described it as recommended, so there is no required-field-semantics change to record here. What issue #114 adds is a reference-implementation write-path check (section 8): a NEWLY created document missing `status` is now rejected at commit time, closing a gap where the write path was more permissive than `kb lint`. This does not affect any already-conformant bundle (which by definition already has `status` on every document) and does not change how an existing bundle is read, parsed, or validated — only how a brand-new document is admitted through the write path. Per the minor/major criteria above, that is neither: it is a reference-implementation enforcement-timing change, not a format change, so it is documented here rather than as a version increment. A bundle that is already non-conformant (missing `status` on one or more legacy documents) is unaffected in how it is READ — those documents keep being served, just never as in-force — see the maintenance ledger migration path in [`docs/operations.md`](docs/operations.md).
 
+**Issue #147 / KNA-69 (legacy status autofill) also does NOT bump this version.** `#147` is a reference-implementation read-side default, not a format change: it does not alter what `status` means, its controlled vocabulary, or the requirement that documents carry it. It changes how the reference implementation treats a legacy document that is missing `status`. Under `#114` such a document was served but never in-force, so a pre-0.4.0 corpus silently lost its in-force guidance on upgrade. Under `#147` the index build treats a missing `status` as `active` by default (`KB_STATUS_AUTOFILL=on`), so the corpus keeps governing exactly as it did before the upgrade. This intentionally reverses the conservative "never guess status" stance `#114` took, and it does so for one deliberate reason: for the narrow legacy-upgrade case, a seamless default that preserves prior in-force behavior is worth more than conservatively flagging every legacy document as not-in-force and blocking it until a manual fix lands. The reversal is bounded and reversible: it applies only to documents with NO `status` (an explicit status is always honored verbatim), never rewrites the markdown source at index time (the build stays a read-only parse; the physical gap is still tracked by the maintenance ledger so the `missing_status` CTA keeps nagging), and is fully disabled by `KB_STATUS_AUTOFILL=off` for a deployment that prefers explicit flagging. Persisting the default into the markdown source is a separate, explicit operator action (`data-olympus migrate status --apply`), never an implicit side effect of indexing. See [`docs/operations.md`](docs/operations.md) section 5.2.
+
 ---
 
 ## 11. Relationship to other formats

{data_olympus-0.4.2 → data_olympus-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-olympus"
-version = "0.4.2"
+version = "0.5.0"
 description = "Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -46,6 +46,14 @@ Changelog = "https://github.com/knaisoma/data-olympus/blob/main/CHANGELOG.md"
 embeddings = [
     "fastembed>=0.8,<0.9",
 ]
+# Optional Prometheus /metrics endpoint (issue #69). NOT a core dependency: the
+# metrics registry is a no-op shim when prometheus-client is absent (its inc/
+# set/observe calls live inside core background loops and tool wrappers, so a
+# bare import must never crash a standard deployment). With the extra installed,
+# /metrics serves the exposition format; without it, /metrics returns 501.
+metrics = [
+    "prometheus-client>=0.20",
+]
 dev = [
     "pytest>=8.3",
     "pytest-asyncio>=0.24",
@@ -59,6 +67,9 @@ dev = [
     # runtime; the tests opt in via KB_EMBEDDINGS_MODE and skip if the model
     # cannot be fetched in the sandbox).
     "fastembed>=0.8,<0.9",
+    # Exercise the Prometheus /metrics path in CI (the exposition-format test
+    # skips when this is absent; the no-op-shim tests run regardless).
+    "prometheus-client>=0.20",
 ]
 bench = [
     "tiktoken>=0.8",

{data_olympus-0.4.2 → data_olympus-0.5.0}/src/data_olympus/cli/main.py

@@ -143,6 +143,8 @@ def build_parser() -> argparse.ArgumentParser:
     add_init_subparser(sub)
     from data_olympus.cli.verify_cmd import add_verify_subparser
     add_verify_subparser(sub)
+    from data_olympus.cli.migrate_cmd import add_migrate_subparser
+    add_migrate_subparser(sub)
     return parser
 
 

data_olympus-0.5.0/src/data_olympus/cli/migrate_cmd.py

@@ -0,0 +1,105 @@
+"""`data-olympus migrate status`: persist the status autofill to disk (#147).
+
+The `status` subcommand writes the `status` field into legacy (pre-0.4.0)
+markdown docs that are missing it, using the default `active` (see
+``data_olympus.status_migrate``). This is the EXPLICIT counterpart to the
+index build's VIRTUAL autofill (KB_STATUS_AUTOFILL): the build never touches
+the markdown source, so an operator runs this once to make the change durable.
+
+Without ``--apply`` the command is a DRY RUN: it reports which files would be
+changed and exits 0, changing nothing. ``--apply`` performs the write and (when
+an audit log path is configured) records one audited event per changed file.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import argparse
+
+
+def add_migrate_subparser(
+    sub: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Wire the ``migrate`` command (with its ``status`` subcommand) in."""
+    p_migrate = sub.add_parser(
+        "migrate",
+        help="one-off corpus migrations (e.g. persist the status autofill)",
+    )
+    migrate_sub = p_migrate.add_subparsers(dest="migrate_command", required=True)
+    p_status = migrate_sub.add_parser(
+        "status",
+        help="write a default `status: active` into legacy docs missing it (#147)",
+    )
+    p_status.add_argument(
+        "path", nargs="?", default=".", help="corpus root (default: .)"
+    )
+    p_status.add_argument(
+        "--apply",
+        action="store_true",
+        help="write the change to disk (default: dry run, reports and changes nothing)",
+    )
+    p_status.add_argument(
+        "--audit-log",
+        default=None,
+        help="audit-log path for the applied writes (default: $KB_AUDIT_LOG_PATH; "
+        "omitted entirely if neither is set)",
+    )
+    p_status.set_defaults(func=_cmd_migrate_status)
+
+
+def _cmd_migrate_status(args: argparse.Namespace) -> int:
+    import sys
+
+    from data_olympus.format import discover_bundle_files
+    from data_olympus.format.document import Document
+    from data_olympus.status_migrate import DEFAULT_STATUS, apply_status_autofill
+
+    root = Path(args.path)
+    if not root.is_dir():
+        print(f"error: {root} is not a directory", file=sys.stderr)
+        return 2
+
+    if not args.apply:
+        # Dry run: report the files that WOULD be rewritten, change nothing.
+        would_change: list[str] = []
+        for md in discover_bundle_files(root):
+            try:
+                doc = Document.load(md)
+            except ValueError:
+                continue  # malformed frontmatter: a lint concern, not migrated
+            status = doc.frontmatter.get("status")
+            if not (isinstance(status, str) and status.strip()):
+                would_change.append(str(md.relative_to(root)))
+        for rel in would_change:
+            print(f"would set status: {DEFAULT_STATUS}  {rel}")
+        print(
+            f"dry run: {len(would_change)} document(s) would be updated "
+            f"(re-run with --apply to write)"
+        )
+        return 0
+
+    audit_log = None
+    audit_path = args.audit_log or os.environ.get("KB_AUDIT_LOG_PATH")
+    if audit_path:
+        from data_olympus.audit_log import AuditLog
+
+        audit_log = AuditLog(
+            log_path=audit_path,
+            hmac_key=os.environ.get("KB_AUDIT_HMAC_KEY", ""),
+        )
+
+    result = apply_status_autofill(root, audit_log=audit_log)
+    for rel in result.changed_paths:
+        print(f"set status: {DEFAULT_STATUS}  {rel}")
+    if result.skipped_malformed:
+        for rel in result.skipped_malformed:
+            print(f"skipped (malformed frontmatter, fix with `kb lint`): {rel}")
+    print(
+        f"applied: {result.changed} changed, {result.already_present} already had "
+        f"status, {len(result.skipped_malformed)} skipped "
+        f"({result.scanned} scanned)"
+    )
+    return 0

{data_olympus-0.4.2 → data_olympus-0.5.0}/src/data_olympus/config.py

@@ -75,6 +75,19 @@ class Config:
     # Window sizes (days) for the "recently expired" / "expiring soon" buckets.
     maintenance_recently_expired_days: int = 30
     maintenance_expiring_soon_days: int = 30
+    # Virtual status autofill for legacy (pre-0.4.0) corpora (issue #147 / KNA-69).
+    # Default ON. When on, the index build treats a doc missing `status` as
+    # `active` IN MEMORY only (the SQLite `docs.status` column and the in-force
+    # retrieval view), so a pre-0.4.0 corpus does not silently lose its in-force
+    # docs on upgrade. The markdown source file is NEVER touched by the build:
+    # Index.build stays a read-only parse. The maintenance ledger still reports
+    # the PHYSICAL missing-status gap (so it keeps nagging until the operator runs
+    # `data-olympus migrate status --apply`, which is the only lane that writes
+    # `status` to disk). Set KB_STATUS_AUTOFILL=off to restore the conservative
+    # pre-#147 behavior (a status-less doc is served but never in-force). This
+    # intentionally reverses the #114 "never guess status" stance: for the narrow
+    # legacy-upgrade case, a seamless default beats conservative flagging.
+    status_autofill: bool = True
     # Streamable-http session reaping: terminate transports idle beyond this many
     # seconds to bound _server_instances (see session_metrics). 0 disables the
     # reaper (observability-only). The scan runs every session_reap_interval_sec.
@@ -136,6 +149,27 @@ class Config:
     # peer, ONLY safe when nothing untrusted can reach the port directly) to make
     # the rate limiter see the true client IP behind the proxy. See docs/serving.md.
     trusted_proxies: list[str] = field(default_factory=list)
+    # Public hostnames the reverse proxy presents in the Host header
+    # (KB_PUBLIC_HOSTNAMES, comma-separated). Mapped to fastmcp's Host-header
+    # allowlist when the HTTP app is built (see server.main). Empty (default)
+    # leaves fastmcp reading its own FASTMCP_HTTP_ALLOWED_HOSTS env knob, so
+    # behaviour is unchanged for existing deployments. This exists so operators
+    # configure data-olympus directly (`KB_*`) rather than reaching for the
+    # fastmcp dependency's env var. Getting it wrong is the silent-breakage shape
+    # that caused the 2026-07-09 kn-dev 421 outage: host-protection on + a public
+    # bind + no allowed host -> every proxied request 421s while readiness stays
+    # green (direct pod probes pass). See docs/serving.md and server._resolve_allowed_hosts.
+    public_hostnames: list[str] = field(default_factory=list)
+    # Periodic "a newer version is published" check (issue #146 / KNA-68).
+    # ``disable_version_check`` (KB_DISABLE_VERSION_CHECK, default off) makes an
+    # air-gapped deployment do ZERO outbound calls: the background task is not
+    # spawned at all. When enabled, the task runs once every
+    # ``version_check_interval_sec`` (default 24h) on a worker thread and caches
+    # the result on ServerState; the /api/v1/health route only READS the cached
+    # value, never the network (a blocking urllib lookup on the async request
+    # path would freeze the event loop for the timeout and stall readiness).
+    disable_version_check: bool = False
+    version_check_interval_sec: int = 86400
 
 
 def _split_csv(raw: str) -> list[str]:
@@ -220,6 +254,10 @@ def load_config() -> Config:
     maintenance_expiring_soon_days = int(
         os.getenv("KB_MAINTENANCE_EXPIRING_SOON_DAYS", "30")
     )
+    # KB_STATUS_AUTOFILL defaults to on (issue #147 / KNA-69): a legacy corpus
+    # missing `status` keeps its in-force docs after upgrade. Any explicit
+    # non-truthy value (off/0/false/no) restores the conservative behavior.
+    status_autofill = _env_bool(os.getenv("KB_STATUS_AUTOFILL", "on"))
     session_idle_timeout_sec = int(os.getenv("KB_SESSION_IDLE_TIMEOUT_SEC", "300"))
     session_reap_interval_sec = int(os.getenv("KB_SESSION_REAP_INTERVAL_SEC", "60"))
     session_touch_interval_sec = int(os.getenv("KB_SESSION_TOUCH_INTERVAL_SEC", "30"))
@@ -250,6 +288,11 @@ def load_config() -> Config:
     emb_enabled = _embeddings_enabled()
     emb_cfg = _embeddings_config()
     trusted_proxies = _split_csv(os.getenv("KB_TRUSTED_PROXIES", ""))
+    public_hostnames = _split_csv(os.getenv("KB_PUBLIC_HOSTNAMES", ""))
+    disable_version_check = _env_bool(os.getenv("KB_DISABLE_VERSION_CHECK", ""))
+    version_check_interval_sec = int(
+        os.getenv("KB_VERSION_CHECK_INTERVAL_SEC", "86400")
+    )
     return Config(
         kb_main_path=Path(os.environ.get("KB_MAIN_PATH", "/kb-main")),
         kb_index_path=Path(os.environ.get("KB_INDEX_PATH", "/index/kb.db")),
@@ -285,6 +328,7 @@ def load_config() -> Config:
         maintenance_ledger_path=maintenance_ledger_path,
         maintenance_recently_expired_days=maintenance_recently_expired_days,
         maintenance_expiring_soon_days=maintenance_expiring_soon_days,
+        status_autofill=status_autofill,
         session_idle_timeout_sec=session_idle_timeout_sec,
         session_reap_interval_sec=session_reap_interval_sec,
         session_touch_interval_sec=session_touch_interval_sec,
@@ -302,4 +346,7 @@ def load_config() -> Config:
         embeddings_weight=emb_cfg.weight,
         embeddings_model=emb_cfg.model_name,
         trusted_proxies=trusted_proxies,
+        public_hostnames=public_hostnames,
+        disable_version_check=disable_version_check,
+        version_check_interval_sec=version_check_interval_sec,
     )

{data_olympus-0.4.2 → data_olympus-0.5.0}/src/data_olympus/health.py

@@ -53,6 +53,13 @@ class HealthState:
     # NOT flip ``degraded``; a superseded doc silently losing its own status
     # flip is a governance data-quality signal, not a service failure.
     graph_excluded_docs: int = 0
+    # Latest published version cached by the periodic version-check background
+    # task (issue #146 / KNA-68). None until the first check completes, or
+    # forever when the check is disabled (KB_DISABLE_VERSION_CHECK) or offline.
+    # The health route only READS this cache; it never touches the network, so a
+    # slow/unreachable PyPI can never stall the async request path.
+    latest_version: str | None = None
+    update_available: bool = False
 
 
 def snapshot(
@@ -74,6 +81,8 @@ def snapshot(
     last_successful_refresh_at: float | None = None,
     remote_head_sha: str | None = None,
     live_sessions: int | None = None,
+    latest_version: str | None = None,
+    update_available: bool = False,
 ) -> HealthState:
     """Compose a HealthState from the index and the last-pull/push timestamps.
 
@@ -127,4 +136,6 @@ def snapshot(
         malformed_frontmatter=malformed_frontmatter,
         malformed_validity=malformed_validity,
         graph_excluded_docs=graph_excluded_docs,
+        latest_version=latest_version,
+        update_available=update_available,
     )

{data_olympus-0.4.2 → data_olympus-0.5.0}/src/data_olympus/index.py

@@ -219,6 +219,15 @@ _DEFAULT_STATUS_WEIGHTS: dict[str, float] = {
 # source (format.validate.IN_FORCE_STATUSES); do not hand-list statuses here.
 _IN_FORCE_STATUS_LIST: tuple[str, ...] = tuple(sorted(IN_FORCE_STATUSES))
 
+# Virtual status autofill (issue #147 / KNA-69). The default status written IN
+# MEMORY into the SQLite `docs.status` column for a legacy doc that has no
+# `status` field, when autofill is enabled for the index. `active` preserves the
+# pre-0.4.0 in-force behavior (it is in format.validate.IN_FORCE_STATUSES). The
+# markdown source file is untouched by the build; the same default is written to
+# disk only by the explicit `data-olympus migrate status --apply` lane
+# (data_olympus.status_migrate.DEFAULT_STATUS, kept in sync with this value).
+DEFAULT_AUTOFILL_STATUS = "active"
+
 # Generic, deployment-neutral default taxonomy. A deployment with a different
 # directory layout supplies its own table at runtime via KB_TAXONOMY_PATH (a
 # JSON file holding a list of [prefix, tier, category] triples). The two
@@ -647,8 +656,18 @@ class Index:
         maintenance_ledger_path: str = DEFAULT_LEDGER_PATH,
         maintenance_recently_expired_days: int = DEFAULT_RECENTLY_EXPIRED_DAYS,
         maintenance_expiring_soon_days: int = DEFAULT_EXPIRING_SOON_DAYS,
+        status_autofill: bool = True,
     ) -> None:
         self._db_path = db_path
+        # Virtual status autofill (issue #147 / KNA-69). When True (default), a
+        # doc missing `status` is indexed with `docs.status` = active IN MEMORY,
+        # so a pre-0.4.0 corpus keeps its in-force docs after upgrade without the
+        # build ever touching the markdown source. The physical missing-status
+        # gap is still reported by the maintenance ledger (DocAuditRow carries the
+        # PHYSICAL status), so the ledger keeps nagging until an operator runs
+        # `data-olympus migrate status --apply`. Off restores the conservative
+        # pre-#147 behavior (a status-less doc is served but never in-force).
+        self._status_autofill = status_autofill
         # Embeddings (issue #42) are threaded in from Config, NOT re-read from env
         # here (reviewer concern 2): Config (via load_config) is the single source
         # of truth for KB_EMBEDDINGS_MODE/MODEL/WEIGHT. ``embeddings`` being non-
@@ -1090,6 +1109,11 @@ class Index:
                         "block was treated as absent for this doc",
                         rel,
                     )
+                # The maintenance ledger audits the PHYSICAL corpus, so it records
+                # the doc's real (pre-autofill) status: a legacy doc missing
+                # `status` still counts as missing here, so the ledger keeps
+                # nagging until an operator runs `migrate status --apply`, even
+                # while virtual autofill (below) serves it as in-force.
                 maintenance_rows.append(
                     DocAuditRow(
                         path=str(rel), id=doc_id, status=doc.status,
@@ -1097,6 +1121,21 @@ class Index:
                         is_reserved=rel.name in RESERVED,
                     )
                 )
+                # Virtual status autofill (issue #147 / KNA-69): a legacy doc
+                # missing `status` is indexed as `active` IN MEMORY only (this
+                # SQLite column, never the markdown source), so a pre-0.4.0 corpus
+                # keeps its in-force docs after upgrade. Gated on the per-index
+                # ``_status_autofill`` flag; off restores the conservative
+                # served-but-never-in-force behavior. A reserved filename
+                # (index.md/log.md/template.md) is exempt from the status schema
+                # requirement, so it is NOT autofilled (it never needed a status).
+                indexed_status = doc.status
+                if (
+                    self._status_autofill
+                    and not doc.status
+                    and rel.name not in RESERVED
+                ):
+                    indexed_status = DEFAULT_AUTOFILL_STATUS
                 path_tier, path_category = _classify_by_path(str(rel), path_rules)
                 final_tier = doc.tier or path_tier
                 final_category = doc.category or path_category
@@ -1118,7 +1157,7 @@ class Index:
                     "valid_from, valid_until, last_verified, recheck_by, verification_source, "
                     "is_inbox) "
                     "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
-                    (doc_id, str(rel), final_tier, final_category, doc.status, doc.doc_type,
+                    (doc_id, str(rel), final_tier, final_category, indexed_status, doc.doc_type,
                      applies_when_str, doc.description, doc.title, tags_str, content_markdown,
                      last_modified, lm_source, doc.git_remote_url,
                      doc.valid_from or None, doc.valid_until or None,