@sema-agent/core 7.54.1 → 7.55.0

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

@@ -35,7 +35,8 @@
  * store's, the fence stays the partition's.
  */
 import type { PersistedRule, RuleScope } from "./permission-rule-model.js";
-import { type DurableRulePartitionProvider, type QuarantinedRuleAdd, type RuleOwner } from "./permission-rule-store.js";
+import { type DurableRulePartitionProvider, type QuarantinedRuleAdd } from "./permission-rule-store.js";
+import type { RuleOwner } from "./rule-owner.js";
 import { type OrgRulePartitionConfig, type OrgRuleResolution } from "./permission-rule-org.js";
 import type { SessionRulePartition } from "./permission-rule-session.js";
 import type { StoreDurability, StoreFidelity } from "./checkpoint-store.js";

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

@@ -45,7 +45,7 @@ import type { PersistedRule, RuleAdd, RuleDot, RuleScope, RuleTombstone } from "
 import { type RuleBehavior } from "./permission-rule-model.js";
 import type { RuleSyncDropReason, RuleQuarantineReason } from "./governance-codes.js";
 import type { StoreDurability, StoreFidelity } from "./checkpoint-store.js";
-import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { RuleOwner } from "./rule-owner.js";
 /** One store read: the rules as persisted, their tombstones, and the revision they were read at. */
 export interface StoredRules {
     /** Rules with their FULL add sets — tombstoned dots already removed by the backend on read. */
@@ -56,6 +56,14 @@ export interface StoredRules {
     /** Integrity fingerprint the backend computed, when it has one. Corruption detection only. */
     checksum?: string;
 }
+/**
+ * The code a refusal carries when the rules a face reads — a bucket at rest, a rule-sync state on the wire — are stamped
+ * with a rule grammar later than this engine reads: a newer engine wrote them. Every face refuses them whole with it (the
+ * read face, a write's read of its base, a sync round's local read and its response), so a caller tells "an engine that
+ * reads that grammar reads them" from a damaged store, whose refusal carries no code. The person's rules are then one
+ * partition that cannot be read: every call is asked about until a read succeeds.
+ */
+export declare const PERMISSION_RULES_LATER_GRAMMAR_CODE = "permission_rules.later_grammar";
 /**
  * The durable partition's read face: read-only, already anchored to a single owner. Rows carry the two
  * durable scopes only (`global` = the `user` source, `project` = the `project` source); a session row
@@ -64,6 +72,13 @@ export interface StoredRules {
  * A backend that fails to read must not silently report an empty set as if it were an empty store — it
  * throws, and the store'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.
+ *
+ * A backend keeps ONE rule grammar stamp per bucket: every write stamps this engine's grammar
+ * (`SESSION_RULES_GRAMMAR`), and every read — of the read face and of a write's base — judges the stamp
+ * through `readRuleGrammarStamp` (absent = this engine's grammar, a bucket written before the stamp): a later
+ * grammar is a bucket this engine cannot read, refused whole with {@link PERMISSION_RULES_LATER_GRAMMAR_CODE},
+ * never read row by row (a row a newer grammar wrote reads as nothing here, and a deny that reads as nothing
+ * refuses nothing).
  */
 export interface DurableRulePartition {
     list(): Promise<StoredRules>;
@@ -78,30 +93,6 @@ export interface DurableRulePartition {
     /** Declared serialization fidelity, same doctrine as the other store families. */
     readonly fidelity?: StoreFidelity;
 }
-/**
- * design/182 §3.3/§4.5 — who a rule bucket belongs to, as a STRUCTURAL position.
- *
- * Identity absence is spelled as a distinct union member, never as a sentinel string flowing through
- * `forPrincipal` — every consumer of a principal string is an identity surface, and a made-up name on an
- * identity surface is indistinguishable from a real one downstream. Cloud sync and cloud tickets accept
- * ONLY the `principal` kind: syncing is an authenticated act, and a local-owner bucket has no cloud home
- * until it is adopted (`adoptFilePermissionRuleStore`).
- */
-export type RuleOwner = {
-    kind: "principal";
-    principal: string;
-} | {
-    kind: "local-owner";
-};
-/** The owner discriminants as a value: the `kind` words of {@link RuleOwner}, both directions fenced at compile time
- *  ({@link RuleOwnerKindsCoverEveryArm} / {@link RuleOwnerArmsCoverEveryKind}). */
-export declare const RULE_OWNER_KINDS: readonly ["principal", "local-owner"];
-/** Compile fence: an arm whose `kind` is not in {@link RULE_OWNER_KINDS} turns the argument into that word. */
-export type RuleOwnerKindsCoverEveryArm = AssertAllKeysHandled<Exclude<RuleOwner["kind"], (typeof RULE_OWNER_KINDS)[number]>>;
-/** Compile fence, the other direction: a word in {@link RULE_OWNER_KINDS} that no arm carries. */
-export type RuleOwnerArmsCoverEveryKind = AssertAllKeysHandled<Exclude<(typeof RULE_OWNER_KINDS)[number], RuleOwner["kind"]>>;
-/** Do two owners name the same bucket? */
-export declare function sameRuleOwner(a: RuleOwner, b: RuleOwner): boolean;
 /** Resolves one owner's durable partition. `undefined` ⇒ a partition that reports zero rules. This is
  *  the BACKEND contract (file, in-memory, an out-of-repo SQL twin); the engine never consumes it
  *  directly — `createPermissionRuleStoreProvider({ durable })` composes it into the unified store. */
@@ -497,6 +488,10 @@ export declare function normalizePersistedRule(r: PersistedRule): {
     reject: Extract<RuleSyncDropReason, "invalid_rule_text" | "metadata_mismatch">;
 };
 /** The normalization half exposed for the DISCLOSURE layer: which records a join would refuse, and why.
+ *
+ *  It reads a state in THIS engine's grammar: the doors that hand it one — a backend's read of its bucket, the sync
+ *  client's read of a response — refuse a state stamped later whole first ({@link PERMISSION_RULES_LATER_GRAMMAR_CODE}),
+ *  so a row it refuses is damage to drop or quarantine, never a newer grammar's rule read as nothing.
  *
  *  design/382 §4.3 — this screen carries the SESSION member of the durable face on every JOIN leg
  *  (inbound state, local state, both sides of the pure join): a rule or tombstone row carrying a

package/dist/core/permission-rule-store.js

@@ -3,10 +3,7 @@ import { canonicalize } from "./canonical-json.js";
 import { escapeForDisclosure, isRuleBehavior, isRuleLive, parseRuleText } from "./permission-rule-model.js";
 import { thrownText } from "./thrown-value.js";
 import { validatePath } from "./effective-path-target.js";
-export const RULE_OWNER_KINDS = Object.freeze(["principal", "local-owner"]);
-export function sameRuleOwner(a, b) {
-    return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
-}
+export const PERMISSION_RULES_LATER_GRAMMAR_CODE = "permission_rules.later_grammar";
 export function isRuleRevision(rev) {
     return typeof rev === "number" && Number.isSafeInteger(rev) && rev >= 0;
 }

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

@@ -27,7 +27,8 @@
  */
 import type { PersistedRule, RuleBehavior, RuleDot, RuleRejectCode, RuleScope, RuleTombstone } from "./permission-rule-model.js";
 import type { PermissionRuleStoreProvider } from "./permission-rule-provider.js";
-import type { RuleOwner, RuleSyncDrop, RuleSyncFrontier, RuleSyncState } from "./permission-rule-store.js";
+import type { RuleOwner } from "./rule-owner.js";
+import type { RuleSyncDrop, RuleSyncFrontier, RuleSyncState } from "./permission-rule-store.js";
 import { type TracerHook } from "./trace.js";
 /** The injected HTTP seam — core never bundles a fetch. The deployment owns base URL, auth, TLS and
  *  retries; a non-2xx / network failure should THROW (the round then aborts with zero local effects —
@@ -43,6 +44,9 @@ export interface RuleSyncRequestBody {
     replica: string;
     state: RuleSyncState;
     observedVector?: RuleSyncFrontier;
+    /** The rule grammar this engine reads and writes the state's rows in (`SESSION_RULES_GRAMMAR`) — a twin whose grammar is
+     *  earlier refuses the whole request, as this client refuses a response stamped later. */
+    grammar: number;
 }
 /** The wire response (server twin: join its persisted state with the request state, answer the whole
  *  merged form). `gcFrontier` is the COLLECTED watermark (§5.1) — absent in v2.0 by protocol. */
@@ -58,6 +62,10 @@ export interface RuleSyncResponseBody {
         dot: RuleDot;
         reason: string;
     }>;
+    /** The rule grammar the merged state's rows are written in. A grammar later than this engine's refuses the whole round
+     *  (`PERMISSION_RULES_LATER_GRAMMAR_CODE`): read in this engine's grammar, a newer grammar's row reads as nothing, and a
+     *  deny among them would be dropped as damage. Absent: a twin that predates the member, read in this engine's. */
+    grammar?: number;
 }
 export interface PermissionRuleSyncResult {
     /** True ⟺ the round landed with zero drops, zero quarantines and zero warnings. */
@@ -154,7 +162,8 @@ interface ParsedRuleSyncResponse {
 }
 /**
  * Parse one wire response. Envelope violations (missing/mistyped principal, echo mismatch, no merged
- * state, an unparseable frontier) THROW — a protocol error aborts the round with zero local effects.
+ * state, an unparseable frontier, a grammar stamp this engine cannot read) THROW — a protocol error aborts
+ * the round with zero local effects.
  * ENTRY-level violations degrade per §4.3: an unshapeable rule/add is skipped with a warning (it never
  * reaches the local disk); an unshapeable tombstone is surfaced as `undefined` so the caller's
  * tighten-only partitioning withholds the round's adds. Unknown keys never flow anywhere — every field

package/dist/core/permission-rule-sync.js

@@ -1,6 +1,7 @@
 import { escapeForDisclosure, isRuleBehavior, parseRuleText, RULE_ADD_ORIGINS } from "./permission-rule-model.js";
-import { applyTombstones, errText, isProjectScopeRoot, joinFrontiers, joinRuleStates, normalizePersistedRule, readRuleWriteOutcome, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
+import { PERMISSION_RULES_LATER_GRAMMAR_CODE, applyTombstones, errText, isProjectScopeRoot, joinFrontiers, joinRuleStates, normalizePersistedRule, readRuleWriteOutcome, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
 import { emitTrace } from "./trace.js";
+import { SESSION_RULES_GRAMMAR, readRuleGrammarStamp } from "./session-policy-store.js";
 export const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
 export const LOCAL_OWNER_UNSYNCABLE_CODE = "permission_rules.local_owner_unsyncable";
 function refuseLocalOwnerSync() {
@@ -64,6 +65,7 @@ export async function syncPermissionRules(opts) {
         replica: raw.actor,
         state: { rules: raw.rules, tombstones: raw.tombstones },
         ...(raw.observedVector !== undefined ? { observedVector: raw.observedVector } : {}),
+        grammar: SESSION_RULES_GRAMMAR,
     };
     const rawResponse = await transport(PERMISSION_RULE_SYNC_PATH, request);
     const response = parseRuleSyncResponse(rawResponse, principal);
@@ -310,6 +312,11 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
     if (echoedPrincipal !== expectedPrincipal) {
         throw new Error(`the sync response echoes principal "${escapeForDisclosure(echoedPrincipal)}" but this round synced "${escapeForDisclosure(expectedPrincipal)}" — the transport is wired to the wrong bucket; refusing the whole round`);
     }
+    const grammar = readRuleGrammarStamp(r.grammar, SESSION_RULES_GRAMMAR, { rules: "the sync response's rules", held: "rows" });
+    if ("got" in grammar) {
+        const refusal = new Error(`${grammar.sentence} — refusing the whole round, nothing landed`);
+        throw grammar.later === true ? Object.assign(refusal, { code: PERMISSION_RULES_LATER_GRAMMAR_CODE }) : refusal;
+    }
     const merged = r.merged;
     const mergedRules = merged?.rules;
     const mergedTombstones = merged?.tombstones;

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

@@ -1,5 +1,5 @@
 /**
- * design/127 — **参数级权限规则 DSL**(CC 2.1.201 追平批 γ)。声明式规则字符串 → {@link ToolPolicy}
+ * design/127 — **参数级权限规则 DSL**(追平批 γ)。声明式规则字符串 → {@link ToolPolicy}
  * 编译器:`"Tool"`(裸)/ `"Tool(param:pattern)"`(参数级,`*` 通配全串锚定)。CC ground truth
  * 行号级:解析 `Lh` :55214 · 通配 `ZMr` :55196 · 参数级 matcher `gnn` :595123 · 评估序 `G1e` :595272。
  *
@@ -46,11 +46,21 @@
  *
  * The NAME lane is the same shape for the tools of `NAME_RULE_FACES` (the `Skill` tool): a `Skill(<name>)` / `Skill(<prefix>:*)`
  * deny or ask — the reference's own spelling — compiles through the same validator (the model's name grammar) and is judged on the
- * one string the call names (`nameRuleSubjectOf`) with `nameRuleAdmits`, the reader the persisted rule store uses. The parameter
+ * one string the call names (`nameRuleSubjectOf`) with `nameRuleReach`, the predicate the persisted rule store uses. The parameter
  * spelling `Skill(skill:<name>)` those tools used to take is retired: refused loudly, its sentence naming the CC form. A KEYED
  * value tool (`Artifact(action:<word>)`) takes the same lane for content keyed by its own parameter (`nameGrammarReads`); its
- * other arguments stay on the generic `param:pattern` lane. A call of it that names no value for the key as the tool reads it
- * is refused by the key's deny or ask rule (`keyedValueAbsentReason`, the persisted lane's reading).
+ * other arguments stay on the generic `param:pattern` lane. The delegation tool's `Agent(<subagent_type>)` takes it too, its
+ * value and the call's resolved against the agent types the call's face carries (`nameRuleReach`), its other arguments on the
+ * generic lane. A call of a closed-set tool that names no value as the tool reads it is refused by the tool's deny or ask rule
+ * (`nameValueAbsentReason`, the persisted lane's reading).
+ *
+ * The HOST lane is the same shape for a tool name the catalog declares a host target for (the URL its call reaches —
+ * `WebFetch`'s `url`): a `WebFetch(domain:<host>)` / `WebFetch(domain:*.<domain>)` deny or ask — the reference's own spelling —
+ * compiles through the model's domain grammar and is judged on the host the call reaches (`callHostTargetOf`, the protective
+ * reading: the call face's slot, the catalog's for the name as the floor) with `domainRuleAdmits`, the reader a person's stored
+ * rows and the entry lists use. Every lane is one dispatch over the rule's name and content (`ruleLaneOf`), so the static
+ * compile and a leg's roster compile read every rule the same way. A call whose host cannot be read is refused by a host deny
+ * rule and is the fail-closed ask under a host ask rule.
  *
  * 🔴 与 CC 的有意差(design/127 r2):
  *  - CC 参数级 generic 道无 allow lane(gnn 只有 deny/ask)—— 我们同样,且整个 policy 无 allow 臂。
@@ -102,6 +112,11 @@ export interface PermissionRuleIssue {
      *  is an object/array (a rule on it can never match); the tool is unknown to the resolver a leg
      *  supplied (absent resolver ⇒ the catalog alone judges and an unknown tool stays permissive). */
      | "unsupported.param_unknown" | "unsupported.param_non_scalar" | "unsupported.tool_unknown"
+    /** A deny/ask name rule whose value the fold lands on SEVERAL of the values the leg's mounted tool declares
+     *  (`Agent(codereview)` on a leg offering `code-review` and `code_review`): which one it names is not determinable, and a rule
+     *  is never resolved to one of several — refused when the leg's `ruleFaces` carry the values (without them the rule reaches
+     *  every such value at the gate). */
+     | "invalid.name_ambiguous"
     /** A path-form deny/ask whose spelling needs a base this policy DECLARES as something other than an absolute path
      *  of its tree's family (`/x` reads `pathBases.root`; a relative pattern `pathBases.cwd`, else `root`; `~/` `home`)
      *  — a bad declared value, refused rather than compiled into a rule that reaches nothing. An undeclared base is no
@@ -117,8 +132,29 @@ export interface PermissionRuleIssue {
     /** 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";
+    /** What a person can do about the rule — never a construction option of the library: those ride on {@link libraryOption}. */
     message: string;
+    /**
+     * The engine-side library coordinate this refusal relates to — a name a host program or a spec author holds and a person
+     * writing rules does not: a construction option of the compile call (a key of {@link PermissionRulePolicyOptions}, a
+     * `pathBases` / `caps` entry spelled `pathBases.<word>` / `caps.<key>`), the allow-list seat of a request or of a deployment
+     * (`TaskSpec.allowedTools` / `RunnerDeps.allowedTools`), or the MCP server spec's per-tool declaration (`toolAxes`). Present
+     * where the engine offers it as the way out of the refusal, or names it as the declaration the refusal rests on (a rule set
+     * over its cap, a declared base that is no path, the list that is no list) — not wherever some other value of an option would
+     * happen to change the answer (a resolver that declared more parameters would also make a misspelled one compile; that is not
+     * a way out). The sentence never names it, so a host that exposes the coordinate renders it and any other host shows the
+     * sentence alone. Minted in one place ({@link ruleIssue}).
+     */
+    libraryOption?: {
+        name: "primaryFieldGeneric" | "defaultAction" | "ruleFaces" | `pathBases.${keyof PathRuleBases}` | `caps.${keyof PermissionRuleCaps}` | "TaskSpec.allowedTools" | "RunnerDeps.allowedTools" | "toolAxes";
+        /** The value that opts in, when the way out is one value (`primaryFieldGeneric` ⇒ `"allow-lexical"`); absent when the option
+         *  takes the host's own choice (a cap's size, a base's path, the answer for calls no rule reaches). */
+        value?: string;
+    };
 }
