@quantiya/codevibe-core 2.0.0 → 2.0.2

package/dist/orchestration-shell/context-store.d.ts

@@ -0,0 +1,389 @@
+import type { StructuralSummary, StructuralSummaryGenerator, RepoSummary } from '../structural-summary/types';
+import type { Tier } from './types';
+/**
+ * Legacy §4.2 staleness fingerprint of the last scan — persisted in
+ * `metadata.json` by schema v1 builds. v2 keeps the same input-hash/content
+ * binding but moves `{HEAD, clean}` to one record per discovered root.
+ *
+ *  - `head` — the git HEAD the cached summary was computed at (conjunct (b)).
+ *    `null` for a non-git tree (a non-git tree never skips — see the probe).
+ *  - `clean` — whether the tree was CLEAN when this summary was computed
+ *    (conjunct (c)). A dirty-tree summary records `clean:false` and is NEVER
+ *    a skip target (Codex r6 H — the dirty→clean-revert false-fresh hole).
+ *  - `summaryInputHash` — a hash over the generation inputs (conjunct (d) —
+ *    tier / body opt-in / user-ignore-file / generator version / caps). A
+ *    mismatch forces a recompute AND a purge of the stale entry (the
+ *    body-inclusion/ZK privacy fail-safe, Codex r7 H).
+ *  - `summarySha256` — the content address of the summary this metadata was
+ *    written FOR (Codex r2 BLOCKING — the crash-atomicity binding). The three
+ *    store files are individually atomic but NOT atomic as a SET; binding the
+ *    metadata to the summary sha lets the loader detect a summary↔metadata
+ *    MISMATCH (e.g. a crash that renamed a new `summary.json` over an OLD
+ *    `metadata.json`). Validated against `summary.sha256` on load (defense in
+ *    depth alongside the `digest.txt` commit-marker ordering).
+ *  - `schemaVersion` — v1 metadata is still loadable for migration, but it is
+ *    never reused as fresh by the v2 probe.
+ */
+export interface LegacyContextStoreMetadata {
+    schemaVersion: 1;
+    head: string | null;
+    clean: boolean;
+    summaryInputHash: string;
+    summarySha256: string;
+    writtenAt: string;
+}
+export interface RootFreshnessMetadata {
+    rootPath: string;
+    gitTopLevel?: string;
+    isGitRepo: boolean;
+    head?: string;
+    clean: boolean;
+}
+export interface ContextStoreMetadataV2 {
+    schemaVersion: 2;
+    workspaceRoot: string;
+    rootPaths: string[];
+    rootFreshness: RootFreshnessMetadata[];
+    summaryInputHash: string;
+    summarySha256: string;
+    writtenAt: string;
+}
+export type ContextStoreMetadata = LegacyContextStoreMetadata | ContextStoreMetadataV2;
+/**
+ * The full context-store entry for a workspace, as loaded from disk. Returned
+ * by `loadContextStore`; `null` if the store does not exist / is unparseable.
+ */
+export interface ContextStoreEntry {
+    workspaceId: string;
+    summary: StructuralSummary;
+    digest: string;
+    metadata: ContextStoreMetadata;
+}
+/**
+ * §5.4 — `slice_selector` is FORMALLY TYPED so the writer and the
+ * prompt-composer reader never serialize/expect different shapes. One entry
+ * per repo the track touches; `paths` are directory subtrees (relative to
+ * that repo root). Empty `paths` for a repo = "whole repo".
+ */
+export interface SliceSelectorEntry {
+    repo_id: string;
+    /** Directory subtrees relative to that repo root. Empty = whole repo. */
+    paths: string[];
+}
+export type SliceSelector = SliceSelectorEntry[];
+/**
+ * §4.2 / §5.4 — a content-addressed handle into the context store. This is a
+ * DESKTOP-ONLY object: it is resolved locally when composing an implementor's
+ * prompt and is NEVER serialized to the engine wire.
+ *
+ *  - `workspaceId` — the local store key (§5.8).
+ *  - `summary_sha256` — pins the EXACT summary version the ref was minted
+ *    against (content-addressing — lets the desktop detect drift at resolve
+ *    time, §4.2 resolve-time staleness contract).
+ *  - `slice_selector` — which subtrees of the summary this track gets (§5.4).
+ */
+export interface ContextRef {
+    workspaceId: string;
+    summary_sha256: string;
+    slice_selector: SliceSelector;
+}
+/**
+ * The resolved slice the prompt-composer feeds an implementor. Carries the
+ * repo summaries (optionally trimmed to the selector subtrees). The bytes
+ * here NEVER go on the engine wire (ZK).
+ */
+export interface ResolvedContextSlice {
+    workspaceId: string;
+    summary_sha256: string;
+    repos: RepoSummary[];
+    /**
+     * True if the ref was minted against a since-changed summary and the slice
+     * was refreshed from the CURRENT summary at resolve time (§4.2 fail-safe-
+     * forward). Surfaced so callers can log/announce the refresh.
+     */
+    refreshedFromDrift: boolean;
+}
+/**
+ * §5.8 — `workspaceId = sha256(canonical_absolute_workspace_root_path).slice(0,16)`.
+ *
+ * Locally unique (distinct projects → distinct stores; closes the `"."`
+ * `repo_id` collision). Keyed on the canonical ABSOLUTE root path; the store
+ * lives OUTSIDE the repo so this never mutates the working tree. Carries no
+ * path bytes off-device (it is a hash). Cross-machine portability is post-v1.
+ *
+ * `absoluteWorkspaceRoot` is resolved to an absolute path defensively. Callers
+ * SHOULD pass an already-canonical (symlink-resolved) absolute root — use
+ * `canonicalizeRoot` (Codex r1 L1: a symlinked workspace path would otherwise
+ * split the same repo into two stores). `path.resolve` here only normalizes
+ * `.`/`..`/separators; it does NOT resolve symlinks, so canonicalization is the
+ * caller's job via `canonicalizeRoot`.
+ */
+export declare function deriveWorkspaceId(absoluteWorkspaceRoot: string): string;
+/**
+ * §5.8 — canonicalize a path to its real (symlink-resolved) absolute form
+ * before it feeds `deriveWorkspaceId` or the `rootPaths` half of
+ * `summary_input_hash` (Codex r1 L1). Without this, launching the SAME repo via
+ * a symlinked path (`/Users/x/proj` → `/Volumes/code/proj`) would derive a
+ * DIFFERENT `workspaceId` and split one repo into two stores (a cache miss +
+ * duplicate on-disk summaries). `fs.realpath` resolves the symlink chain; if it
+ * fails (ENOENT on a not-yet-created path, EACCES, etc.) we FALL BACK to
+ * `path.resolve` so the call never throws — a non-canonical key is still
+ * deterministic, it just may not coalesce a symlink alias.
+ */
+export declare function canonicalizeRoot(p: string): Promise<string>;
+/**
+ * §5.8 — `repo_id = sha256(relative_path_from_workspace_root)` (FULL digest),
+ * where the relative path is POSIX-normalized: forward slashes, leading `./`,
+ * `.\`, `/`, `\` prefixes stripped, no trailing slash, the single root repo
+ * canonicalized to `"."` (agy r8 L1 — a consistent leading-separator strip
+ * keeps the hash stable across `./repo` vs `repo` vs `/repo`).
+ *
+ * Uses Node's built-in `crypto.createHash('sha256')` — NOT blake3 (agy r4 M2:
+ * blake3 is not a codevibe-core dependency).
+ */
+export declare function deriveRepoId(relativePathFromWorkspaceRoot: string): string;
+/**
+ * §5.8 POSIX normalization for `repo_id` input. Exported for the §5/§6 REMAP
+ * (when it builds `slice_selector` repo entries) so writer + reader agree.
+ */
+export declare function normalizeRepoRelativePath(relativePath: string): string;
+/** `~/.codevibe/context/<workspaceId>/` — entirely under the user's home. */
+export declare function contextStoreDir(workspaceId: string): string;
+/**
+ * Persist a fresh summary + digest + metadata to the store.
+ *
+ * CRASH-ATOMICITY (Codex r2 BLOCKING — the dirty→clean false-fresh hole): the
+ * three per-file writes are individually atomic (tmp→fsync→rename) but NOT
+ * atomic as a SET. A crash BETWEEN renames could leave a NEW `summary.json`
+ * beside an OLD `metadata.json` — and if that recompute was over a DIRTY tree
+ * while the OLD metadata recorded `clean:true` at the same HEAD, the load would
+ * trust the stale `clean` and falsely reuse the dirty summary as fresh.
+ *
+ * The fix makes `digest.txt` the COMMIT MARKER:
+ *   1. write `summary.json`   (atomic rename)
+ *   2. write `metadata.json`  (atomic rename, carrying `summarySha256`)
+ *   3. write `digest.txt`     (atomic rename — LAST; commits the set)
+ * Any crash before step 3 leaves `digest.txt` STALE-OR-MISSING. On load,
+ * `loadContextStore` requires `digest === summary.sha256` (and metadata's
+ * `summarySha256 === summary.sha256`), so a half-committed set fails validation
+ * → treated as not-fresh/corrupt → the caller recomputes. To make the
+ * stale-digest signal sound, we UNLINK any old `digest.txt` BEFORE writing the
+ * new summary/metadata, so a crash mid-set cannot leave an old digest that
+ * happens to equal the new summary's sha (it can't — different content) but
+ * also cannot leave a digest matching the OLD summary while the new summary is
+ * already in place. The marker is therefore: digest present AND == summary.sha
+ * ⇒ the full set committed.
+ *
+ * On any `summary_input_hash` change the caller passes `purgeFirst: true` so a
+ * stale body-including summary cannot linger on disk (§4.2 conjunct (d) — the
+ * PRIVACY fail-safe, Codex r7 H).
+ */
+export declare function writeContextStore(deps: {
+    workspaceId: string;
+    summary: StructuralSummary;
+    metadata: ContextStoreMetadata;
+    purgeFirst?: boolean;
+}): Promise<void>;
+/**
+ * Load the store entry for a workspace. Returns `null` if any of the three
+ * files is missing / unparseable (the store is then treated as "missing" → a
+ * recompute). Defensive: a partially-written / corrupt file never throws.
+ */
+export declare function loadContextStore(workspaceId: string): Promise<ContextStoreEntry | null>;
+interface GitProbe {
+    isGitRepo: boolean;
+    gitTopLevel: string | null;
+    head: string | null;
+    /** True only when `git status --porcelain --untracked-files=all` is EMPTY. */
+    clean: boolean;
+}
+/**
+ * Hash the generation inputs (§4.2 conjunct (d)). A `StructuralSummary` is a
+ * pure function of `tree content × generation inputs`; this hashes the
+ * generation-inputs half so the cache is reusable only when BOTH the tree
+ * (conjuncts a–c) AND the inputs are unchanged.
+ *
+ * Inputs (per §4.2): `{rootPaths, tier, the Max body-inclusion opt-in result
+ * readOptIn(tier), the ~/.codevibe/structural-summary.ignore user-ignore file
+ * hash, the generator/schema version, the relevant CP-1.d caps}`.
+ *
+ * A mismatch is load-bearing AND privacy-critical: a Max user who removes a
+ * body opt-in path or downgrades tier leaves a clean-at-HEAD cached summary
+ * that STILL contains body bytes — reuse would feed those into a `context_ref`
+ * slice, violating the §1.3/§5.4 ZK boundary. So a mismatch forces recompute
+ * AND purge (Codex r7 H).
+ */
+export declare function computeSummaryInputHash(deps: {
+    rootPaths: string[];
+    tier: Tier;
+}): Promise<string>;
+export interface FreshnessProbeResult {
+    /** True ONLY when all four conjuncts hold (provably reusable). */
+    fresh: boolean;
+    /**
+     * Why it was not fresh (for logging / tests). One of the four conjuncts, or
+     * `missing` (no cached entry), or `not-git` (sound non-git fallback).
+     */
+    reason: 'fresh' | 'missing' | 'metadata-schema-mismatch' | 'root-set-mismatch' | 'git-root-mismatch' | 'not-git' | 'dirty-tree' | 'head-moved' | 'cached-was-dirty' | 'input-hash-mismatch';
+    /** The live git probe (so the caller can persist `clean`/`head` on recompute). */
+    git: GitProbe;
+    /** Per-root live freshness facts to persist with the recomputed summary. */
+    rootFreshness: RootFreshnessMetadata[];
+    /** The freshly-computed input hash (so the caller can persist it on recompute). */
+    liveInputHash: string;
+    /**
+     * True when the input hash specifically changed — the caller MUST purge the
+     * stale entry before rewriting (the body-inclusion/ZK fail-safe). Distinct
+     * from a plain tree-drift recompute (which can overwrite-in-place).
+     */
+    inputHashChanged: boolean;
+}
+/**
+ * §4.2 — the provably-sound + cheap staleness probe. Returns `fresh:true` ONLY
+ * when ALL FOUR conjuncts hold:
+ *
+ *   (a) each current git root worktree is clean (`git status --porcelain
+ *       --untracked-files=all` EMPTY);
+ *   (b) each live root's HEAD + git top-level equals the record in metadata;
+ *   (c) every cached root summary was ITSELF computed over a clean tree
+ *       (`rootFreshness[].clean === true` — the dirty→clean-revert hole);
+ *   (d) the generation inputs are unchanged (`summary_input_hash` matches —
+ *       tier / body opt-in / user-ignore / generator version / caps, Codex r7 H).
+ *
+ * Any failing conjunct ⇒ NOT provably fresh ⇒ recompute. A non-git tree never
+ * skips. The invariant: only a clean tree, at the same HEAD, whose cached
+ * summary was also clean-at-that-HEAD AND generated under the same inputs,
+ * skips; everything else recomputes (fail-safe toward "never stale" + the
+ * body-inclusion/ZK boundary).
+ */
+export declare function probeFreshness(deps: {
+    workspaceRoot: string;
+    rootPaths: string[];
+    tier: Tier;
+    cached: ContextStoreEntry | null;
+}): Promise<FreshnessProbeResult>;
+export interface EnsureFreshResult {
+    /** The current (possibly-refreshed) summary digest — `''` if unavailable. */
+    digest: string;
+    /** The workspace id keying the store. */
+    workspaceId: string;
+    /** True if a recompute ran this call; false if the cached entry was reused. */
+    recomputed: boolean;
+    /** The probe outcome (for logging / surfacing). */
+    reason: FreshnessProbeResult['reason'];
+    /**
+     * The (possibly-refreshed) structural summary — the SAME object that was
+     * persisted to / reused from the store, so a caller (session-start /
+     * familiarize) can dispatch it to the orchestration store WITHOUT a SECOND
+     * generator walk (Codex r1 M1 — the double-walk unify). `null` when the
+     * refresh failed (`error` set) — the caller then renders the failure floor.
+     */
+    summary: StructuralSummary | null;
+    /**
+     * Set when the refresh FAILED (e.g. unreadable tree). The pre-classify
+     * caller surfaces this as the only `ask_user` case (§4.2 — "the only
+     * `ask_user` case is a refresh that fails"); a stale digest is NEVER
+     * proceeded with. `null` on success.
+     */
+    error: string | null;
+}
+export interface EnsureFreshDeps {
+    workspaceRoot: string;
+    rootPaths: string[];
+    tier: Tier;
+    userId: string;
+    generator: StructuralSummaryGenerator;
+    /** Test seam — defaults to the real `probeFreshness`. */
+    probeFreshnessFn?: typeof probeFreshness;
+    /** Test seam — defaults to the real `loadContextStore`. */
+    loadContextStoreFn?: typeof loadContextStore;
+    /** Test seam — defaults to the real `writeContextStore`. */
+    writeContextStoreFn?: typeof writeContextStore;
+    /** Test seam for the strict privacy purge path. */
+    purgeContextStoreFilesStrictFn?: (dir: string) => Promise<void>;
+}
+/**
+ * §4.2 — the DESKTOP PRE-CLASSIFY refresh. Called UNCONDITIONALLY before every
+ * `classify` (the planner action is not yet known — it's pre-classify), gated
+ * by the cheap-but-SOUND staleness probe. This is what makes auto-refresh
+ * reachable given the shipped Lambda digest-gate (Codex r2 H2): the hosted
+ * planner overrides `start_task`/`team_decompose` → `ask_user` when the digest
+ * is empty, and the desktop sends the digest from current store state — so the
+ * desktop MUST populate the digest BEFORE the classify.
+ *
+ * Sequence (§4.2 (1)→(2)→(3)):
+ *   (1) load the cached entry + run the 4-conjunct probe.
+ *   (2) if not provably-fresh, run the bounded structural-summary walk to
+ *       recompute (cheap, NOT free) + persist {summary, digest, metadata};
+ *       a `summary_input_hash` mismatch purges the stale entry first.
+ *   (3) return the (possibly-refreshed) digest so the caller writes it into
+ *       the classify packet's `sessionContext`.
+ *
+ * Best-effort but FAIL-CLOSED on the digest: a recompute failure returns
+ * `error` set + `digest:''` (NOT a stale digest) so the caller can `ask_user`
+ * rather than mint a `context_ref` that resolves to a since-changed summary.
+ */
+export declare function ensureFreshContextStore(deps: EnsureFreshDeps): Promise<EnsureFreshResult>;
+/**
+ * Mint a `context_ref` for a track. Content-addressed: pins the EXACT
+ * `summary_sha256` so drift is detectable at resolve time. DESKTOP-ONLY — the
+ * returned object is NEVER serialized to the engine wire.
+ *
+ * `slice_selector` is supplied by the §5/§6 REMAP (the decomposer that knows
+ * each track's `ownership_hint.write_paths` + `shared_contracts`). v1 here
+ * provides the substrate; an empty `slice_selector` = whole workspace (the
+ * degenerate single-track familiarize-everything case, §5.4).
+ *
+ * CONTRACT (Stage-1 r1 LOW — the canonicalization invariant): `workspaceId` MUST
+ * be the CANONICAL id (`deriveWorkspaceId(await canonicalizeRoot(root))`).
+ * `resolveContextRef` loads by `ref.workspaceId`, while `ensureFreshContextStore`
+ * writes under the canonical id — a non-canonical (symlink-aliased) `workspaceId`
+ * here would resolve to the wrong / missing store. There is no production mint
+ * site yet (the §5/§6 REMAP that mints refs is CP-14 territory); when it lands,
+ * canonicalize at every mint call site.
+ */
+export declare function mintContextRef(deps: {
+    /** MUST be canonical — `deriveWorkspaceId(await canonicalizeRoot(root))`. */
+    workspaceId: string;
+    summary_sha256: string;
+    slice_selector?: SliceSelector;
+}): ContextRef;
+/**
+ * §4.2 resolve-time staleness contract (the decompose→dispatch window) +
+ * §5.4 slicing. Resolve a `context_ref` into the slice the prompt-composer
+ * feeds an implementor, locally, on the desktop. The slice bytes NEVER go on
+ * the engine wire (ZK).
+ *
+ * Because `context_ref` pins `summary_sha256`, the desktop detects when the
+ * tree changed between mint (decompose) and resolve (prompt-compose). v1
+ * contract (FAIL-SAFE-FORWARD): if the live summary has drifted from the
+ * pinned `summary_sha256`, refresh the slice from the CURRENT summary before
+ * composing — the implementor always gets a slice consistent with the tree it
+ * will actually edit (never a slice from a since-changed summary). The refresh
+ * is gated by the SAME sound staleness probe (no model call when the sha256 is
+ * unchanged).
+ */
+export declare function resolveContextRef(deps: {
+    ref: ContextRef;
+    workspaceRoot: string;
+    rootPaths: string[];
+    tier: Tier;
+    userId: string;
+    generator: StructuralSummaryGenerator;
+    /** Test seam — defaults to the real `ensureFreshContextStore`. */
+    ensureFreshFn?: typeof ensureFreshContextStore;
+    /** Test seam — defaults to the real `loadContextStore`. */
+    loadContextStoreFn?: typeof loadContextStore;
+}): Promise<ResolvedContextSlice>;
+/**
+ * §5.4 — slice a `StructuralSummary` down to the selector's repo+path
+ * subtrees. One selector entry per repo (keyed by `repo_id`); `paths` are
+ * directory subtrees relative to that repo root; empty `paths` = whole repo.
+ *
+ * An empty `slice_selector` (no entries at all) = the whole workspace (the
+ * degenerate familiarize-everything case). A repo summary's manifest /
+ * dependency block is ALWAYS retained (included implicitly by the resolver,
+ * §5.4) — only the `directoryTree` is trimmed to the selected subtrees.
+ */
+export declare function sliceSummary(summary: StructuralSummary, selector: SliceSelector, workspaceRoot?: string): RepoSummary[];
+export {};

