instar 1.3.820 → 1.3.822

package/upgrades/side-effects/cartographer-streaming-ls-tree.md

@@ -0,0 +1,80 @@
+# Side-Effects Review — Cartographer streaming ls-tree
+
+**Version / slug:** `cartographer-streaming-ls-tree`  
+**Date:** `2026-07-11`  
+**Author:** `instar-codey`  
+**Second-pass reviewer:** `framework_guard_review`
+
+## Summary
+
+The cartographer detect module replaces its buffered `git ls-tree` read with a guarded streaming child process and incremental NUL parser. `runDetect` is now asynchronous so both the default worker and the in-process rollback can await subprocess completion. No scaffold writer, index storage, heap ordering, writer ownership, or rollout setting changes.
+
+## Decision-point inventory
+
+- Git completion — modify — the map is accepted only on clean exit with a fully terminated NUL stream.
+- Git failure — pass-through — every failure shape still becomes `detect-git-error` and feeds the existing breaker.
+- `gitMaxBuffer` — pass-through — accepted and plumbed for config compatibility, intentionally ignored by the streaming reader.
+
+## Over-block / under-block
+
+Malformed output with an unterminated last record now refuses rather than accepting an ambiguous tail. Valid empty-tree output remains successful. The parser's carry can grow to one Git path record; the unavoidable output map remains O(tree entries) because downstream status comparison requires it, but there is no second whole-output string or split array.
+
+## Level of abstraction
+
+`SafeGitExecutor.readStream` extends the existing guarded Git funnel so classification, source-tree protection, environment scrubbing, and audit behavior are preserved. Incremental record parsing remains in `cartographerDetect`, the owner of ls-tree semantics. The worker boundary remains unchanged and default-on.
+
+## Signal vs authority
+
+No new authority is introduced. Git failure remains a named refusal signal consumed by the existing sweep breaker; partial data never reaches candidate selection.
+
+## Judgment-point check
+
+No new static heuristic at a competing-signals decision point. Child-process success is an enumerable protocol invariant: clean zero exit, no signal, and complete NUL framing.
+
+## Interactions
+
+- Ordering and shape: real-fixture parity freezes the same insertion order and OIDs as the former buffered parser.
+- Backpressure/memory: every stdout chunk is synchronously reduced into complete records; only the current record carry remains between chunks. Stderr capture is capped at 8 KiB.
+- Failure atomicity: the local map is returned only after `close` reports exit code zero and no signal. Mid-stream SIGKILL, non-zero exit, spawn error, and malformed tail reject it.
+- Lifetime: the read-only stream retains the former 30-second subprocess bound and kills on expiry. On worker timeout, the parent requests cooperative child teardown, retains the reported child PID as a fallback, and force-terminates after a 250 ms grace bound.
+- Configuration: `gitMaxBuffer` remains accepted at `ConfigDefaults`, server plumbing, engine config, and `DetectInput`; removing it would be a needless compatibility break.
+- Scope: #1073 items 1 (scaffold writer) and 2 (SQLite/sharding) are untouched and remain open.
+
+## External surfaces
+
+The exported `runDetect` helper now returns a Promise; all repository call sites are updated. Runtime output, snapshot schema, candidate ordering, and persistent state are unchanged. No operator action or external API is added. Timing improves for large Git trees because stdout is reduced as it arrives.
+
+## Operator-surface quality
+
+No operator surface — not applicable.
+
+## Multi-machine posture
+
+Machine-local by design: each machine compares its own checked-out Git tree inside its own detect worker. It emits no user-facing notice, holds no new durable state, strands no topic state, and generates no URL. Existing snapshot behavior is unchanged.
+
+## Rollback
+
+Pure code rollback. No persistent schema or state migration is involved. Reverting restores the explicit 64 MiB buffered floor and its refusal-on-overflow behavior.
+
+## Conclusion
+
+The transport upgrade is contained to #1073 item 3 and preserves the existing authority, writer, worker, ordering, and configuration contracts. Independent review found the first draft had lost the buffered executor's subprocess timeout and could orphan Git when a worker was terminated; the shared timeout and explicit two-level reap protocol now close that gap.
+
+## Second-pass review
+
+**Reviewer:** `framework_guard_review`  
+**Independent read:** concur. The revised stream retains bounded subprocess lifetime in both in-process and worker modes; the real-worker reap proof and funnel/stream suites are green.
+
+## Class-Closure Declaration
+
+`defectClass: unbounded-self-action`, `closure: n/a` — one bounded kill attempt is tied to a single detect-worker timeout; this adds no autonomous retry, respawn, notification, or recurring control loop.
+
+## Evidence
+
+- CI correction: the no-silent-fallbacks heuristic initially counted four
+  intentional error-propagation/terminal-state catches. Each is now explicitly
+  annotated in place; the baseline remains 492 and the exact ratchet is green.
+- Unit: chunk-edge NUL, a Unicode record split across four chunks, real-tree parity, empty tree, output beyond a one-byte legacy setting, mid-stream SIGKILL refusal, and hung-stream timeout.
+- Funnel: read-only streaming succeeds; destructive use is rejected before spawn.
+- Dist worker: forced timeout against a fake hung Git process proves the pass refuses and the reported OS PID is no longer alive.
+- Existing detect refusal, bounded heap, routes, config, and dist-worker suites remain green.

