@sema-agent/core 5.20.0 → 5.21.0

package/dist/core/permission-rule-store.d.ts

@@ -1,26 +1,76 @@
+/**
+ * design/179 §8 — the persisted allow-rule store seam, its core-private write face, and the removal entry.
+ *
+ * ## Two faces, deliberately unequal
+ *
+ * A deployment sees a READ face: `list()`, scoped to one verified principal by a factory. There is no
+ * exported write API at all — the only way a rule enters the store through the engine is the core-private
+ * redemption path (`permission-rule-consent.ts`), which requires an approved durable approval record.
+ * `expectedRev` is concurrency control, not authorization, so "hold a put API and skip the ticket" is not
+ * a shape that exists here rather than a rule someone must remember.
+ *
+ * That claim is scoped to the API. A standard in-process deployment shares filesystem credentials with the
+ * user, so it can edit a file backend's file directly — the same trust model the settings file it mirrors
+ * has. The checksum detects corruption, not an editor who recomputes it. This is stated, not defended
+ * against, in v1: the file backend's trust is host = user, no more and no less.
+ *
+ * ## Principal scoping is a factory boundary, not a parameter
+ *
+ * `forPrincipal` returns a store already anchored to one identity, so `list()` has no cross-tenant
+ * argument to pass wrong. An unauthenticated task (`principal === undefined`) resolves to ZERO rules
+ * rather than to a shared bucket — fail-closed on a loosening face means fewer allows, never a shared one.
+ *
+ * ## Delete is a tombstone, and the tombstone IS the operation's identity
+ *
+ * Removal takes the observed-remove form: the tombstone carries every add dot the deleting replica could
+ * see at delete time, and that observation is FIXED when the call constructs it. An OCC retry inside that
+ * one live call re-submits the SAME tombstone — re-snapshotting would suck a concurrently landed add into
+ * `removedDots` and swallow a legitimate re-add. The fixing is scoped to one live call on purpose: there
+ * is no cross-process or cross-restart continuation of a delete in v1, so calling the entry again after a
+ * restart is a NEW delete intent (a new observation, a new tombstone) — which is the correct reading of a
+ * person pressing delete a second time.
+ */
 import type { PersistedAllowRule, RuleAdd, RuleDot, RuleScope, RuleTombstone } from "./permission-rule-model.js";
 import type { StoreDurability, StoreFidelity } from "./checkpoint-store.js";
+/** One store read: the rules as persisted, their tombstones, and the revision they were read at. */
 export interface StoredAllowRules {
+    /** Rules with their FULL add sets — tombstoned dots already removed by the backend on read. */
     rules: PersistedAllowRule[];
     tombstones: RuleTombstone[];
+    /** Monotonic revision of this store, for optimistic concurrency on every write. */
     rev: number;
+    /** Integrity fingerprint the backend computed, when it has one. Corruption detection only. */
     checksum?: string;
 }
+/**
+ * The host-visible store face: read-only, already anchored to a single principal.
+ *
+ * A backend that fails to read must not silently report an empty set as if it were an empty store — it
+ * throws, and the lane's caller turns that into zero rules PLUS a loud disclosure. Both outcomes deny
+ * more than they allow; only one of them is honest about why.
+ */
 export interface PermissionRuleStore {
     list(): Promise<StoredAllowRules>;
+    /** Declared durability; an undeclared backend reads fail-closed as `"process-local"`. */
     readonly durability?: StoreDurability;
+    /** Declared serialization fidelity, same doctrine as the other store families. */
     readonly fidelity?: StoreFidelity;
 }
+/** Resolves a store for one verified principal. `undefined` ⇒ a store that reports zero rules. */
 export interface PermissionRuleStoreProvider {
     forPrincipal(principal: string | undefined): PermissionRuleStore;
 }
+/** The outcome of one accepted write. */
 export interface PutResult {
     rev: number;
 }
+/** Authorization accompanying an add: the redemption that produced it. Carrying the record id makes the
+ *  add's logical operation identity checkable at the backend, not just at the caller. */
 export interface RedemptionAuthorization {
     recordId: string;
     principal: string;
 }