package/dist/orchestration-shell/declared-test-runner.d.ts

@@ -0,0 +1,84 @@
+import type { Dirent, Stats } from 'node:fs';
+import type { runShellCommand } from '../local-executor/verification-gates/shell-runner';
+import type { ShadowDiffFile } from '../local-executor/workspace-shadow';
+/** Default per-file wall-clock budget for a declared-test `node` run. */
+export declare const DECLARED_TEST_TIMEOUT_MS = 300000;
+/**
+ * CLOSED reason set (Codex-r2-4 / LOCK #598-6) — every surfaced reason is one of
+ * these FIXED labels; a raw exception message is NEVER surfaced. The `<ext>` /
+ * `N` placeholders are filled with the user-owned extension / the integer exit
+ * code respectively (both safe — the user owns the workspace), never with
+ * arbitrary error text.
+ */
+export type DeclaredTestReason = `test failed (exit ${number})` | 'timed out' | `no supported runner for ${string}` | 'path outside workspace' | 'path could not be inspected' | 'test runner failed to start' | 'declared test was deleted' | `test framework ${string} not available`;
+export interface DeclaredTestResult {
+    outcome: 'pass' | 'fail' | 'no_tests_run';
+    /** On 'fail': first failing/unexecutable file (workspace-relative). */
+    failingPath?: string;
+    reason?: DeclaredTestReason;
+    /** Executed files. */
+    ranCount: number;
+    /** Never-written declared file / empty-or-JS-less declared dir (§3.D, VISIBLE). */
+    skipped: string[];
+}
+export interface RunDeclaredTestSurfacesArgs {
+    /** cwd holding the agent's changes (the shadow root). */
+    shadowDir: string;
+    /** Workspace-relative declared test paths. */
+    testSurfaces: string[];
+    /** Workspace-rel paths the diff marked `change_kind:'deleted'` (Codex-r2-3). */
+    deletedPaths: string[];
+    trackIndex: number;
+    /** Injected (test seam) — the verification subprocess primitive. */
+    runShell: typeof runShellCommand;
+    /** Injected — existence + symlink discriminate (no-follow). */
+    lstat: (p: string) => Promise<Stats>;
+    /** Injected — symlink-following containment. */
+    realpath: (p: string) => Promise<string>;
+    /** Injected — file/dir discriminate on the resolved target. */
+    stat: (p: string) => Promise<Stats>;
+    /** Injected — directory expansion. */
+    readdir: (p: string) => Promise<Dirent[]>;
+    /**
+     * Injected (#609) — read a file's UTF-8 contents (nearest-`package.json` framework detection).
+     * A throw (ENOENT / EISDIR / unreadable) is TOTAL-handled by `detectFramework` (→ keep walking up,
+     * else fall back to the bare-`node` runner); it never propagates a raw error.
+     */
+    readFile: (p: string) => Promise<string>;
+    /** Default `DECLARED_TEST_TIMEOUT_MS`. */
+    timeoutMs?: number;
+}
+/**
+ * Canonicalize a declared scope / diff path for comparison: collapse backslashes to
+ * POSIX `/`, strip a leading `./`, strip trailing `/`. A `''` result matches nothing.
+ *
+ * SINGLE SOURCE OF TRUTH (Codex impl-r1 HIGH) — `quorum-loop.ts`'s `filesOutsideWriteScope`
+ * imports THIS function so the write-scope guard and the declared-test executor's deletion
+ * guard + classification cannot drift. A non-canonical declared surface (e.g. `./test/track0/`
+ * or `test\track0\`) that the diff guard accepts in-scope MUST normalize identically here, or
+ * a captured deletion `test/track0/b.test.js` would slip past the deletion guard.
+ */
+export declare function normalizeScopePath(rel: string): string;
+/**
+ * REVIEW-INTEGRITY DRIFT (Codex impl-r4 HIGH / LOCK #598-10) — the workspace-relative
+ * paths that DIFFER between two captured shadow diffs: a path present in one set but not
+ * the other, or present in both with a changed `change_kind` or `content`.
+ *
+ * LOAD-BEARING. The declared-test executor runs agent-authored `node <file>` with
+ * `cwd: shadowDir`, which can MUTATE the shadow (write / delete / modify) AFTER the
+ * reviewed diff was captured. Promotion re-captures the LIVE shadow and applies THAT, so a
+ * post-test mutation would be promoted though reviewers + the user only ever approved the
+ * pre-test diff (and a test-time deletion would dodge the `deletedPaths` guard). The caller
+ * re-captures after the test gate and FAILS the round when this returns non-empty — a
+ * declared test must be PURE. Content-SAFE: returns PATHS only, never file content (the user
+ * owns the workspace, so paths are permitted on the surface; content is NOT). Sorted for a
+ * stable, deterministic surface.
+ */
+export declare function shadowDiffDrift(before: ShadowDiffFile[], after: ShadowDiffFile[]): string[];
+/**
+ * Run a team track's declared `test_surfaces` against the shadow (the agent's
+ * uncommitted changes). Pure free function with injected deps (fully mockable —
+ * agy-4). First failure / hard-fail WINS (short-circuit). See the module-level
+ * invariants.
+ */
+export declare function runDeclaredTestSurfaces(args: RunDeclaredTestSurfacesArgs): Promise<DeclaredTestResult>;