package/upgrades/side-effects/two-node-harness-increment2-entry-gate.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — Two-Node Replication Harness (Increment-2 Entry Gate)
+
+**Version / slug:** `two-node-harness-increment2-entry-gate`
+**Date:** `2026-07-11`
+**Author:** `echo (instar-dev agent)`
+**Second-pass reviewer:** `not required (tests + test-support only; no decision point, no runtime surface)`
+
+## Summary of the change
+
+Implements the Increment-2 entry-gate deliverable of `docs/specs/ownership-gated-spawn-and-judgment-within-floors.md` (§4 line 242: "Entry gate: the two-node replication harness (§5) green in CI"; §5 line 261: the L7 evidence contract). Two new test files only: `tests/support/twoNodeOwnershipHarness.ts` (the reusable two-node factory — durable ownership substrate, un-stubbed signed journal-sync replication, real AgentServer per node) and `tests/e2e/duplicate-reconciliation-two-node.test.ts` (the entry-gate lifecycle + the §5 delayed-replay and partition-formed cases + three spec-anchored `it.todo` scenarios). Plus this artifact, the ELI16 companion, and an internal-only release fragment. **Zero `src/**` changes.**
+
+## Decision-point inventory
+
+*(none — no runtime decision point is added or modified; the harness exercises existing ones)*
+
+## 1. Over-block
+
+Nothing at runtime (no runtime surface). In CI: the new E2E becomes a required-passing test — a future change that breaks the two-machine heal fails CI. That is the deliverable, not a side effect: the spec makes this test THE Increment-2 entry gate.
+
+## 2. Under-block
+
+- The harness runs two nodes IN ONE PROCESS over loopback — partitions are modeled as WITHHELD replication (the §5 partition-formed and delayed-replay cases), not as packet loss/timeout dynamics; clock skew and cross-host filesystem differences are not modeled. The spec's §3.0 consistency contract owns those honesty bounds.
+- The 2b custody-transfer scenario and the terminate-time-probe scenario are `it.todo` — their mechanics are deliberately NOT built in Increment 1/this PR (Increment 2b's own build); the todos carry the spec anchors so they cannot be silently forgotten.
+- The closeout leg asserts the ARMING predicate (the peer's own view says owner-elsewhere) and simulates the close; the full sweeper-close leg lands with the `duplicate-reconciled` reap-reason extension (Increment 2).
+
+## 3. Level-of-abstraction fit
+
+Reuses the three existing proven patterns (journal-sync-roundtrip's replication hop, mesh-failover's two-server shape, the alive-test's real-AgentServer boot) rather than inventing a parallel harness idiom. The node factory lives in `tests/support/` alongside the existing fixture module.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** docs/signal-vs-authority.md — Not applicable at runtime (no new detector or authority). In-CI authority (a failing test blocks merges) is the standard test-suite contract.
+
+## 5. Interactions
+
+- The E2E rides the existing `e2e` CI job (vitest include already covers `tests/e2e/**`) — no workflow changes, no new CI lanes.
+- The harness binds ephemeral loopback ports (port 0) and tmpdir state — no interaction with the host agent's server, state, or config.
+- Discovered interaction (already resolved upstream): building this harness surfaced the record-already-correct FSM refusal (claim-out-of-sequence → escalate-instead-of-heal) — fixed on the Increment-1 PR as the `record-already-converged` skip and unit-tested there; this E2E now proves that fix end-to-end.
+
+## 6. External surfaces
+
+None. No egress (loopback only), no persistent state outside vitest tmpdirs (SafeFsExecutor teardown), no operator surface, no agent-visible capability (hence the internal-only release-note lane).
+
+## 6b. Operator-surface quality
+
+No operator surface — not applicable.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+The change IS the multi-machine test substrate. It runs no agent, replicates no store of its own, and creates no cross-machine surface; it simulates two machines inside one test process to verify the production replication contract (journal → signed envelope → applier → materialized peer view).
+
+## 8. Rollback cost
+
+Delete the two test files (plus docs). Nothing depends on them at runtime. The only cost of rollback is losing the Increment-2 entry gate's objective checkability.
+
+## Rollout-ladder compliance (§4 hard prohibitions)
+
+- NO flag flips: `ownershipGatedSpawn` / `duplicateReconciler` / `judgmentArbiters` / `commitmentCustodyTransfer` untouched; `inboundQueue` / `holdForStability` / stale-owner-release untouched (their own features' graduation decisions, per §4 "inherit-and-stall").
+- NO `provenance.deterministicSampling` change (that is an Increment-2-ENTRY action, riding the actual enforce-flip PR).
+- In-test enforce-mode construction of the reconciler is test construction inside a sandbox, not a rollout-ladder flip (the Increment-1 burst-invariant E2E precedent).
+
+## Conclusion
+
+Tests + test-support only; the risk surface is CI-time, which is the point. Clear to ship as its own PR once Increment 1 merges (it depends on the Increment-1 modules).