@sema-agent/core 7.54.1 → 7.56.0

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

@@ -224,6 +224,9 @@ export interface UnreadableOrgRow {
     readonly rule: string;
     readonly code: RuleRejectCode;
     readonly detail?: string;
+    /** The rule spelling a row that is no rule spelling only because of white space (a tab, a no-break space) is a blank away from — the
+     *  text to republish it as; the row itself is still read as unreadable (one spelling reader, fail-closed). */
+    readonly respelling?: string;
     readonly behavior: "deny" | "ask";
     readonly reach: OrgRowReach;
 }
@@ -327,8 +330,9 @@ export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[
     rule: string;
     code: RuleRejectCode;
 }>;
-/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair. */
-export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail">): string;
+/** The reason an unreadable row's verdict carries — its place in the snapshot, its code, and the repair: for a row that is no rule
+ *  spelling only because of white space (a tab, a no-break space), its text and the spelling to republish it as. */
+export declare function unreadableOrgRowReason(row: Pick<UnreadableOrgRow, "index" | "code" | "detail" | "rule" | "respelling">): string;
 /** The ONE clause for an org verdict that carries an `unreadable` reason — a rule the call could not be read against, or
  *  a row this layer cannot read — on a refusal and on a question alike. */
 export declare function orgUnreadableClause(reason: string): string;

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