package/dist/orchestration-shell/emit-shell-event.d.ts

@@ -0,0 +1,64 @@
+import { AppSyncClient } from '../appsync';
+/**
+ * §3 LOCK lines 173-181. Names + per-type metadata shapes are part of
+ * the Stage A contract. CP-1.a ships the union; CP-1.b/c/d add call
+ * sites for each emit type.
+ */
+export type NewEventTypeKind = 'MODE_SELECTED' | 'PLANNER_DECISION' | 'PLANNER_CACHE_HIT' | 'PLANNER_DEGRADED' | 'PLANNER_OUTAGE' | 'PLANNER_RECOVERED' | 'SLASH_COMMAND_INVOKED' | 'STRUCTURAL_SUMMARY_GENERATED' | 'LOCAL_AUTHORITY_REFUSAL' | 'NOTIFICATION' | 'ASSISTANT_RESPONSE';
+/**
+ * §3 LOCK lines 160-170. ShellEventEmit contract.
+ *
+ * Per Stage 2 r1 Codex HIGH-2: `source` and `isEncrypted` MUST be
+ * present on every call. The Stage A LOCK on §3 fixes both: every CP-1
+ * shell event is DESKTOP-sourced and E2E-encrypted under the session
+ * key. Making them required (vs optional) prevents accidental plaintext
+ * fall-through if a caller forgets either field.
+ */
+export interface ShellEventEmit {
+    /** Current Session.sessionId; orchestration shell tracks this. */
+    sessionId: string;
+    /** One of the 9 new EventType enums (plus NOTIFICATION reuse). */
+    type: NewEventTypeKind;
+    /** Shell is desktop-side; mobile uses its own emit path. REQUIRED. */
+    source: 'DESKTOP';
+    /** Human-readable summary; encrypted under session key. */
+    content?: string;
+    /** Event-specific structured payload; encrypted; per-type shape per §3. */
+    metadata?: Record<string, unknown>;
+    /** All CP-1 shell events are E2E encrypted per existing pattern. REQUIRED. */
+    isEncrypted: true;
+    /** RFC3339; if omitted, server fills in via existing VTL. */
+    timestamp?: string;
+}
+/**
+ * Test seam — allows the unit tests to swap the AppSync client without
+ * mounting the full singleton. Production code calls
+ * `emitShellEvent(args)` which uses `getDefaultClient()`.
+ */
+export interface EmitShellEventDeps {
+    appsyncClient: Pick<AppSyncClient, 'createEvent'>;
+    getSessionKey: (sessionId: string) => Promise<string | null>;
+    getCohortFlag: (name: string, sessionId: string) => Promise<boolean>;
+}
+/**
+ * §3 LOCK lines 184-207. Single chokepoint enforcing the cohort-flag
+ * gate + encryption invariants for all 9 new EventTypes.
+ *
+ * When the cohort flag is off: log at debug and return without
+ * touching AppSync. When on: encrypt content + metadata under the
+ * session key, call `createEvent` via Pattern B Lambda resolver
+ * (existing surface, no schema change).
+ *
+ * `deps` is the test seam. Production callers omit it and the function
+ * resolves the default `keychainManager` + `cryptoService` references.
+ * The AppSync client is REQUIRED — there is no global default in
+ * codevibe-core (each plugin instantiates its own `AppSyncClient`).
+ */
+export declare function emitShellEvent(args: ShellEventEmit, deps: EmitShellEventDeps): Promise<void>;
+/**
+ * Convenience helper for production callers — binds default
+ * dependencies (`keychainManager` for session-key lookup,
+ * `getCohortFlag` for the flag read) and accepts the AppSync client
+ * separately because there's no global default in `codevibe-core`.
+ */
+export declare function createShellEventEmitter(appsyncClient: Pick<AppSyncClient, 'createEvent'>): (args: ShellEventEmit) => Promise<void>;