+/** The add half of the write union: one redeemed approval becoming one dot on one (rule, scope). */
 export interface RuleAddDelta {
     kind: "redemption-add";
     rule: string;
@@ -31,12 +81,25 @@ export interface RuleAddDelta {
     add: RuleAdd;
     redemption: RedemptionAuthorization;
 }
+/** The delete half: appending one tombstone, and nothing else. */
 export interface RuleDeleteDelta {
     kind: "tighten-delete";
     tombstone: RuleTombstone;
 }
+/**
+ * What a write may say. Authorization discriminates on the DELTA SHAPE, not on a full snapshot: only the
+ * add arm can introduce a dot, and the delete arm carries a tombstone and no adds. A backend additionally
+ * REFUSES at runtime any delete that would introduce a new add dot — structure and runtime check together,
+ * so "pick the delete arm and smuggle an add" is neither expressible nor accepted.
+ */
 export type RuleWriteDelta = RuleAddDelta | RuleDeleteDelta;
+/**
+ * The core-private write face. Deliberately absent from the package's public exports: a host cannot hold
+ * one, so no API-level path to the store bypasses the consent protocol.
+ */
 export interface PermissionRuleWriter {
+    /** Mint the next dot for this replica. Counters need only be unique and monotonic, so a dot minted for
+     *  an operation that then fails is simply never used. */
     nextDot(): Promise<RuleDot>;
     apply(delta: RuleWriteDelta, opts: {
         expectedRev: number;
@@ -45,28 +108,75 @@ export interface PermissionRuleWriter {
         rev: number;
     }>;
 }
+/**
+ * The internal handle a writable backend hangs its write face on. Not exported from the package index —
+ * that omission IS the boundary described in the module doc.
+ */
 export declare const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
+/** A store that also carries the core-private write face. */
 export interface WritablePermissionRuleStore extends PermissionRuleStore {
     readonly [PERMISSION_RULE_WRITER]: PermissionRuleWriter;
 }
+/** The writer of a store, or `undefined` when the backend is read-only from the engine's side. */
 export declare function writerOf(store: PermissionRuleStore): PermissionRuleWriter | undefined;
+/** Do two scopes name the same place? */
 export declare function sameScope(a: RuleScope, b: RuleScope): boolean;
+/**
+ * Apply tombstones to a raw persisted set: an add survives iff its dot appears in no tombstone for the
+ * same (rule, scope). The criterion is dot IDENTITY — single dots across replicas carry no order to
+ * compare — and an add the deleting replica never observed survives (add-wins), because behind every add
+ * there is one real human approval.
+ */
 export declare function applyTombstones(rules: readonly PersistedAllowRule[], tombstones: readonly RuleTombstone[]): PersistedAllowRule[];
+/** Fold one delta into a raw rule set, returning the new set. Pure — the backends share it so the file and
+ *  in-memory forms cannot drift in what a delta MEANS. */
 export declare function foldDelta(rules: readonly PersistedAllowRule[], delta: RuleAddDelta): PersistedAllowRule[];
+/** Every add dot present in a rule set. */
 export declare function addDotsOf(rules: readonly PersistedAllowRule[]): RuleDot[];
+/**
+ * The runtime half of the delete-arm authorization, shared by every backend so the two cannot drift on
+ * what a delta MEANS.
+ *
+ * The union already makes "pick the delete arm and also add something" unspellable in TypeScript, and a
+ * union does not constrain a JavaScript caller's payload — so the check is executed, not merely intended.
+ * Every backend calls this before appending a tombstone.
+ */
 export declare function assertDeleteDeltaCarriesNoAdd(delta: RuleDeleteDelta): void;
+/** Integrity fingerprint over a store's own facts. Corruption detection, not tamper-proofing. */
 export declare function ruleStoreChecksum(payload: unknown): Promise<string>;
-export type RemoveResult = {
+/**
+ * The result of a removal.
+ *
+ * `conflict` is not a member: an OCC conflict is retried internally to a terminal state, so a caller never
+ * has to write the retry loop that must not re-snapshot.
+ */
+export type RemoveResult = 
+/** The tombstone landed and none of the observed dots survive. `stillLive` reports whether an approval
+ *  that landed DURING this call keeps the rule alive anyway (add-wins) — a real outcome with a name,
+ *  not an anomaly. */
+{
     status: "removed";
     rev: number;
     stillLive: boolean;
-} | {
+}
+/** Nothing to remove — including a repeated delete. No empty tombstone is minted. */
+ | {
     status: "no-op";
     rev: number;
-} | {
+}
+/** Terminal failure, confirmed by read-back to have written NOTHING. When the read-back itself failed,
+ *  `error` says so and the caller reconciles with `list()`. */
+ | {
     status: "failed";
     error: string;
 };
+/**
+ * Remove a persisted rule.
+ *
+ * Removal is the TIGHTENING direction, so it needs no approval-record ceremony: a host may narrow on a
+ * user's behalf, it may not widen. The asymmetry is the point — minting takes a human's click, revoking
+ * does not.
+ */
 export declare function removePersistedRule(opts: {
     rule: string;
     scope: RuleScope;
@@ -74,7 +184,13 @@ export declare function removePersistedRule(opts: {
     provider: PermissionRuleStoreProvider;
 }): Promise<RemoveResult>;
 export declare function errText(err: unknown): string;
+/** A store that always reports zero rules — what an unauthenticated principal resolves to, and the shape a
+ *  failed read degrades to at the consumption site. */
 export declare const EMPTY_RULE_STORE: PermissionRuleStore;
+/**
+ * In-memory backend — the reference implementation of the delta semantics, and the one the tests drive.
+ * `process-local` by declaration: it makes no durability promise it cannot keep.
+ */
 export declare class InMemoryPermissionRuleStore implements WritablePermissionRuleStore {
     private readonly actor;
     readonly durability: StoreDurability;

package/dist/core/permission-rules.d.ts

@@ -1,17 +1,54 @@
+/**
+ * design/127 — **参数级权限规则 DSL**(CC 2.1.201 追平批 γ)。声明式规则字符串 → {@link ToolPolicy}
+ * 编译器:`"Tool"`(裸)/ `"Tool(param:pattern)"`(参数级,`*` 通配全串锚定)。CC ground truth
+ * 行号级:解析 `Lh` :55214 · 通配 `ZMr` :55196 · 参数级 matcher `gnn` :595123 · 评估序 `G1e` :595272。
+ *
+ * 架构边界(design/127 §0,重判过的「core 不长 rule interpreter」):这是纯函数式、opt-in、零
+ * run-loop 介入的「声明式数据→ToolPolicy」工厂(`createCoarseCommandNamePolicy` 同形态先例)。
+ * core 不读设置文件、不管 source 层级合并 —— Settings-loader 把各层合并成**单一规则表**后编译
+ * **一个** policy(不要按层各编译再组合:combinePolicies 的 fold 里 ask 胜 allow,跨 policy 的
+ * 显式 allow 规则会被另一 policy 的 ask 吞掉 —— codex 127 审 B3)。
+ *
+ * 🔴 与 CC 的三处有意差(design/127 r2):
+ *  - CC 参数级 generic 道无 allow lane(gnn 只有 deny/ask)—— 我们同样:`allow` + 参数级 content =
+ *    无效规则;auto-allow 只来自裸工具规则。
+ *  - CC 对尾缀垃圾静默降级为裸名(Lh `n !== len-1`)—— `parsePermissionRule` 保持 CC parity,但
+ *    **工厂 validator strict**:降级即 invalid(fail-fast 世界观,写错的规则不能静默变宽)。
+ *  - 已知主字段参数规则(如 `Bash(command:…)`)默认 **reject**:通配是 trim 后**整串 lexical**
+ *    匹配,不是 shell AST / 前缀 lane —— `Bash(command:git push*)` 匹配不了 `cd /x && git push`,
+ *    「以为挡住了」比没挡更危险(codex 127 审 M2)。`primaryFieldGeneric:"allow-lexical"` 显式解锁。
+ */
 import type { NamedToolPolicy } from "./tool-policy.js";
+/** [K-PLATFORM-SWEEP] MINOR#11: Bash's REAL non-primary arg names, accepted as generic param rules
+ *  (`Bash(timeout:...)`). Exported SOLELY so a lockstep test can assert it against the live Bash tool
+ *  schema — a schema param added without updating this set would compile to silently-never-matching
+ *  rules (the exact drift class the Opus 复审 m note warned about). */
 export declare const BASH_GENERIC_PARAMS: ReadonlySet<string>;
 export interface PermissionRule {
+    /** CC 语法:`"Tool"` 或 `"Tool(param:pattern)"`。`Tool()`/`Tool(*)` 归一为裸规则;括号可 `\(`/`\)` 转义。 */
     rule: string;
     behavior: "deny" | "ask" | "allow";
+    /** Provenance(codex 127 审 M7):进 deny/ask 的 message 供审计(e.g. `"policySettings"`)。层级
+     *  优先级/tighten-only 语义在 Settings-loader,不在这里。 */
     source?: string;
 }
+/** Parse result — CC `Lh` parity (INCLUDING the silent bare-name downgrade on malformed parens; the
+ *  factory validator is strict on top of this, see module doc). */
 export interface ParsedPermissionRule {
     toolName: string;
     ruleContent?: string;
 }
 export interface PermissionRuleIssue {
     rule: string;
-    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix" | "unsupported.bash_prefix_rules_store" | "unsupported.file_glob" | "unsupported.mcp_paren" | "unsupported.unknown_param";
+    /** `invalid.*` = 语法/语义错;`unsupported.*` = CC 合法但 v1 不支持的 lane(codex 127 审 B5:独立
+     *  分类,绝不静默 no-op —— `Bash(npm run:*)` 被当 generic 参数规则接受后永不匹配是最危险的失败形态)。 */
+    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix"
+    /** design/179 D7: a Bash prefix rule under `bashPrefixLane:"rules-store"` — reported so a migration
+     *  report can tell "route this through the rule store" apart from "this is a mistake". */
+     | "unsupported.bash_prefix_rules_store" | "unsupported.file_glob" | "unsupported.mcp_paren"
+    /** HRD-PRM-7: a param-level rule naming a parameter the target tool does not carry. Additive member —
+     *  the lane that used to compile silently and never match (see {@link FILE_TOOL_PARAMS}). */
+     | "unsupported.unknown_param";
     message: string;
 }
 export interface PermissionRuleCaps {
@@ -19,18 +56,67 @@ export interface PermissionRuleCaps {
     maxRuleLength: number;
     maxPatternLength: number;
     maxStars: number;
+    /** Scalar arg values longer than this are NOT matched textually — the rule **fail-closes** to its
+     *  lane (a deny rule targeting an oversized value denies; an ask rule asks). 租户规则 × 模型巨串
+     *  的热路径成本上界(codex 127 审 M6)。 */
     maxScalarValueChars: number;
 }
 export interface PermissionRulePolicyOptions {
+    /** Invalid/unsupported rules: `"throw"`(default — 部署作者写错要立刻知道)aggregates ALL issues
+     *  into one error; `"skip"` drops them (pair with {@link validatePermissionRules} for a report, and/or
+     *  supply {@link onIssue}). Exception(codex 实现审 M3):`invalid.cap_exceeded` on the WHOLE rule set
+     *  (maxRules) throws EVEN under `"skip"` — skipping it would compile an EMPTY table and fail-open. */
     onInvalidRule?: "throw" | "skip";
+    /** Called once per dropped rule under `"skip"` (audit surface — silent drops are how a deployment
+     *  discovers, months later, that its deny never existed). Default: one aggregated `console.warn`. */
     onIssue?: (issue: PermissionRuleIssue) => void;
+    /** What the policy returns when NO rule matches. Default `"allow"` = 本 policy 无意见(组合语义)。
+     *  default-closed 部署用 `"ask"`/`"deny"` —— 必须在这 INSIDE the policy(codex 127 审 B3:链尾
+     *  ask policy 会在 fold 里吞掉本 policy 的显式 allow)。 */
     defaultAction?: "allow" | "ask" | "deny";
+    /** 已知主字段参数规则(`Bash(command:…)` 等)的处置。默认 `"reject"`(整串 lexical ≠ 前缀/AST,
+     *  假安全感);`"allow-lexical"` 显式接受并按 generic 语义匹配。 */
     primaryFieldGeneric?: "reject" | "allow-lexical";
+    /**
+     * design/179 D7 — where a Bash PREFIX rule (`Bash(npm run:*)`) belongs.
+     *
+     * This DSL is a pure function with no access to a deployment's wiring, so it cannot discover on its own
+     * that a persisted-rule store exists; the choice has to be said out loud. `"reject"` is the default and
+     * keeps this file's behavior byte-identical to what it was: a prefix rule is an `unsupported.bash_prefix`
+     * issue, because a generic parameter matcher would compile it into a rule that never matches anything.
+     * `"rules-store"` says the deployment routes that form through the persisted allow-rule lane instead —
+     * the issue is then re-coded to {@link PermissionRuleIssue.code} `unsupported.bash_prefix_rules_store`,
+     * which reads as "handled elsewhere" rather than "you wrote something wrong". Either way the rule does
+     * NOT enter this policy: the two lanes stay separate, and only the report changes.
+     */
     bashPrefixLane?: "reject" | "rules-store";
     caps?: Partial<PermissionRuleCaps>;
 }
+/**
+ * Parse one rule string — CC `Lh` :55214 parity, including its lenient downgrades (malformed parens /
+ * trailing garbage ⇒ the WHOLE string becomes the bare tool name). The strict complement lives in
+ * {@link validatePermissionRules} — use that (or the factory) to refuse the downgrades.
+ */
 export declare function parsePermissionRule(rule: string): ParsedPermissionRule;
+/**
+ * Linear-time `*` glob match (design/127 M6: NOT a RegExp — patterns may come from tenant-supplied
+ * Settings layers; the classic two-pointer walk has zero ReDoS surface and the same semantics as CC's
+ * anchored `^…$`+dotAll construction: every non-`*` char is literal, `*` spans anything incl. newlines).
+ */
 export declare function wildcardMatch(pattern: string, value: string): boolean;
+/** Exported for the lockstep guard only (see {@link FILE_TOOL_PARAMS}) — not part of the rule DSL. */
 export declare const fileToolParamVocabulary: (canonicalTool: string) => ReadonlySet<string> | undefined;
+/** Dry-run 校验/迁移报告(codex 127 审 B5):不 throw,返回全部 issues(含 `unsupported.*` 分类,
+ *  供从 CC settings 迁移的部署逐条对照)。 */
 export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane">): PermissionRuleIssue[];
+/**
+ * Compile declarative permission rules into ONE {@link ToolPolicy} (design/127). Evaluation order
+ * inside the policy (CC `G1e` :595272 isomorph): bare deny → param deny → bare ask → param ask →
+ * bare allow → `defaultAction`. `check()` is idempotent and side-effect-free (combinePolicies 契约);
+ * all parsing/validation happens HERE, the hot path never re-parses.
+ *
+ * ⚠️ Composition note (codex 127 审 B3): an `allow` from this policy is "no objection", NOT a
+ * cross-policy override — another policy's ask/deny still outranks it in the combinePolicies fold.
+ * Express default-closed via `defaultAction`, never via a trailing always-ask policy.
+ */
 export declare function createPermissionRulePolicy(rules: PermissionRule[], opts?: PermissionRulePolicyOptions): NamedToolPolicy;

package/dist/core/present-plan-tool.d.ts

@@ -1,7 +1,27 @@
 import type { ToolSpec } from "./types.js";
+/** The first-party plan-review tool's name (design/80 D-B; CC `ExitPlanMode` parity). Reserved when
+ *  `TaskSpec.enablePlanMode` is set. */
 export declare const PRESENT_PLAN_TOOL_NAME = "ExitPlanMode";
+/** design/108 — the first-party "enter plan mode" tool's name (CC `EnterPlanMode` parity). Mounted (alongside
+ *  `present_plan`) when `TaskSpec.enablePlanMode` is set, so the model can self-impose read-only plan mode. */
 export declare const ENTER_PLAN_MODE_TOOL_NAME = "EnterPlanMode";
+/**
+ * design/108 — the first-party `enter_plan_mode` tool (CC `EnterPlanMode` parity). A THIN composition over the
+ * general `ctx.enterPlanMode()` primitive: the model calls it to self-impose read-only plan mode for the rest of
+ * THIS run. `effect:"read"` (it grants nothing — it RESTRICTS). `executionMode:"sequential"` so that in a batch
+ * like `[enter_plan_mode, edit_file]` the whole batch runs sequentially (agent-loop `hasSequentialToolCall`),
+ * making enter execute (set the flag) BEFORE the sibling edit is prepared+gated — closing the same-batch window.
+ * Exit is via `present_plan` (→ plan_review → human approve-resume), not by this tool.
+ */
 export declare function createEnterPlanModeTool(enterPlanMode: () => void): ToolSpec;
+/**
+ * design/80 D-B — the first-party `present_plan` tool (CC `ExitPlanMode` parity). A THIN composition over the
+ * general `ctx.requestReview()` primitive: the model calls it with a plan; the tool returns the plan as its
+ * content (so it reaches the reviewer via the transcript — the plan is NOT stored on the gate, design/76 §9),
+ * and signals the engine to pause with a `plan_review` checkpoint at the next safe turn boundary. The tool has
+ * NO side effect (`effect:"read"`); the actual pause/mint is the engine's, gated on a wired `checkpointStore`.
+ * `requestReview` is the prepare-task closure (the same primitive `ctx.requestReview` exposes to caller tools).
+ */
 export declare function createPresentPlanTool(requestReview: (opts?: {
     reason?: string;
 }) => void): ToolSpec;

package/dist/core/pricing.d.ts

@@ -1,10 +1,25 @@
+/**
+ * Cost computation (1.37). core never hardcodes provider pricing — a deployment injects it via
+ * `RunnerDeps.pricing` or each `Model.cost`. All prices are **absolute per-1M-token USD**, not
+ * multipliers: each provider's adapter precomputes its discount into an absolute value
+ * (OpenAI/DeepSeek: the cache-hit price; Anthropic: base×0.1 read / ×1.25 5min-write / ×2.0 1h-write).
+ */
+/** Per-1M-token absolute prices (USD) for a model. */
 export interface ModelPricing {
     inputPer1M: number;
     outputPer1M: number;
+    /** Cache-read (hit) absolute price per 1M. Default 0 (treated as full-price input if absent). */
     cacheReadPer1M?: number;
+    /** Cache-write 5-min-TTL absolute price per 1M (Anthropic ~1.25× base). 0 elsewhere. */
     cacheWritePer1M?: number;
+    /** Cache-write 1-hour-TTL absolute price per 1M (Anthropic ~2.0× base). 0 elsewhere. */
     cacheWriteLongPer1M?: number;
 }
+/**
+ * Unified token counts for one task/turn, **already normalized** so `totalInputTokens` INCLUDES all
+ * cache tokens (matching OTel `gen_ai.usage.input_tokens`). `cacheReadTokens`/`cacheWriteTokens`/
+ * `cacheWriteTokensLong` are mutually exclusive subsets of `totalInputTokens`.
+ */
 export interface TokenCounts {
     totalInputTokens: number;
     cacheReadTokens: number;
@@ -12,7 +27,18 @@ export interface TokenCounts {
     cacheWriteTokensLong: number;
     outputTokens: number;
 }
+/**
+ * Cost in **integer micro-USD** (1e-6 USD) — integer to avoid float-accumulation error in billing
+ * reconcile (Stripe/AWS-style). Convergent across providers: full-price input = `totalInputTokens`
+ * minus all cache tokens; cache read/write priced at their own absolute rates; output at its rate.
+ *
+ * DeepSeek (hit price as `cacheReadPer1M`, no cache-write) and OpenAI (no 1h write) fall out by their
+ * zero token counts; Anthropic uses all fields. This fixes P2 (cached charged at full price) by
+ * pricing the cache subset separately instead of trusting the brain's possibly-overstated cost total.
+ */
 export declare function computeCostMicroUsd(counts: TokenCounts, pricing: ModelPricing): number;
+/** Map a vendor `Model.cost` (already per-1M absolute) to `ModelPricing`. We don't emit 1h cache
+ *  writes, so `cacheWriteLongPer1M` defaults to the 5-min write price (irrelevant while that count is 0). */
 export declare function modelCostToPricing(cost: {
     input?: number;
     output?: number;

package/dist/core/property-harness.d.ts

@@ -1,39 +1,125 @@
+/**
+ * Property-harness (design/57 §9 / design/58) — the **oracle-free** half of the trusted-oracle problem.
+ *
+ * From a **trusted contract** (supplied by the spec / leader — NEVER the worker, so it dodges BUG8: a worker
+ * can't write `assert(true)` here) this derives executable **invariants** that hold for ANY correct
+ * implementation, with **no expected values** (no oracle — dodging the "expected is LLM-computed" trap of a
+ * generated test) and **no LLM** (pure deterministic — design/56's "execute > analyze"). Run against an
+ * implementation over many generated inputs, they catch the **structural-contract** bug class deterministically
+ * at **0 false positives** (probe-13: structural 16/16 caught, FP 0/12).
+ *
+ * It is a thin **complement** to the mechanical exit gate ({@link runExecGate}), not a replacement: it provably
+ * **cannot** catch value-semantic bugs — wrong output that is still structurally valid (`abs → square`,
+ * titlecase `don't → Don'T`). Those still need a real test suite (MECH) or the L3 judge. The value is the
+ * **sound invariant library + the contract→invariant derivation** centralized here (a profile re-deriving it
+ * risks unsound invariants = false positives = the thing that makes a gate harmful).
+ *
+ * Honest limits (two independent probes converged — core probe-13 + search [52], both FP=0):
+ * - **The only false-positive risk is an UNFAITHFUL contract.** Each invariant is sound by construction, so a
+ *   *correct* impl can't violate one — UNLESS the contract misdescribes the intended behavior (declaring a
+ *   property the correct impl doesn't have). The contract must faithfully describe intent (it is trusted input).
+ * - **Order/positional blindness.** `permutation`/`subset`/multiset-based invariants are order-agnostic, so a
+ *   wrong-order-but-same-elements result (concat `b+a`, a mis-ordered flatten) passes. That is the value-semantic
+ *   class — catch it with a positional contract entry, a real test (MECH), or the judge.
+ * - **No contract ⇒ no signal.** A function with no declared contract derives zero invariants (zero coverage);
+ *   the catch comes from the *contract* you declare, not from the type alone — this is not magic from signatures.
+ *
+ * Scope (design/58 §2): no type→input generation (caller supplies `genInput`), no multi-language rendering
+ * (this is the JS/TS reference; other languages render their own from {@link FunctionContract}), no
+ * non-termination detection (a sync infinite loop blocks {@link checkInvariants} — gate it with the
+ * env/exec timeout via `runExecGate`; `totalNoThrow` only catches throws).
+ */
+/** Sound, oracle-free invariant kinds (design/58 §1.3). Each holds for ANY correct implementation. */
 export type InvariantKind = "permutation" | "lengthPreserving" | "subset" | "distinctOutput" | "idempotent" | "involution" | "outputPredicate" | "rangeBound" | "nonNegative" | "nonEmptyPreserving" | "concatPreserving" | "chunkMaxLen" | "lengthEq" | "roundtrip" | "totalNoThrow";
+/**
+ * The TRUSTED contract a function is expected to satisfy — from the spec / leader, **never the worker** (BUG8).
+ * The predicate/bound fields carry trusted JS supplied by the spec author (not worker output), so the
+ * in-process model is safe for them.
+ */
 export interface FunctionContract {
+    /** Output is a permutation (same multiset) of the input collection — sort / shuffle / reverse / rotate. */
     permutation?: boolean;
+    /** `|output| === |input collection|`. */
     lengthPreserving?: boolean;
+    /** Output is a sub-multiset of the input collection — filter / take. */
     subset?: boolean;
+    /** Output has no duplicate elements — dedupe / unique. */
     distinctOutput?: boolean;
+    /** `f(f(x))` deep-equals `f(x)` — normalize / sort / dedupe. (Output type must equal input type.) */
     idempotent?: boolean;
+    /** `f(f(x))` deep-equals `x` — reverse / negate. (Output type must equal input type.) */
     involution?: boolean;
+    /** Numeric output is `>= 0` — abs / length / count. */
     nonNegative?: boolean;
+    /** A non-empty input collection implies a non-empty output — titlecase / dedupe. */
     nonEmptyPreserving?: boolean;
+    /** Concatenating the output groups in order deep-equals the input collection — chunk / split. */
     concatPreserving?: boolean;
+    /** The function is an `{ encode, decode }` pair and `decode(encode(x))` deep-equals `x` — serde / base62. */
     roundtrip?: boolean;
+    /** The function must not throw on any valid-typed input. (Non-termination is NOT covered — see file header.) */
     totalNoThrow?: boolean;
+    /** Every output element satisfies this trusted predicate — filter-by-P. */
     outputPredicate?: (el: any) => boolean;
+    /** Numeric output lies within `[lo, hi]` computed from the input by this trusted fn — clamp. */
     rangeBound?: (input: any) => readonly [number, number];
+    /** Every output group has length in `(0, n]` where `n` is this trusted fn of the input — chunk. */
     chunkMaxLen?: (input: any) => number;
+    /** `|output| === ` this trusted fn of the input — e.g. `countdown(n)` has length `n + 1`. */
     lengthEq?: (input: any) => number;
+    /**
+     * Extract the input collection when the input WRAPS it — e.g. `(x) => x.a` for `{ a, k }`. Default: the input
+     * IS the collection. 🔴 Required for the collection invariants when the input is a wrapper object, else they
+     * compare the output against the wrapper instead of the collection (probe-13 soundness fix).
+     */
     inputCollection?: (input: any) => unknown[];
 }
+/** One derived, runnable invariant. `check(fn, input)` returns `true` iff the invariant HOLDS. */
 export interface Invariant {
     kind: InvariantKind;
+    /** Human-readable description (surfaced in a violation). */
     description: string;
+    /** For `roundtrip`, `fn` is the `{ encode, decode }` pair; otherwise a unary function. A throw propagates to the runner. */
     check: (fn: any, input: any) => boolean;
 }
+/** A concrete invariant violation found by {@link checkInvariants}. */
 export interface InvariantViolation {
     kind: InvariantKind;
     description: string;
+    /** The input that triggered it (the first one observed). */
     input: unknown;
+    /** A-5 fold: the violation was detected via the check THROWING on a structurally wrong return value
+     *  (e.g. `.length` of undefined) rather than returning false — the impl's output doesn't even have
+     *  the shape the contract implies. fn itself did NOT throw (that is `totalNoThrow`'s domain). */
     evaluationThrew?: true;
 }
+/** The outcome of running invariants over generated inputs. */
 export interface CheckResult {
+    /** True iff no invariant was violated across all trials. */
     ok: boolean;
+    /** One entry per violated invariant (first triggering input). */
     violations: InvariantViolation[];
+    /** How many inputs were tried. */
     trials: number;
 }
+/**
+ * Derive the sound, oracle-free invariants implied by a trusted {@link FunctionContract}. Pure and
+ * deterministic. The collection invariants honor `contract.inputCollection` (default: the input is the
+ * collection) so a wrapper-object input (`{ a, k }`) is handled correctly.
+ */
 export declare function deriveInvariants(contract: FunctionContract): Invariant[];
+/**
+ * Run derived `invariants` against `fn` over `opts.trials` generated inputs (default 200). Returns the
+ * violated invariants (first triggering input each).
+ *
+ * 🔴 Runs `fn` **in the caller's process** (design/58 §1.2). Pass only a TRUSTED `fn`, or invoke this INSIDE
+ * the worker's sandbox (a generated test the leader drops into the env and runs via `runExecGate`, gating on
+ * exit code). **Non-termination is NOT caught here** — a sync infinite loop blocks the call; bound it with the
+ * env/exec timeout. An impl throw is detected by the self-contained `totalNoThrow` invariant (recorded ONLY
+ * when totality was contracted — soundness over recall); the runner's `catch` is just a safety net so one
+ * pathological input can't crash the whole run. Note: `fn` is invoked once per invariant per trial (twice for
+ * `idempotent`/`involution`) — pass a PURE function (the intended use); a side-effecting `fn` is amplified.
+ */
 export declare function checkInvariants(fn: unknown, genInput: (i: number) => unknown, invariants: Invariant[], opts?: {
     trials?: number;
 }): CheckResult;

package/dist/core/protocol-naming.d.ts

@@ -1,7 +1,45 @@
 import type { ProtocolNamespace } from "./protocol-table.js";
+/** The provider's tool-name pattern is `^[a-zA-Z0-9_-]{1,64}$` — the limit applies to the ASSEMBLED name,
+ *  not to its segments (design/116 W5-5, CC 2.1.187 parity `buildMcpToolName`). */
 export declare const TOOL_NAME_MAX_CHARS = 64;
+/** Reserved for the tool segment when budgeting the peer segment: a peer kept at the full name budget
+ *  overflows the assembled name on its own (prefix + 64 + separator = 71 > 64), which is how the tool
+ *  segment used to be handed a NEGATIVE budget. A tool name shorter than this is not recognizable. */
 export declare const MINTED_TOOL_SEGMENT_MIN_CHARS = 16;
+/**
+ * design/116 W5-5 (CC 2.1.187 parity) — normalize a peer/tool segment to the API tool-name charset by
+ * replacing every other character with `_`. CC does exactly this on BOTH segments when composing
+ * `mcp__<server>__<tool>` (services/mcp/normalization.ts `normalizeNameForMCP` + mcpStringUtils.ts
+ * `buildMcpToolName`), so a peer advertising a dotted/spaced/unicode name can't mint a name the provider
+ * rejects. NOTE: only the MODEL-FACING namespaced name is normalized — the raw remote name still goes on
+ * the wire and still keys the caller-facing maps (`allowTools`/`toolAxes`). Same known collision property
+ * as CC: two remote names that normalize to the same string collide (rare; CC accepts this).
+ *
+ * RB-83 (2026-07-25, red probe): the pattern this enforces is `{1,64}`, and only the charset half was
+ * enforced. Both other halves matter for the same reason the charset does — an over-long or empty segment
+ * produces a name the provider rejects, which 400s the WHOLE model request, the exact failure the intake
+ * gate exists to contain ("a single misconfigured server never bricks the whole task").
+ */
 export declare function normalizeNameSegment(name: string): string;
+/** RB-83: force a normalized segment into `{1,max}`, keeping long names distinct via a stable digest. */
 export declare function clampNameSegment(seg: string, max?: number): string;
+/**
+ * The registered-name prefix for `peer` in `ns` — i.e. the set `name.startsWith(prefix)` that a consumer
+ * uses as its splice domain when swapping one peer's tools wholesale.
+ *
+ * The peer segment is kept as long as the assembled name allows (it is how an operator recognizes which
+ * peer a tool came from) and absorbs the clamp, digest-suffixed, when it does not fit.
+ *
+ * NOT `ns.makeName`: that leg REFUSES a peer carrying the separator, while this pipeline SANITIZES its
+ * inputs (the peer name is deployment/remote data, not a caller-authored identifier) and must not turn a
+ * long or exotic peer name into a materialization failure. SANITIZE, however, means the sanitized result
+ * must be sound: {@link settlePeerSegment} owes the same round-trip guarantee `makeName` gets by refusing
+ * (ticket #10), and the property test holds the two legs to the identical law.
+ */
 export declare function mintNamespacePrefix(ns: ProtocolNamespace, peer: string): string;
+/**
+ * The full registered name for `(peer, tool)` in `ns`. Always starts with {@link mintNamespacePrefix}'s
+ * answer for the same peer (the invariant ticket #9's pins hold), and never exceeds
+ * {@link TOOL_NAME_MAX_CHARS}: whatever the peer segment leaves over is the tool segment's budget.
+ */
 export declare function mintNamespacedToolName(ns: ProtocolNamespace, peer: string, tool: string): string;