@@ -284,12 +284,13 @@ function orgStateCopyOf(state) {
 function readOrgRow(row, index) {
     const { rule: text, behavior: said } = orgRowPolicyOf(row);
     const behavior = said === "ask" ? "ask" : "deny";
-    const unreadable = (code, detail) => ({
+    const unreadable = (code, detail, respelling) => ({
         kind: "unreadable",
         index,
         rule: typeof text === "string" ? text : text === undefined ? "<unreadable>" : escapeForDisclosure(text),
         code,
         ...(detail !== undefined ? { detail } : {}),
+        ...(respelling !== undefined ? { respelling } : {}),
         behavior,
         reach: reachOfRowHead(text, behavior),
     });
@@ -299,7 +300,7 @@ function readOrgRow(row, index) {
         return unreadable("invalid.grammar", said === undefined ? "no behavior" : `behavior "${escapeForDisclosure(said)}" is not deny or ask`);
     const parsed = parseRuleText(text, said);
     if ("reject" in parsed)
-        return unreadable(parsed.reject.code);
+        return unreadable(parsed.reject.code, undefined, parsed.reject.respelling);
     if (parsed.rule.tool !== COMMAND_RULE_TOOL)
         return unreadable("unsupported.tool");
     return { kind: "read", index, rule: text, behavior: said, parsed: parsed.rule };
@@ -355,6 +356,9 @@ function readListedOrgRules(rules) {
     return reading;
 }
 export function unreadableOrgRowReason(row) {
+    if (row.respelling !== undefined) {
+        return `row ${row.index} of the organization snapshot, "${escapeForDisclosure(row.rule)}", is not a rule spelling (${row.code}); republish it as "${escapeForDisclosure(row.respelling)}"`;
+    }
     return `row ${row.index} of the organization snapshot is not a rule this layer reads (${row.code}${row.detail !== undefined ? `: ${row.detail}` : ""}); republish it in the shell tool's command grammar`;
 }
 export function orgUnreadableClause(reason) {
@@ -365,7 +369,7 @@ export function describeUnreadableOrgRows(unreadable, revision) {
         return undefined;
     const named = unreadable
         .slice(0, DISCLOSED_UNREADABLE_ROWS)
-        .map((u) => `row ${u.index} "${escapeForDisclosure(u.rule)}" (${u.code}${u.detail !== undefined ? `: ${u.detail}` : ""})`)
+        .map((u) => `row ${u.index} "${escapeForDisclosure(u.rule)}" (${u.code}${u.detail !== undefined ? `: ${u.detail}` : ""}${u.respelling !== undefined ? `; republish it as "${escapeForDisclosure(u.respelling)}"` : ""})`)
         .join(", ");
     const more = unreadable.length - DISCLOSED_UNREADABLE_ROWS;
     return (`the org snapshot${revision !== undefined ? ` (revision ${escapeForDisclosure(revision)})` : ""} is served DEGRADED: ${unreadable.length} row(s) this layer cannot read — ${named}${more > 0 ? ` and ${more} more` : ""}; ` +

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";
@@ -145,7 +146,10 @@ export interface PermissionRuleStoreProvider {
  * provider: an absent principal resolves to zero personal rules, and a provider that forgot it would hand one person's
  * standing approvals to an anonymous task. The ONE exception is an explicitly declared LOCAL-OWNER deployment, where "no
  * principal" is the typed absence of identity — the machine owner's own bucket (a provider with no such face resolves
- * the anonymous store; {@link createPermissionRuleLanes} refuses that declaration loudly).
+ * the anonymous store; {@link createPermissionRuleLanes} refuses that declaration loudly). "No principal" is ABSENCE only —
+ * `undefined`, and the empty string the engine has always spelled the same ({@link readPrincipal}). A principal that was provided
+ * and is not a name (white space, an invisible or control character) is a bad value and is refused here: read as absence it
+ * would be the machine owner's bucket on a local-owner deployment.
  */
 export declare function ownerStoreOf(provider: PermissionRuleStoreProvider, principal: string | undefined, localOwnerDeclared: boolean): PermissionRuleStore;
 /** What {@link createPermissionRuleStoreProvider} composes. */

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

@@ -1,17 +1,39 @@
-import { escapeForDisclosure } from "./permission-rule-model.js";
+import { escapeForDisclosure, isRuleBehavior, parseRuleText } from "./permission-rule-model.js";
 import { PERMISSION_RULE_WRITER, errText, isValidDurableScope, normalizePersistedRule, sameRuleIdentity, writerOf, } from "./permission-rule-store.js";
+import { readRuleOwner } from "./rule-owner.js";
+import { readPrincipal } from "./principal-name.js";
 import { UNGOVERNED_ORG_RESOLUTION, compileOrgShadowPredicate, createOrgRulePartition } from "./permission-rule-org.js";
 export function ruleSourceOf(scope) {
     return scope.kind === "global" ? "user" : scope.kind;
 }
 export function ownerStoreOf(provider, principal, localOwnerDeclared) {
-    const anonymous = principal === undefined || principal === "";
-    return anonymous && localOwnerDeclared && provider.forLocalOwner !== undefined ? provider.forLocalOwner() : provider.forPrincipal(anonymous ? undefined : principal);
+    const reading = readPrincipal(principal);
+    if (reading.kind === "invalid") {
+        throw new Error(`the principal given is not a principal name (got ${reading.fault}) — refusing to resolve a bucket for it; a provided value that names nobody is not "no principal"`);
+    }
+    if (reading.kind === "name")
+        return provider.forPrincipal(reading.name);
+    return localOwnerDeclared && provider.forLocalOwner !== undefined ? provider.forLocalOwner() : provider.forPrincipal(undefined);
 }
 function usableSessionId(sessionId) {
     return typeof sessionId === "string" && sessionId !== "" ? sessionId : undefined;
 }
 const EMPTY_DURABLE = { rules: [], tombstones: [], rev: 0 };
+function durableReadOf(settled) {
+    if (!settled.ok)
+        return settled;
+    for (const [kind, rows] of [["rule", settled.v.rules], ["tombstone", settled.v.tombstones]]) {
+        const at = rows.findIndex((r) => !isRuleBehavior(r?.behavior));
+        if (at < 0)
+            continue;
+        const row = rows[at];
+        return {
+            ok: false,
+            e: new Error(`the persisted rule partition served a ${kind} row (#${at}, ${escapeForDisclosure(row?.rule)}) whose behavior word ${escapeForDisclosure(row?.behavior)} is outside deny/ask/allow — whether it refuses a call is unknown, so the partition is read as one that could not be read`),
+        };
+    }
+    return settled;
+}
 export function createPermissionRuleStoreProvider(cfg) {
     if (cfg === null || typeof cfg !== "object") {
         throw new Error("createPermissionRuleStoreProvider takes a config object naming the partitions to compose");
@@ -61,7 +83,7 @@ class UnifiedPermissionRuleStore {
         const disclosures = [];
         const [orgSettled, durableSettled, sessionRows] = await Promise.all([
             this.org !== undefined ? this.org.resolve() : Promise.resolve({ ...UNGOVERNED_ORG_RESOLUTION, rules: [], disclosures: [] }),
-            this.durable !== undefined ? this.durable.list().then((v) => ({ ok: true, v }), (e) => ({ ok: false, e })) : Promise.resolve({ ok: true, v: EMPTY_DURABLE }),
+            this.durable !== undefined ? this.durable.list().then((v) => durableReadOf({ ok: true, v }), (e) => ({ ok: false, e })) : Promise.resolve({ ok: true, v: EMPTY_DURABLE }),
             this.readSessionRows(usableSessionId(query?.sessionId), disclosures),
         ]);
         const orgResolution = orgSettled;
@@ -106,7 +128,7 @@ class UnifiedPermissionRuleStore {
             const served = structuredClone(await this.session.read(sessionId));
             const rows = served.filter((r) => {
                 const scope = r?.scope;
-                return scope?.kind === "session" && scope.sessionId === sessionId && !("reject" in normalizePersistedRule(r));
+                return scope?.kind === "session" && scope.sessionId === sessionId && (!("reject" in normalizePersistedRule(r)) || ((r.behavior === "deny" || r.behavior === "ask") && "reject" in parseRuleText(r.rule, r.behavior)));
             });
             if (rows.length < served.length) {
                 disclosures.push(`the session rule partition served ${served.length - rows.length} row(s) that are not canonical session rows of this session — dropped, not adjudicated`);
@@ -157,8 +179,17 @@ export async function effectivePermissionRules(opts) {
     return await resolveOwnerStore(opts).effective(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : undefined);
 }
 export function resolveOwnerStore(opts) {
-    if (opts.owner !== undefined && opts.owner.kind === "local-owner") {
-        if (opts.principal !== undefined) {
+    const owner = opts.owner === undefined ? undefined : readRuleOwner(opts.owner);
+    if (opts.owner !== undefined && owner === undefined) {
+        throw new Error("the owner given is neither a principal nor the local owner (a principal owner names a principal name) — refusing to resolve a bucket nobody can name");
+    }
+    const given = readPrincipal(opts.principal);
+    if (given.kind === "invalid") {
+        throw new Error(`the principal given is not a principal name (got ${given.fault}) — pass a verified principal, the local owner, or neither; a provided value that names nobody is not "no principal"`);
+    }
+    const principal = given.kind === "name" ? given.name : undefined;
+    if (owner?.kind === "local-owner") {
+        if (principal !== undefined) {
             throw new Error("pass either a principal or a local-owner, not both — a bucket has one owner");
         }
         const store = opts.provider.forLocalOwner?.();
@@ -167,9 +198,8 @@ export function resolveOwnerStore(opts) {
         }
         return store;
     }
-    if (opts.owner !== undefined && opts.owner.kind === "principal" && opts.principal !== undefined && opts.owner.principal !== opts.principal) {
-        throw new Error(`contradictory identity: principal "${escapeForDisclosure(opts.principal)}" and owner principal "${escapeForDisclosure(opts.owner.principal)}" disagree`);
+    if (owner?.kind === "principal" && principal !== undefined && owner.principal !== principal) {
+        throw new Error(`contradictory identity: principal "${escapeForDisclosure(principal)}" and owner principal "${escapeForDisclosure(owner.principal)}" disagree`);
     }
-    const principal = opts.owner?.kind === "principal" ? opts.owner.principal : opts.principal;
-    return opts.provider.forPrincipal(principal);
+    return opts.provider.forPrincipal(owner?.kind === "principal" ? owner.principal : principal);
 }

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,31 +93,8 @@ 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
+/** Resolves one owner's durable partition. `undefined` — or anything that is not a principal name
+ *  (`principalNameOf`: the empty and the blank string included) ⇒ 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. */
 export interface DurableRulePartitionProvider {
@@ -497,6 +489,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

@@ -1,12 +1,10 @@
 import { randomBytes } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
 import { escapeForDisclosure, isRuleBehavior, isRuleLive, parseRuleText } from "./permission-rule-model.js";
+import { readRuleOwner } from "./rule-owner.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;
 }
@@ -513,6 +511,10 @@ async function readRuleLiveness(store, identity) {
     }
 }
 const REMOVE_MAX_ATTEMPTS = 8;
+const NO_TARGET_OWNER = "the principal given is neither a principal name (a string with a visible character, no control or separator character, and no format character but a joiner) nor an owner (a principal owner names a principal name; the local owner is { kind: \"local-owner\" })";
+function persistedRuleTargetOwner(target) {
+    return readRuleOwner(typeof target === "string" ? { kind: "principal", principal: target } : target);
+}
 export async function removePersistedRule(opts) {
     const behavior = opts.behavior;
     const rule = opts.rule;
@@ -522,7 +524,9 @@ export async function removePersistedRule(opts) {
         return { status: "failed", error: `removePersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry`, committed: "no" };
     }
     const identity = { behavior, rule, scope };
-    const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
+    const owner = persistedRuleTargetOwner(target);
+    if (owner === undefined)
+        return { status: "failed", error: `removePersistedRule: ${NO_TARGET_OWNER} — refusing to remove from a bucket nobody can name`, committed: "no" };
     const provider = opts.provider;
     if (scope?.kind === "session") {
         return {
@@ -689,7 +693,9 @@ export async function addPersistedRule(opts) {
     if ("reject" in parsed)
         return { status: "failed", error: `addPersistedRule: ${parsed.reject.code}: ${parsed.reject.message}`, committed: "no" };
     const identity = { behavior, rule: parsed.rule.rule, scope };
-    const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
+    const owner = persistedRuleTargetOwner(target);
+    if (owner === undefined)
+        return { status: "failed", error: `addPersistedRule: ${NO_TARGET_OWNER} — refusing to write into a bucket nobody can name`, committed: "no" };
     const provider = opts.provider;
     if (owner.kind === "local-owner" && provider.forLocalOwner === undefined) {
         return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be added through it", committed: "no" };

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,8 @@
 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 { principalNameOf } from "./principal-name.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() {
@@ -22,8 +24,8 @@ export async function syncPermissionRules(opts) {
             throw new Error(`contradictory identity: principal "${escapeForDisclosure(principal)}" and owner principal "${escapeForDisclosure(owner.principal)}" disagree`);
         }
     }
-    if (typeof principal !== "string" || principal === "") {
-        throw new Error("syncPermissionRules requires a verified principal — an unauthenticated deployment has no cloud bucket to sync");
+    if (principalNameOf(principal) === undefined) {
+        throw new Error("syncPermissionRules requires a verified principal — an unauthenticated deployment has no cloud bucket to sync (a blank name, or one holding a control, separator or invisible format character, is not a principal)");
     }
     const traceClock = opts.now ?? Date.now;
     const disclose = (result) => {
@@ -64,6 +66,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 +313,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-rule-syntax.d.ts

@@ -29,10 +29,11 @@ export declare function lastIndexOfUnescaped(s: string, ch: string): number;
  */
 export declare function parsePermissionRule(rule: string): ParsedPermissionRule;
 /**
- * Can a rule name this tool name — is it the rule syntax's name head ({@link RULE_TOOL_NAME}) and not the lone `*`? The
- * lone `*` is the wildcard (every tool), not a name: a tool called `*` could never be granted or refused on its own. The
- * mount contract for every name a caller tool answers to (its name and each alias), so each one is a name every list can
- * write; a protocol-minted name (`<ns>__<peer>__<tool>`, segments in `[A-Za-z0-9_-]`) is always one.
+ * Can a rule name this tool name — is it the rule syntax's name head ({@link RULE_TOOL_NAME}) with no `*` in it? A `*` makes a
+ * spelling a glob over names, not a name: a tool whose name held one would be reached by every rule whose glob matches it and
+ * could never be named on its own (the reference's mount spelling holds no `*` either). The mount contract for every name a
+ * caller tool answers to (its name and each alias), so each one is a name every list can write; a protocol-minted name
+ * (`<ns>__<peer>__<tool>`, segments in `[A-Za-z0-9_-]`) is always one.
  */
 export declare function isNameableToolName(name: string): boolean;
 /**

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

@@ -36,9 +36,9 @@ export function parsePermissionRule(rule) {
         return { toolName: name.trim() };
     return { toolName: name.trim(), ruleContent: unescapeRuleContent(content) };
 }
-const RULE_TOOL_NAME = /^(?:\*|[A-Za-z0-9_](?:[A-Za-z0-9_.:*-]*[A-Za-z0-9_*-])?)$/;
+const RULE_TOOL_NAME = /^[A-Za-z0-9_*](?:[A-Za-z0-9_.:*-]*[A-Za-z0-9_*-])?$/;
 export function isNameableToolName(name) {
-    return typeof name === "string" && name !== "*" && RULE_TOOL_NAME.test(name);
+    return typeof name === "string" && !name.includes("*") && RULE_TOOL_NAME.test(name);
 }
 export function ruleSpellingOf(rule) {
     if (rule !== rule.trim())

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 臂。
@@ -80,8 +90,8 @@ export interface PermissionRuleIssue {
     /** A rule the rule syntax reads no rule in (`ruleSpellingOf`) whose name is the reason: blanks around the rule, a
      *  character outside a tool name's spelling (a variation selector, a filler, a zero-width space), a blank or an invisible
      *  character before the `(`, a leading `-`. Refused — the lenient reading would deny a tool under another spelling, or none.
-     *  Also a rule whose tool name the syntax reads as the wildcard `*` (`*`, `*()`, `*(*)`): a rule reaches the tool it
-     *  names, and `*` names none. */
+     *  (A `*` in a tool name is no such spelling: a deny or ask rule reads it as a glob over the whole name, `*` alone as every
+     *  tool.) */
      | "invalid.tool_name" | "invalid.param_split" | "invalid.primary_field" | "invalid.cap_exceeded"
     /** An ALLOW rule (any spelling): a policy fold says deny / ask only — "this does not need asking" is the allow
      *  layer's (`TaskSpec.allowedTools`, `RunnerDeps.allowedTools`). One issue per allow rule. */
@@ -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;
@@ -170,23 +206,25 @@ export interface PermissionRulePolicyOptions {
      */
     pathBases?: PathRuleBases;
 }
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
-export { isNamespacedCoveringRuleName, namespacedRuleNameCovers, wildcardMatch };
+import { isCoveringRuleName, ruleNameCovers, wildcardMatch } from "./namespaced-rule-name.js";
+export { isCoveringRuleName, ruleNameCovers, 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;