feat(knowledge): retire missing directory members

docs/adr/0007-portable-candidate-knowledge-store.md

@@ -50,8 +50,8 @@ add-members operation can append unmatched accepted files from an existing
 binding as new managed file sources and immutable members in deterministic path
 order; existing member states remain report-only and a later candidate failure
 returns a path-free partial result. Applied refresh is limited to existing
-active same-member changed files; directory removals, root rebind, rename, and
-member-retirement policy remain deferred. The membership is a stable historical
+active same-member changed files; complete removal reconciliation, root rebind,
+rename, and broader member-retirement policy remain deferred. The membership is a stable historical
 mapping captured at binding or explicit append time: later source version
 appends, explicit origin rebinding, or source retirement do not rewrite its
 rows, and actual incremental scan reconciliation remains deferred.
@@ -192,7 +192,15 @@ source. Each source, version, canonical origin binding, managed blob, journal
 commit, and immutable directory member is committed atomically per candidate;
 the operation stops on the first later failure and returns only path-free
 partial IDs. It does not create observations for new members or infer renames,
-removals, rebinding, or retirement.
+removals, rebinding, or retirement. An explicit approved directory-member
+retirement operation performs one fresh bounded scan and accepts only an active
+same-member `missing` member. It atomically records the existing
+`user-requested` retirement marker with latest-version, origin-revision, and
+chronology guards. Its path-free `removed` result means logical retirement, not
+physical deletion; an already retired member returns `already-removed` without
+a write. Bytes, versions, origin bindings, observations, journal state, and
+immutable membership remain, while complete reconciliation, cleanup, and broader
+lifecycle policy remain deferred.
 SQLite migration v13 stores the opaque directory binding and immutable hashed
 members in separate local-only tables with same-CKB foreign-key scope; there is
 no backfill of earlier runtime-only imports.
@@ -392,9 +400,11 @@ configuration. Its original filename is not used in the managed layout.
 
 This decision deliberately leaves the following work unintegrated:
 
-- directory removals, directory rebind, rename/removal, and member retirement
-  policy (the explicit add-members operation handles only unmatched additions,
-  while applied refresh handles only existing active same-member changed files);
+- complete directory removal reconciliation, directory rebind, rename/removal,
+  and broader member-retirement policy (the explicit operation handles only one
+  approved missing same-member member; add-members handles only unmatched
+  additions, while applied refresh handles only existing active same-member
+  changed files);
 - redirect-observation history, conditional URL requests, and URL-specific
   failure or time-based readiness policy;
 - background refresh, time-based freshness policy, moved-origin discovery, and

docs/architecture.md

@@ -215,7 +215,8 @@ fallback. See [ADR 0004](adr/0004-desktop-credential-boundary.md).
   mapping captured at binding or explicit append time:
   later source version appends, explicit origin rebinding, or source retirement
   do not rewrite it. Incremental directory scan reconciliation, directory
-  rebind, rename, removal, and member-retirement policy remain unimplemented.
+  rebind, rename, complete removal reconciliation, and broader member-retirement
+  policy remain unimplemented.
   A local explicit bounded refresh preview can classify historical members as
   `current`, `changed`, `missing`, `retired`, or `origin-conflict` and count
   unmatched accepted files. It exposes no paths or integrity metadata and makes
@@ -242,8 +243,16 @@ fallback. See [ADR 0004](adr/0004-desktop-credential-boundary.md).
   each file source, initial version, sensitive origin binding, managed blob,
   journal event, and immutable membership atomically per candidate. Existing
   member states are report-only, new members receive no refresh observation, and
-  removals, renames, root rebind, automatic retirement/deletion, and writer
+  complete removal reconciliation, renames, root rebind, automatic retirement/deletion, and writer
   coordination remain deferred.
+- An explicit approved directory-member retirement operation reuses one complete
+  bounded scan and accepts only an active same-member `missing` member. It
+  atomically records the existing `user-requested` retirement marker with
+  latest-version, origin-revision, and chronology guards. `removed` means
+  logical retirement only: bytes, versions, origin bindings, observations,
+  journal state, and immutable membership remain; an already retired member
+  returns `already-removed` without a write. Complete directory reconciliation,
+  physical cleanup, and broader lifecycle policy remain deferred.
 - Managed source add and append publish verified bytes without replacement before
   committing their version-6 database marker. Committed markers always require
   matching opaque bytes; file sources retain their additional regular-file and
@@ -438,7 +447,9 @@ last-observation state tied to the exact source version. An
 explicit rebind changes only sensitive local origin configuration after an
 exact latest-managed-version match and exposes no path or integrity metadata.
 New-member persistence is available only through the explicit bounded add-members
-operation; rename/removal decisions, directory-root rebind,
+operation, and explicit missing-member retirement is available only through the
+approved directory-member operation; complete removal reconciliation,
+directory-root rebind,
 automatic retirement/deletion, background refresh, time-based freshness policy,
 automatic moved-origin
 discovery, adapter-level refresh/rebind/duplicate controls, incremental

docs/privacy-and-evaluation.md

@@ -77,10 +77,14 @@ only path-free added source IDs. It creates no refresh observation for new
 members. The explicit bounded applied operation appends
 changed bytes only for active same-member files in source-ID order and records
 current observations for successful changed, current, and same-member-missing
-entries. Rename/removal decisions, root or origin rebind, automatic
-retirement/deletion, adapters, indexing, and background
-refresh remain deferred; a later member failure returns a path-free partial
-result after earlier member commits.
+entries. Complete removal reconciliation, root or origin rebind, automatic
+retirement/deletion, adapters, indexing, and background refresh remain deferred;
+a later member failure returns a path-free partial result after earlier member
+commits. An explicit approved directory-member retirement operation can mark one
+fresh-scan `missing` same-member source as logically removed with the existing
+`user-requested` marker; it does not delete bytes, versions, bindings,
+observations, journal state, or immutable membership. Already retired members
+return an `already-removed` result without a write.
 
 One explicitly approved HTTPS URL can also become an initial managed CKB
 source. The existing controlled URL ingestion boundary validates public address