+/** THE mint of a {@link PermissionRuleIssue}: every issue the compiler and the allow-list screen report is made here, so the
+ *  optional {@link PermissionRuleIssue.libraryOption} is written at one place and an absent one is absent, never `undefined`. */
+export declare function ruleIssue(rule: string, code: PermissionRuleIssue["code"], message: string, libraryOption?: PermissionRuleIssue["libraryOption"]): PermissionRuleIssue;
 export interface PermissionRuleCaps {
     maxRules: number;
     maxRuleLength: number;
@@ -175,18 +211,20 @@ export { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch }
 /**
  * design/388 A-6/7/8/9 (D-3): the per-tool RULE FACE — the parameters a `Tool(param:pattern)` rule may name
  * (`params`, the SCALAR top-level keys ∪ the path target's aliases), the ones the generic lexical matcher must
- * not be pointed at (`primaryParams`), the carried-but-non-scalar keys a rule can never match (`nonScalar`), and
- * whether the tool names a path target at all (the file-tool glob lane). Resolved through
- * {@link PermissionRulePolicyOptions.ruleFaces} when a leg supplies its roster, else from the static catalog
- * — the three hand-kept tables (`PRIMARY_FIELDS` / `FILE_TOOLS` / `FILE_TOOL_PARAMS`) this replaced are gone.
+ * not be pointed at (`primaryParams`) and the carried-but-non-scalar keys a rule can never match (`nonScalar`). Resolved
+ * through {@link PermissionRulePolicyOptions.ruleFaces} when a leg supplies its roster, else from the static catalog — the
+ * three hand-kept tables (`PRIMARY_FIELDS` / `FILE_TOOLS` / `FILE_TOOL_PARAMS`) this replaced are gone. Which lane a rule
+ * takes is not the face's to say: it is the rule's name's grammar (`ruleLaneOf`), the same with or without a resolver.
  */
 export interface RuleFaceView {
     primaryParams: readonly string[];
-    /** The full scalar vocabulary; ABSENT when the resolver does not know it (the static catalog for a
-     *  definition whose schema is factory-built) — then only the primary-field check applies. */
+    /** The full scalar vocabulary. A face that states none declares its `primaryParams` only: a rule naming any other
+     *  parameter is refused (`unsupported.param_unknown`) — a face never leaves a parameter name unjudged. */
     params?: readonly string[];
     nonScalar?: readonly string[];
-    pathTargeting?: boolean;
+    /** The values the mounted tool takes for the argument its name rules are read against (`ToolRuleFace.nameValues`): with them a
+     *  name rule whose value the fold lands on several of them is refused at compile (`invalid.name_ambiguous`). */
+    nameValues?: readonly string[];
 }
 /** The static catalog's answer for a wire name (undefined ⇒ the catalog does not carry it). */
 export declare function catalogRuleFaceView(toolName: string): RuleFaceView | undefined;