@sema-agent/core 7.15.0 → 7.17.0

package/dist/tools/fs/read-face.d.ts

@@ -1,13 +1,12 @@
-/** The read-face containment state. `"roots"` = the historical containment judgment, unchanged.
+/** The read-face containment state. `"roots"` = the containment judgment runs.
  *  `"open"` = the containment step is skipped (canonicalization, deny set, UNC out-of-set refusal
  *  and the type gates all still run). */
 export type ReadFace = "open" | "roots";
-/** Loud value gate (#123): a `readFace` seat carries exactly "open" | "roots" — anything else
- *  (case variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
+/** Loud value gate: a `readFace` seat carries exactly "open" | "roots" — anything else (case
+ *  variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
  *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
- *  screen the seats on runs that never mount hands early and unconditionally (since #242 the
- *  resolver itself ALSO runs on every hands-less leg; this screen still fires first, so a garbage
- *  value refuses before any leg-shape branching). */
+ *  screen the seats on runs that never mount hands. The resolver itself also runs on every hands-less
+ *  leg; this screen still fires first, so a garbage value refuses before any leg-shape branching. */
 export declare function assertReadFaceValue(v: unknown, seat: string): ReadFace | undefined;
 /** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
  *  (a deliberate axis separation: this shape carries facts, not verdicts). */
@@ -20,17 +19,16 @@ export interface ReadFaceInputs {
      *  LOAD-BEARING wall (bash_readonly is genuinely confined by it) — never openable. */
     readOnlyMount: boolean;
     /** Org governance declared (`RunnerDeps.permissionRuleStore.partitions.org === true`): default roots; the task layer
-     *  may not open (D-2 — tighten-only under governance; the deps layer, being the deployment's own
+     *  may not open (tighten-only under governance; the deps layer, being the deployment's own
      *  declaration, still may). */
     orgGoverned: boolean;
-    /** D-6: is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
-     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — recon §3:
-     *  every exclusion source is spec-time-frozen, so this is always computable). When false, the
-     *  roots fence is the ONLY read boundary and the default stays roots even under a deps-layer
-     *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
-     *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
+    /** Is the FULL shell (`core.bash@1`) structurally reachable on this mount? Computed BEFORE
+     *  tool-band assembly from spec-time facts (env kind / handsReadOnly / Bash exclusion — every
+     *  exclusion source is spec-time-frozen, so this is always computable). When false, the roots fence
+     *  is the ONLY read boundary, so no IMPLICIT default may open the face; an EXPLICIT "open" on
+     *  either seat still wins (row 4 of the order is a default, not a clamp). */
     fullShellReachable: boolean;
-    /** #237 — observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+    /** Observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
      *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
      *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
      *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
@@ -39,24 +37,23 @@ export interface ReadFaceInputs {
     onDeploymentClamp?: () => void;
 }
 /**
- * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
- * this — a library-direct mount gets identical validation and identical defaults.
+ * The ONE resolution order, first hit wins. prepare-task AND createHandsToolkit both call this — a
+ * library-direct mount gets identical validation and identical defaults.
  *
  *  1. read-only (verifier) mount → ROOTS; an explicit "open" on the TASK seat is a genuine
- *     per-call CONTRADICTION and refuses loudly (#123 — never silently pick a side). An "open"
- *     on the DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it
- *     silently CLAMPS to roots (stricter-wins), same seat distinction row 2 already draws for
- *     org governance below.
- *  2. org-governed: TaskSpec "open" refuses (task layer only tightens, D-2); deps "open" wins;
+ *     per-call CONTRADICTION and refuses loudly (never silently pick a side). An "open" on the
+ *     DEPLOYMENT seat alone is a deployment-wide default, not a per-task assertion — it silently
+ *     CLAMPS to roots (stricter-wins), the same seat distinction row 2 draws for org governance.
+ *  2. org-governed: TaskSpec "open" refuses (task layer only tightens); deps "open" wins;
  *     otherwise ROOTS.
  *  3. explicit seat: spec ?? deps.
- *  4. bash-less mount (D-6): ROOTS (the fence is the only read boundary there — "the fence guards
+ *  4. bash-less mount: ROOTS (the fence is the only read boundary there — "the fence guards
  *     nothing bash reaches anyway" does not hold, so no implicit default may open it).
- *  5. default: ROOTS (D-1b — the engine never opens implicitly).
+ *  5. default: ROOTS — the engine never opens implicitly.
  */
 export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;
 /**
- * #237 — the ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
+ * The ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
  * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
  * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
  * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`

package/dist/tools/fs/repo-map.d.ts

@@ -3,14 +3,14 @@ import type { ExecutionEnv } from "../../internal/harness-types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 import type { ReadFace } from "./read-face.js";
 /** Extract top-level symbol names (deduped, in first-seen order) from source text. A lightweight
- *  comment/docstring state machine (council #4) skips column-0 declaration-like lines that are really
- *  inside a `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module
- *  docstring containing `def foo():` at column 0 produces a phantom symbol. Not a full parser (v1
- *  heuristic): it tracks whole-line block/docstring regions, the common false-positive source.
+ *  comment/docstring state machine skips column-0 declaration-like lines that are really inside a
+ *  `/* … *​/` block comment or a Python `"""`/`'''` docstring — otherwise e.g. a module docstring
+ *  containing `def foo():` at column 0 produces a phantom symbol. Not a full parser: it tracks
+ *  whole-line block/docstring regions, the common false-positive source.
  *
- *  ⚠️ **Exported ONLY as a v1 heuristic, NOT a containment proof** (design/79 §3): it is column-0 /
- *  source-only and skips indented lines, so it CANNOT enumerate everything an artifact can call. The
- *  auto-promote tripwire (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan
- *  contributes nothing; it can only ever raise an escalation, never clear one. */
+ *  ⚠️ **A heuristic, NOT a containment proof**: it is column-0 / source-only and skips indented lines,
+ *  so it CANNOT enumerate everything an artifact can call. The auto-promote tripwire
+ *  (src/core/auto-promote.ts) consumes it in ESCALATE-ONLY mode — a clean scan contributes nothing;
+ *  it can only ever raise an escalation, never clear one. */
 export declare function extractSymbols(text: string): string[];
 export declare function createRepoMapTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;