fix: preserve resync absence and profile admission safety (#364)

* fix: preserve resync absence and profile admission safety

* fix: retain admission spelling and retry baseline reads

* fix(agent-spec): key refresh cache by declared module path

* fix(agent-spec): key cache by containment spelling

---------

Co-authored-by: Johannes Schickling <schickling.j@gmail.com>

Author: schickling-assistant

crates/agent-spec/src/profile.rs

@@ -1,4 +1,4 @@
-# Resync events ride the built-in stream with occurrence-scoped digest identity
+# Resync events ride the built-in stream with occurrence-scoped carrier-state identity
 
 Status: accepted
 
@@ -94,6 +94,30 @@ occurrence store.
 Q13 contract. The composition experiment records these tests as the direct
 evidence.
 
+## Amendment — 2026-08-27 (Q21)
+
+Johannes approved decision request Q21 to make carrier absence an observable
+state rather than an unreadable digest. A subscription now records
+`present(<digest>)` or `missing`. A proven present→missing transition emits a
+canonical tombstone (`old: <digest>`, `new: missing`), and missing→present
+emits a creation even if the recreated bytes have the same digest as before
+deletion. Repeated missing observations remain silent.
+
+Only `ENOENT` and a stable non-regular replacement establish `missing`.
+Permission and transient I/O failures retain the last proven state, emit a
+diagnostic, and retry. Failed delivery retains the exact carrier-state
+transition body, occurrence, and identity; a newer observation is considered
+only after that immutable reservation completes. Per-binding supersession and
+shared-carrier subscriber independence remain unchanged.
+
+`deletion_and_same_byte_recreation_are_distinct_carrier_transitions`,
+`initial_transient_read_failure_schedules_a_baseline_retry`,
+`transient_permission_error_retries_without_emitting_a_tombstone`,
+`fifo_carrier_is_rejected_without_blocking`,
+`failed_tombstone_emit_retains_present_state_and_immutable_retry_snapshot`,
+and the existing shared-subscriber occurrence tests prove the Q21 contract.
+
+
 ## Options
 
 | Option | Result | Reason |

docs/vrs/.decisions/0008-resync-events-ride-the-built-in-stream.md

@@ -39,15 +39,29 @@ Q13 occurrence identity is covered by four focused unit tests in
 4. `repeated_identical_transitions_receive_distinct_occurrence_identities` —
    drives A→B, B→A, A→B through the real event ingress and proves the repeated
    A→B legs have distinct IDs and subscription sequences 1 and 3.
-5. `failed_emit_retains_digest_and_schedules_the_same_transition_for_retry` —
-   proves a failed retry retains the exact immutable body, event ID, and
-   sequence.
+5. `failed_tombstone_emit_retains_present_state_and_immutable_retry_snapshot` —
+   proves a failed tombstone retains the exact immutable body, event ID, state,
+   and sequence across same-byte recreation.
 6. `subscribers_advance_occurrence_sequences_independently` — proves two
    subscriptions each capture their first transition at sequence 1.
 7. `supervisor_restart_incarnation_changes_the_occurrence_namespace` — proves
    an incarnation change produces a different body and ID even when the
    per-subscription sequence and digest transition repeat.
 
+Q21 carrier-state semantics are covered by three additional focused tests:
+
+8. `deletion_and_same_byte_recreation_are_distinct_carrier_transitions` —
+   proves present→missing emits `old: <digest>` / `new: missing`, repeated
+   missing stays silent, and same-byte recreation emits missing→present as the
+   next occurrence while superseding the tombstone.
+9. `initial_transient_read_failure_schedules_a_baseline_retry` and
+   `transient_permission_error_retries_without_emitting_a_tombstone` prove an
+   initial or later permission failure retains unknown/prior state and
+   schedules retry; after access recovers, baseline seeding or the real byte
+   transition completes without an intermediate tombstone.
+10. `digesting_a_fifo_fails_without_blocking_the_worker` — proves both native
+    and confined readers classify a FIFO as stable missing without blocking.
+
 Three design constraints were discovered by running the code, not by reasoning:
 
 - **Directory-creation blind spot.** Writing a file into a newly created
@@ -68,21 +82,25 @@ Three design constraints were discovered by running the code, not by reasoning:
 
 ## Result
 
-The three integration tests and focused resync unit suite pass, including the
-four Q13 occurrence tests. Pre-existing suite results remain recorded in the
-PR description; unrelated formatting drift was left untouched.
+The default resync unit slice passed 31 tests, including every Q13/Q21 state,
+retry, shared-subscriber, and confinement case. The default Agent Spec suite
+passed 78 tests, and the `wasm-resolver` Agent Spec suite passed 110 unit,
+integration, and hostile-module tests. The real resync integration suite passed
+three default and five wasm-enabled filesystem/inbox cases. Pre-existing
+warnings were unchanged.
 
 ## Conclusion
 
 The composition holds without new delivery semantics: DING, archive, ring
-dedup, and supersession are inherited untouched. The two discoveries above are
-now pinned by the tests that exposed them.
+dedup, and supersession are inherited untouched. Carrier absence is now a
+first-class transition without turning transient read failures into false
+tombstones.
 
 ## VRS Impact
 
 Supports [`06-resync/requirements.md`](../../06-resync/requirements.md)
-RESYNC-R01/R03/R04/R06/R07 and [`spec.md`](../../06-resync/spec.md). The Q13
-evidence supports the approved RESYNC-R06 occurrence-identity amendment and
-decision record 0008. The catalog-relative resource URI form remains an st2
-extension pending canonical Agent Spec adoption (noted in
+RESYNC-R01/R03/R04/R06/R07 and [`spec.md`](../../06-resync/spec.md). The
+Q13/Q21 evidence supports the approved RESYNC-R06 occurrence and carrier-state
+amendments to decision record 0008. The catalog-relative resource URI form
+remains an st2 extension pending canonical Agent Spec adoption (noted in
 [`02-agent-spec`](../../02-agent-spec/requirements.md) terms).

docs/vrs/06-resync/.experiments/2026-08-25-resync-composition.md

@@ -51,9 +51,10 @@ root [`R05`](../requirements.md); Resource bindings are defined by
   provisional constants tuned by observation, per the rollout note in
   [issue #341](https://github.com/compoundingtech/st2/issues/341).
 - **RESYNC-T03 No catch-up:** Like any restarted stream, a restarted
-  supervisor re-observes current digests silently and emits only subsequent
-  changes. Changes missed while the supervisor was down are discovered by the
-  agent's own next read or by reconcile, not reconstructed as events.
+  supervisor re-observes current carrier state silently and emits only
+  subsequent changes. Changes missed while the supervisor was down are
+  discovered by the agent's own next read or by reconcile, not reconstructed
+  as events.
 
 ## Requirements
 
@@ -70,9 +71,11 @@ root [`R05`](../requirements.md); Resource bindings are defined by
   watches and why, denies everything else by default, ignores read/open
   access events, and never traverses payload trees — refining [`R14`](../requirements.md)
   and the mutation-only wakeup invariant.
-- **RESYNC-R03 Seeded baseline:** On supervisor start the current digest of
-  every watchable carrier is recorded without emitting. Only a transition
-  between observed contents produces an event; a restart alone wakes nobody.
+- **RESYNC-R03 Seeded baseline:** On supervisor start every watchable carrier
+  is recorded as either `present(<content-digest>)` or `missing` without
+  emitting. Only a transition between proven states produces an event; a
+  restart alone wakes nobody. Permission and transient I/O failures establish
+  neither state and are retried rather than interpreted as absence.
 
 ### Must classify before notifying
 
@@ -92,19 +95,21 @@ root [`R05`](../requirements.md); Resource bindings are defined by
 
 ### Must emit honest, deduplicated events
 
-- **RESYNC-R06 Event shape and occurrence identity:** One carrier change
+- **RESYNC-R06 Event shape and occurrence identity:** One carrier state change
   becomes one stream event on the built-in `resync` stream: subject
   `resource <binding> changed`, body naming the binding label, resolved path,
-  old and new content digests, and an occurrence token. The token combines
-  the current supervisor incarnation — catalog-lock device/inode plus
-  supervisor PID/start-time ticks — with a sequence retained independently by
-  each subscription. A subscription advances its sequence only when it
-  captures a new immutable transition; a failed publication retries the same
-  body, token, and identity. The event identity is the SHA-256 of that
-  canonical rendered body. Thus replay is stable, while A→B, B→A, A→B gives
-  the repeated A→B legs distinct identities. The grouping key is the binding
-  label; every emit declares supersession so a binding collapses to one unread
-  head.
+  old and new carrier states, and an occurrence token. A present state renders
+  as its content digest and absence renders canonically as `missing`, so
+  deletion and recreation are observable even when recreated bytes equal the
+  prior bytes. The token combines the current supervisor incarnation —
+  catalog-lock device/inode plus supervisor PID/start-time ticks — with a
+  sequence retained independently by each subscription. A subscription
+  advances its sequence only when it captures a new immutable transition; a
+  failed publication retries the same body, token, and identity. The event
+  identity is the SHA-256 of that canonical rendered body. Thus replay is
+  stable, while repeated state-transition legs receive distinct identities.
+  The grouping key is the binding label; every emit declares supersession so a
+  binding collapses to one unread head.
 - **RESYNC-R07 Built-in stream:** The `resync` stream exists on every agent
   without declaration and is reserved: a user-declared stream of that name is
   refused. Only the supervisor's crate-internal publisher admits the built-in
@@ -113,12 +118,13 @@ root [`R05`](../requirements.md); Resource bindings are defined by
   supersession semantics, inbox transport, and DING `»` marker inherited from
   [`STREAM-R03..R07`](../04-stream/requirements.md).
 - **RESYNC-R08 Lifecycle honesty:** No events accumulate for suspended or
-  retired agents. Digest seeding happens when a seat launches or resumes, so
-  resume re-observes current state silently and only later transitions notify.
+  retired agents. Carrier-state seeding happens when a seat launches or
+  resumes, so resume re-observes current state silently and only later
+  transitions notify.
 
 ## Evidence
 
-The composition (parent-directory watch → classification → digest-keyed
-superseded emit → DING wake) is proven by integration tests introduced with
-the implementation; see [`.experiments/`](./.experiments/) for the record
-and the pre-existing failure baseline it was verified against.
+The composition (parent-directory watch → classification → carrier-state-keyed
+superseded emit → DING wake) is proven by integration tests introduced with the
+implementation; see [`.experiments/`](./.experiments/) for the record and the
+pre-existing failure baseline it was verified against.

docs/vrs/06-resync/requirements.md

@@ -16,7 +16,7 @@ writer (Nix activation / tool / agent)
    v  inotify mutation on the parent directory (non-recursive)
 resync watcher thread
    |- classify carrier: immediate | silent | coalesced
-   |- digest new bytes (sha256), compare to seeded/last digest
+   |- observe present(sha256) | missing; compare to seeded/last state
    '- equal → nothing; changed → queue per class window
    |
    v  window boundary
@@ -84,26 +84,29 @@ meaningful.
   launched/restarted in that pass. Desired declarations, dead keep-retained
   seats, and companion-only launches never become watched. If strict discovery
   temporarily rejects a declaration whose exact canonical seat remains
-  observed alive, its prior declaration subscription survives with its digest
-  and pending transition; it drops as soon as that seat is not live. Existing
-  valid subscriptions are matched by declaration path and binding label. Each
-  refresh takes bus id, canonical seat id, carrier path, label, and class from
-  the current declaration while retaining digest, the per-subscription
-  occurrence sequence, any immutable pending transition, and dirty state; only
-  new subscriptions seed silently with sequence zero.
-- A previously blind path is digest-diffed both before and after its recovered
+  observed alive, its prior declaration subscription survives with its carrier
+  state and pending transition; it drops as soon as that seat is not live.
+  Existing valid subscriptions are matched by declaration path and binding
+  label. Each refresh takes bus id, canonical seat id, carrier path, label, and
+  class from the current declaration while retaining carrier state, the
+  per-subscription occurrence sequence, any immutable pending transition, and
+  dirty state; only new subscriptions seed silently with sequence zero.
+- A previously blind path is state-diffed both before and after its recovered
   parent watch is registered, closing the poll-to-registration gap.
-- Installation failure degrades to timer-based digest polling over the watch
+- Installation failure degrades to timer-based carrier polling over the watch
   set (bounded by the number of bindings), never to silence about the
   mechanism. Polling only marks observed changes dirty and schedules the
   carrier's ordinary class deadline; it neither bypasses coalescing nor emits
   ahead of an immutable pending transition.
 - A runtime watcher-backend error may mean mutation events were dropped, so it
   schedules every changed carrier through the same pending-aware classified
-  path. Equal digests remain silent.
-- Digest reads open carriers nonblocking, accept regular files only, and feed
-  bytes incrementally into SHA-256 with bounded memory; FIFOs, other special
-  files, and large carriers cannot stall or exhaust the worker.
+  path. Equal states remain silent.
+- Reads open carriers nonblocking and without following the final symlink
+  (every component for confined carriers). A proven regular file becomes
+  `present(<sha256>)`; `ENOENT` or a stable non-regular replacement becomes
+  `missing`. Permission and transient I/O errors are diagnosed and retried
+  without changing state. FIFOs and other special files therefore cannot stall
+  the worker and produce one tombstone transition rather than silent ambiguity.
 
 ## Built-in stream
 
@@ -120,18 +123,24 @@ grammar (1..=200 bytes, no surrounding whitespace or controls), and
 `declaration` is reserved for the synthetic declaration carrier so supersession
 keys cannot collide.
 
-Digest and occurrence-sequence state live with the supervisor process (seeded
-at start) and have no durable store, consistent with RESYNC-T03. A captured
-transition gets an occurrence token
+Carrier state and occurrence-sequence state live with the supervisor process
+(seeded at start) and have no durable store, consistent with RESYNC-T03. A
+carrier state is `present(<sha256>)` or `missing`. Present→missing emits a
+canonical tombstone whose body contains `old: <digest>` and `new: missing`;
+missing→present emits a creation even when that digest matches the bytes from
+before deletion. Repeated missing observations are silent.
+
+A captured transition gets an occurrence token
 `v1:<catalog-lock-dev>:<catalog-lock-inode>:<supervisor-pid>:<supervisor-start-time-ticks>:<subscription-sequence>`
 in its canonical body before that body is hashed for the event ID. Each
 subscription advances its sequence only when capturing a new immutable
-transition. Failed publication retains the old digest, exact target digest,
+transition. Failed publication retains the old state, exact target state,
 canonical body, occurrence token, and event ID; retry replays those bytes
-before observing a newer carrier digest. Repeated A→B legs therefore remain
-distinct occurrences, while a retry remains the same reservation. A supervisor
-restart changes the incarnation namespace and silently seeds new subscription
-sequences. The durable dedup horizon remains the stream receipt ring.
+before observing newer carrier state. Repeated transition legs therefore
+remain distinct occurrences, while a retry remains the same reservation. A
+supervisor restart changes the incarnation namespace and silently seeds new
+subscription sequences. The durable dedup horizon remains the stream receipt
+ring.
 
 ## What this does not do
 

docs/vrs/06-resync/spec.md

@@ -165,6 +165,32 @@ The evidence therefore supports a **wasm-only, feature-gated foundation** behind
 the chosen registry/SDK seam. The dependency and binary cost is real and is why
 the feature gate is constitutional, not optional cleanup.
 
+### Admission-key cache safety follow-up
+
+**Hypothesis:** A path-only refresh cache can reuse an externally admitted
+module for a catalog-relative declaration of the same absolute spelling,
+bypassing descriptor-relative no-follow traversal.
+
+**Method:** Resolve a module through a symlinked parent as an external profile,
+then resolve the same spelling as catalog-relative in one refresh. Separately,
+resolve one regular module under external and contained policies through
+registry clones and replace module bytes between refreshes.
+
+**Result:** `cache_normalization_does_not_change_the_path_used_for_admission`
+proves lexical normalization cannot erase filesystem-significant `..` after a
+symlink because admission still opens the declared spelling.
+`refresh_cache_cannot_reuse_external_admission_for_a_contained_module` proves
+the second resolution re-opens and rejects the symlink.
+`registry_clones_share_compilation_only_with_the_same_admission_policy` proves
+clones share one compilation within a policy and retain separate cache entries
+across policies. The existing replacement test proves a changed identity still
+invalidates its entry. The complete `wasm-resolver` Agent Spec suite passed 110
+tests.
+
+**Conclusion:** Snapshot outcomes and compiled success/failure entries require
+one key: normalized module path plus external-or-exact-confinement-root policy,
+then file identity. Path identity alone is not an authorization boundary.
+
 ## VRS Impact
 
 Supports [`PROFILE-R01..R08`](../requirements.md) and the sandbox/ABI sections