@@ -160,8 +164,8 @@ canonical origin binding. Partial and legacy runtime-only imports have no
 directory membership evidence. The store has a read-only explicit bounded
 directory refresh preview, an explicit add-members operation, and an applied
 operation limited to existing active same-member changed files. Add-members
-persists only unmatched accepted files as append-only new members; rename/removal
-decisions, directory-root rebind, automatic retirement/deletion, background
+persists only unmatched accepted files as append-only new members; complete
+removal reconciliation, directory-root rebind, automatic retirement/deletion, background
 refresh, time-based freshness policy, moved-origin
 discovery, automatic duplicate resolution, normalized facts, or retrieval
 indexes. A read-only, one-CKB-scoped duplicate projection compares only latest

docs/roadmap.md

@@ -182,7 +182,8 @@ directory-root binding plus immutable SHA-256 membership hashes for accepted
 files, while partial and legacy runtime-only imports have no directory
 membership evidence. The selected root and exact origins remain sensitive local
 state outside generic projections. Incremental removal/rename refresh, root
-rebind, and member-retirement policy remain unimplemented. Membership is a
+rebind, complete removal reconciliation, and broader member-retirement policy
+remain unimplemented. Membership is a
 stable historical mapping captured at binding or explicit append time; later
 source version appends, explicit origin rebinding, or source retirement do not
 rewrite it.
@@ -192,8 +193,8 @@ append unmatched accepted files as new managed file sources and immutable
 members in deterministic path order. Each candidate commits its source,
 version, origin binding, managed bytes, journal event, and membership atomically;
 later failures return path-free partial added IDs, and new members receive no
-refresh observations. Removal, rename, root rebind, and member-retirement
-policy remain deferred.
+refresh observations. Complete removal reconciliation, rename, root rebind, and
+broader member-retirement policy remain deferred.
 An explicit local bounded read-only refresh preview now revalidates the stored
 root, repeats the intake preflight, and returns path-free `current`, `changed`,
 `missing`, `retired`, or `origin-conflict` member states plus an aggregate count
@@ -202,7 +203,13 @@ observation, or lifecycle writes; scan-level unreadable, unstable, limit, and
 extraction failures fail closed. Applied refresh is limited to existing active
 same-member changed files; rename/removal decisions, member-retirement lifecycle,
 directory-root rebind, automatic retirement/deletion, adapters, indexing, and
-background refresh remain deferred.
+background refresh remain deferred. An explicit approved directory-member
+retirement operation can mark one active same-member `missing` source as
+logically removed using the existing `user-requested` retirement marker after
+latest-version, origin-revision, and chronology guards. It returns path-free
+`removed` or `already-removed`; it does not delete bytes, versions, bindings,
+observations, journal state, or immutable membership. Complete directory
+reconciliation and physical cleanup remain deferred.
 An explicit bounded observation-only directory refresh now reuses one complete
 scan and atomically records path-free `current`, `changed`, and same-member
 `missing` observations with one shared timestamp. Retired, origin-conflict, and
@@ -264,7 +271,8 @@ captured at binding or explicit append time and is not rewritten by later source
 versioning, explicit origin rebinding, or retirement. Directory rebind,
 rename/removal lifecycle,
 and incremental scan reconciliation remain deferred. The read-only preview,
-bounded existing-member applied refresh, and explicit add-members operation are
+  bounded existing-member applied refresh, explicit add-members operation, and
+  explicit missing-member retirement are
 component implementations only; the v0.7 stage remains at component
 implementation.
 Journal records exclude origin paths, filenames, labels, checksums, source content,
@@ -577,6 +585,7 @@ model above controls current stage claims.
 
 | Date       | Change                                                                                                                                                                                                                                       | Reason                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-08-23 | Added explicit bounded logical retirement of one missing directory member as the thirteenth #110 slice without advancing the v0.7 stage beyond component implementation                                                                 | A fresh bounded scan can now approve one active same-member missing source for guarded insertion of the existing user-requested retirement marker; results distinguish logical removed from already-removed, preserve all bytes and immutable membership, and leave complete reconciliation, physical cleanup, adapters, indexing, and background refresh pending. |
 | 2026-08-23 | Added explicit bounded directory member addition as the twelfth #110 slice without advancing the v0.7 stage beyond component implementation                                                                                                  | One complete scan of an existing binding can now append unmatched accepted files as independent managed sources and immutable hashed members in lexical path order, one candidate atomically at a time, with path-free added IDs and partial results; refresh observations, rename/removal, root rebind, retirement, adapters, indexing, and background refresh remain pending. |
 | 2026-08-23 | Added explicit applied bounded directory refresh for existing active same-member files as the eleventh #110 slice without advancing the v0.7 stage beyond component implementation                                                                 | One complete local scan can now append changed bytes in deterministic source-ID order through guarded managed-file publication, persist current observations for successful changed/current/missing members, and return a path-free partial result after a later member failure; new-member persistence, reconciliation, lifecycle, adapters, indexing, and background refresh remain pending. |
 | 2026-08-23 | Added explicit bounded directory observation recording as the tenth #110 slice without advancing the v0.7 stage beyond component implementation                                                                                              | One complete local scan can now atomically persist path-free current/changed/same-member-missing observations for eligible active members with one checked-at timestamp; retired, origin-conflict, and new files remain report-only, and changed-byte application, new-member persistence, reconciliation, lifecycle, adapters, indexing, and background refresh remain pending.                                                                                                                                            |