@sema-agent/core 7.7.0 → 7.9.0

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

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import { canonicalize } from "./canonical-json.js";
-import { escapeForDisclosure, isRuleLive, parseAllowRuleText } from "./permission-rule-model.js";
+import { escapeForDisclosure, isRuleBehavior, isRuleLive, parseRuleText } from "./permission-rule-model.js";
 export function sameRuleOwner(a, b) {
     return a.kind === "principal" ? b.kind === "principal" && a.principal === b.principal : b.kind === "local-owner";
 }
@@ -19,19 +19,22 @@ export function sameScope(a, b) {
 function sameDot(a, b) {
     return a.actor === b.actor && a.counter === b.counter;
 }
+export function sameRuleIdentity(a, b) {
+    return a.behavior === b.behavior && a.rule === b.rule && sameScope(a.scope, b.scope);
+}
 export function applyTombstones(rules, tombstones) {
     return rules
         .map((r) => {
-        const removed = tombstones.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        const removed = tombstones.filter((t) => sameRuleIdentity(t, r)).flatMap((t) => t.removedDots);
         return removed.length === 0 ? r : { ...r, adds: r.adds.filter((a) => !removed.some((d) => sameDot(d, a.dot))) };
     })
         .filter(isRuleLive);
 }
 export function foldDelta(rules, delta) {
     const next = rules.map((r) => ({ ...r, adds: [...r.adds] }));
-    const existing = next.find((r) => r.rule === delta.rule && sameScope(r.scope, delta.scope));
+    const existing = next.find((r) => sameRuleIdentity(r, delta));
     if (existing === undefined) {
-        next.push({ rule: delta.rule, tool: delta.tool, match: delta.match, command: delta.command, scope: delta.scope, adds: [delta.add] });
+        next.push({ behavior: delta.behavior, rule: delta.rule, tool: delta.tool, match: delta.match, command: delta.command, scope: delta.scope, adds: [delta.add] });
         return next;
     }
     if (!existing.adds.some((a) => sameDot(a.dot, delta.add.dot)))
@@ -41,7 +44,7 @@ export function foldDelta(rules, delta) {
 export function addDotsOf(rules) {
     return rules.flatMap((r) => r.adds.map((a) => a.dot));
 }
-const ADD_ONLY_KEYS = ["add", "redemption", "rule", "command", "match", "tool"];
+const ADD_ONLY_KEYS = ["add", "redemption", "rule", "command", "match", "tool", "behavior"];
 export function assertDeleteDeltaCarriesNoAdd(delta) {
     const smuggled = ADD_ONLY_KEYS.filter((k) => Object.hasOwn(delta, k));
     if (smuggled.length > 0) {
@@ -87,8 +90,8 @@ function scopeKey(scope) {
 function dotKey(dot) {
     return JSON.stringify([dot.actor, dot.counter]);
 }
-function ruleIdentityKey(rule, scope) {
-    return JSON.stringify([rule, scopeKey(scope)]);
+function ruleIdentityKey(behavior, rule, scope) {
+    return JSON.stringify([behavior, rule, scopeKey(scope)]);
 }
 function compareDots(a, b) {
     return a.actor < b.actor ? -1 : a.actor > b.actor ? 1 : a.counter - b.counter;
@@ -124,7 +127,9 @@ export function joinFrontiers(a, b) {
     return out;
 }
 export function normalizePersistedRule(r) {
-    const parsed = parseAllowRuleText(r.rule);
+    if (!isRuleBehavior(r.behavior))
+        return { reject: "invalid_rule_text" };
+    const parsed = parseRuleText(r.rule, r.behavior);
     if ("reject" in parsed)
         return { reject: "invalid_rule_text" };
     const p = parsed.rule;
@@ -142,13 +147,13 @@ export function screenRuleSyncState(state) {
             continue;
         if (r.scope?.kind === "session") {
             for (const a of r.adds)
-                rejected.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "session_scope_not_durable" });
+                rejected.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "session_scope_not_durable" });
             continue;
         }
         const n = normalizePersistedRule(r);
         if ("reject" in n) {
             for (const a of r.adds)
-                rejected.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: n.reject });
+                rejected.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: n.reject });
             continue;
         }
         rules.push(r);
@@ -156,7 +161,11 @@ export function screenRuleSyncState(state) {
     const tombstones = [];
     for (const t of state.tombstones) {
         if (t?.scope?.kind === "session") {
-            rejected.push({ rule: t.rule, scope: t.scope, dot: t.deletedBy, reason: "session_scope_not_durable" });
+            rejected.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: t.deletedBy, reason: "session_scope_not_durable" });
+            continue;
+        }
+        if (!isRuleBehavior(t.behavior)) {
+            rejected.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: t.deletedBy, reason: "invalid_rule_text" });
             continue;
         }
         tombstones.push(t);
@@ -168,7 +177,7 @@ export function joinRuleStates(a, b) {
     const sb = screenRuleSyncState(b).state;
     const ruleGroups = new Map();
     for (const r of [...sa.rules, ...sb.rules]) {
-        const key = ruleIdentityKey(r.rule, r.scope);
+        const key = ruleIdentityKey(r.behavior, r.rule, r.scope);
         const existing = ruleGroups.get(key);
         if (existing === undefined) {
             ruleGroups.set(key, { ...r, adds: [...r.adds] });
@@ -184,12 +193,12 @@ export function joinRuleStates(a, b) {
     }
     const rules = [...ruleGroups.values()]
         .map((r) => ({ ...r, adds: [...r.adds].sort((x, y) => compareDots(x.dot, y.dot)) }))
-        .sort((x, y) => (x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : scopeKey(x.scope) < scopeKey(y.scope) ? -1 : scopeKey(x.scope) > scopeKey(y.scope) ? 1 : 0));
+        .sort((x, y) => compareIdentity(x, y));
     const tombGroups = new Map();
     for (const t of [...sa.tombstones, ...sb.tombstones]) {
         if (!Array.isArray(t.removedDots) || t.removedDots.length === 0)
             continue;
-        const key = JSON.stringify([t.rule, scopeKey(t.scope), dotKey(t.deletedBy)]);
+        const key = JSON.stringify([t.behavior, t.rule, scopeKey(t.scope), dotKey(t.deletedBy)]);
         const existing = tombGroups.get(key);
         if (existing === undefined) {
             tombGroups.set(key, { ...t, removedDots: [...t.removedDots] });
@@ -201,9 +210,18 @@ export function joinRuleStates(a, b) {
     }
     const tombstones = [...tombGroups.values()]
         .map((t) => ({ ...t, removedDots: [...t.removedDots].sort(compareDots) }))
-        .sort((x, y) => x.rule < y.rule ? -1 : x.rule > y.rule ? 1 : scopeKey(x.scope) < scopeKey(y.scope) ? -1 : scopeKey(x.scope) > scopeKey(y.scope) ? 1 : compareDots(x.deletedBy, y.deletedBy));
+        .sort((x, y) => compareIdentity(x, y) || compareDots(x.deletedBy, y.deletedBy));
     return { rules, tombstones };
 }
+function compareIdentity(x, y) {
+    if (x.rule !== y.rule)
+        return x.rule < y.rule ? -1 : 1;
+    const sx = scopeKey(x.scope);
+    const sy = scopeKey(y.scope);
+    if (sx !== sy)
+        return sx < sy ? -1 : 1;
+    return x.behavior === y.behavior ? 0 : x.behavior < y.behavior ? -1 : 1;
+}
 export function collectBelowFrontier(state, frontier) {
     const collectable = state.tombstones.filter((t) => dotAtOrBelowFrontier(t.deletedBy, frontier) && t.removedDots.every((d) => dotAtOrBelowFrontier(d, frontier)));
     if (collectable.length === 0)
@@ -211,7 +229,7 @@ export function collectBelowFrontier(state, frontier) {
     const keep = state.tombstones.filter((t) => !collectable.includes(t));
     const rules = state.rules
         .map((r) => {
-        const covered = collectable.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        const covered = collectable.filter((t) => sameRuleIdentity(t, r)).flatMap((t) => t.removedDots);
         return covered.length === 0 ? r : { ...r, adds: r.adds.filter((a) => !covered.some((d) => sameDot(d, a.dot))) };
     })
         .filter((r) => r.adds.length > 0);
@@ -230,7 +248,10 @@ export function applySyncJoin(cur, delta, nowMs) {
         if (!isValidDurableScope(t.scope) || !isValidDot(t.deletedBy) || !t.removedDots.every(isValidDot)) {
             throw new Error("an inbound tombstone carries a malformed scope or dot — refusing the whole sync-join (a tombstone that cannot identity-match what it deletes would land its covered adds live)");
         }
-        const canonicalTomb = parseAllowRuleText(t.rule);
+        if (!isRuleBehavior(t.behavior)) {
+            throw new Error("an inbound tombstone carries a behavior word outside deny/ask/allow — refusing the whole sync-join (a tombstone that cannot identity-match what it deletes would land its covered adds live)");
+        }
+        const canonicalTomb = parseRuleText(t.rule, t.behavior);
         if ("reject" in canonicalTomb || canonicalTomb.rule.rule !== t.rule) {
             throw new Error(`an inbound tombstone names a non-canonical or invalid rule text ("${escapeForDisclosure(t.rule)}") — refusing the whole sync-join (the client's partitioning must withhold the round's adds alongside a malformed tombstone)`);
         }
@@ -243,12 +264,12 @@ export function applySyncJoin(cur, delta, nowMs) {
     const dotIdentity = new Map();
     for (const r of cur.rules)
         for (const a of r.adds)
-            dotIdentity.set(dotKey(a.dot), ruleIdentityKey(r.rule, r.scope));
+            dotIdentity.set(dotKey(a.dot), ruleIdentityKey(r.behavior, r.rule, r.scope));
     for (const q of cur.quarantined)
-        dotIdentity.set(dotKey(q.add.dot), ruleIdentityKey(q.rule, q.scope));
+        dotIdentity.set(dotKey(q.add.dot), ruleIdentityKey(q.behavior, q.rule, q.scope));
     const inboundClaims = new Map();
     for (const r of screened.state.rules) {
-        const identity = ruleIdentityKey(r.rule, r.scope);
+        const identity = ruleIdentityKey(r.behavior, r.rule, r.scope);
         for (const a of r.adds) {
             const claims = inboundClaims.get(dotKey(a.dot)) ?? new Set();
             claims.add(identity);
@@ -259,7 +280,7 @@ export function applySyncJoin(cur, delta, nowMs) {
         const forged = forgedDot(t.deletedBy) ? t.deletedBy : t.removedDots.find(forgedDot);
         if (forged === undefined)
             return true;
-        droppedInbound.push({ rule: t.rule, scope: t.scope, dot: forged, reason: "own_actor_forged" });
+        droppedInbound.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: forged, reason: "own_actor_forged" });
         return false;
     });
     const tombstoneRejected = inboundTombstones.length !== screened.state.tombstones.length;
@@ -272,22 +293,22 @@ export function applySyncJoin(cur, delta, nowMs) {
         }
         if (!isValidDurableScope(r.scope)) {
             for (const a of r.adds)
-                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
+                droppedInbound.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
             continue;
         }
-        const identity = ruleIdentityKey(r.rule, r.scope);
+        const identity = ruleIdentityKey(r.behavior, r.rule, r.scope);
         const kept = r.adds.filter((a) => {
             if (!isValidDot(a.dot)) {
-                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
+                droppedInbound.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "metadata_mismatch" });
                 return false;
             }
             if (forgedDot(a.dot)) {
-                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "own_actor_forged" });
+                droppedInbound.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "own_actor_forged" });
                 return false;
             }
             const known = dotIdentity.get(dotKey(a.dot));
             if ((known !== undefined && known !== identity) || (inboundClaims.get(dotKey(a.dot))?.size ?? 0) > 1) {
-                droppedInbound.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "dot_identity_conflict" });
+                droppedInbound.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "dot_identity_conflict" });
                 return false;
             }
             return true;
@@ -298,18 +319,18 @@ export function applySyncJoin(cur, delta, nowMs) {
     const inbound = { rules: inboundRules, tombstones: inboundTombstones };
     const localScreen = screenRuleSyncState({ rules: cur.rules, tombstones: cur.tombstones });
     const quarantined = [...cur.quarantined];
-    const quarantineKey = (rule, scope, dot) => JSON.stringify([rule, scopeKey(scope), dotKey(dot)]);
-    const pushQuarantine = (rule, scope, add, reason) => {
-        if (quarantined.some((q) => q.rule === rule && sameScope(q.scope, scope) && sameDot(q.add.dot, add.dot)))
+    const quarantineKey = (behavior, rule, scope, dot) => JSON.stringify([behavior, rule, scopeKey(scope), dotKey(dot)]);
+    const pushQuarantine = (behavior, rule, scope, add, reason) => {
+        if (quarantined.some((q) => sameRuleIdentity(q, { behavior, rule, scope }) && sameDot(q.add.dot, add.dot)))
             return;
-        quarantined.push({ rule, scope, add, reason, atMs: nowMs });
-        quarantinedNow.push({ rule, scope, dot: add.dot, reason });
+        quarantined.push({ behavior, rule, scope, add, reason, atMs: nowMs });
+        quarantinedNow.push({ behavior, rule, scope, dot: add.dot, reason });
     };
     for (const rej of localScreen.rejected) {
-        const row = cur.rules.find((r) => r.rule === rej.rule && sameScope(r.scope, rej.scope));
+        const row = cur.rules.find((r) => sameRuleIdentity(r, rej));
         const add = row?.adds.find((a) => sameDot(a.dot, rej.dot));
         if (add !== undefined && (rej.reason === "invalid_rule_text" || rej.reason === "metadata_mismatch")) {
-            pushQuarantine(rej.rule, rej.scope, add, rej.reason);
+            pushQuarantine(rej.behavior, rej.rule, rej.scope, add, rej.reason);
         }
     }
     let joined = joinRuleStates(localScreen.state, inbound);
@@ -323,7 +344,7 @@ export function applySyncJoin(cur, delta, nowMs) {
         for (const r of live) {
             for (const a of r.adds) {
                 if (dotAtOrBelowFrontier(a.dot, delta.gcFrontier) && !inboundDots.has(dotKey(a.dot))) {
-                    pushQuarantine(r.rule, r.scope, a, "below_gc_frontier");
+                    pushQuarantine(r.behavior, r.rule, r.scope, a, "below_gc_frontier");
                 }
             }
         }
@@ -338,16 +359,16 @@ export function applySyncJoin(cur, delta, nowMs) {
             if (joined.tombstones.some((t) => sameDot(t.deletedBy, dot))) {
                 throw new Error("a quarantine instruction may not touch a tombstone — it moves adds only");
             }
-            const row = joined.rules.find((r) => r.rule === q.rule && sameScope(r.scope, q.scope));
+            const row = joined.rules.find((r) => sameRuleIdentity(r, q));
             const add = row?.adds.find((a) => sameDot(a.dot, dot));
             if (add === undefined)
                 continue;
-            pushQuarantine(q.rule, q.scope, add, q.reason);
+            pushQuarantine(q.behavior, q.rule, q.scope, add, q.reason);
         }
     }
-    const quarantinedRows = new Set(quarantined.map((q) => quarantineKey(q.rule, q.scope, q.add.dot)));
+    const quarantinedRows = new Set(quarantined.map((q) => quarantineKey(q.behavior, q.rule, q.scope, q.add.dot)));
     const rules = joined.rules
-        .map((r) => ({ ...r, adds: r.adds.filter((a) => !quarantinedRows.has(quarantineKey(r.rule, r.scope, a.dot))) }))
+        .map((r) => ({ ...r, adds: r.adds.filter((a) => !quarantinedRows.has(quarantineKey(r.behavior, r.rule, r.scope, a.dot))) }))
         .filter((r) => r.adds.length > 0);
     return {
         next: {
@@ -373,9 +394,14 @@ export async function ruleStoreChecksum(payload) {
 }
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
+    const behavior = opts.behavior;
     const rule = opts.rule;
     const scope = structuredClone(opts.scope);
     const target = opts.principal;
+    if (!isRuleBehavior(behavior)) {
+        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` };
+    }
+    const identity = { behavior, rule, scope };
     const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
     const provider = opts.provider;
     if (scope?.kind === "session") {
@@ -401,11 +427,11 @@ export async function removePersistedRule(opts) {
     }
     if (snapshot.unreadable !== undefined)
         return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}` };
-    const live = snapshot.rules.filter((r) => r.rule === rule && sameScope(r.scope, scope));
+    const live = snapshot.rules.filter((r) => sameRuleIdentity(r, identity));
     const removedDots = live.flatMap((r) => r.adds.map((a) => a.dot));
     if (removedDots.length === 0)
         return { status: "no-op", rev: snapshot.rev };
-    const tombstone = { rule, scope, removedDots, deletedBy: await writer.nextDot() };
+    const tombstone = { behavior, rule, scope, removedDots, deletedBy: await writer.nextDot() };
     let expectedRev = snapshot.rev;
     let lastError = "";
     for (let attempt = 0; attempt < REMOVE_MAX_ATTEMPTS; attempt++) {
@@ -420,7 +446,7 @@ export async function removePersistedRule(opts) {
                     const after = await store.effective();
                     if (after.unreadable !== undefined)
                         throw new Error(after.unreadable);
-                    stillLive = after.rules.some((r) => r.rule === rule && sameScope(r.scope, scope) && isRuleLive(r));
+                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r));
                 }
                 catch {
                     stillLive = false;
@@ -439,7 +465,7 @@ export async function removePersistedRule(opts) {
         const after = await writer.readRaw();
         const landed = after.tombstones.some((t) => t.deletedBy.actor === tombstone.deletedBy.actor && t.deletedBy.counter === tombstone.deletedBy.counter);
         return landed
-            ? { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => r.rule === rule && sameScope(r.scope, scope) && isRuleLive(r)) }
+            ? { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) }
             : { status: "failed", error: `${reason} (read-back confirms no tombstone was written)` };
     }
     catch (err) {

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

@@ -25,7 +25,7 @@
  * privilege-separation ticket adds device-bound signatures. Deployments should connect knowing which
  * level they are buying.
  */
-import type { PersistedAllowRule, RuleDot, RuleRejectCode, RuleScope, RuleTombstone } from "./permission-rule-model.js";
+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 TracerHook } from "./trace.js";
@@ -50,7 +50,9 @@ export interface RuleSyncResponseBody {
     principal: string;
     merged: RuleSyncState;
     gcFrontier?: RuleSyncFrontier;
+    /** Server-side refusals of rows we sent. `behavior` is part of the row identity the twin names. */
     dropped?: Array<{
+        behavior: import("./permission-rule-model.js").RuleBehavior;
         rule: string;
         scope: RuleScope;
         dot: RuleDot;
@@ -70,8 +72,9 @@ export interface PermissionRuleSyncResult {
         newAdds: number;
         newTombstones: number;
     };
-    /** (rule, scope) pairs that went removed → live in this round — add-wins made visible (§4.6). */
+    /** (behavior, rule, scope) identities that went removed → live in this round — add-wins made visible (§4.6). */
     resurrected: Array<{
+        behavior: import("./permission-rule-model.js").RuleBehavior;
         rule: string;
         scope: RuleScope;
         byDot: RuleDot;
@@ -116,11 +119,12 @@ export declare function syncPermissionRules(opts: {
 interface ParsedRuleSyncResponse {
     principal: string;
     merged: {
-        rules: PersistedAllowRule[];
+        rules: PersistedRule[];
         tombstones: Array<RuleTombstone | undefined>;
     };
     gcFrontier?: RuleSyncFrontier;
     dropped: Array<{
+        behavior: RuleBehavior;
         rule: string;
         scope: RuleScope;
         dot: RuleDot;
@@ -130,6 +134,7 @@ interface ParsedRuleSyncResponse {
      *  outcome, kept OUT of `merged.tombstones` so it does not read as malformed. See {@link
      *  parseRuleSyncResponse} for why this one does not withhold the round's adds (backlog #176). */
     textRefusedTombstones: Array<{
+        behavior: RuleBehavior;
         rule: string;
         scope: RuleScope;
         dot: RuleDot;
@@ -140,6 +145,7 @@ interface ParsedRuleSyncResponse {
      *  DAMAGED one as generic-malformed would withhold every valid inbound add on every round — one
      *  peer row poisoning sync forever, the exact shape the per-row drop arm exists to avoid. */
     sessionScopeTombstones: Array<{
+        behavior: RuleBehavior;
         rule: string;
         scope: RuleScope;
         dot: RuleDot;

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

@@ -1,5 +1,5 @@
-import { escapeForDisclosure, parseAllowRuleText } from "./permission-rule-model.js";
-import { applyTombstones, errText, joinFrontiers, joinRuleStates, normalizePersistedRule, ruleSyncVector, sameScope, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
+import { escapeForDisclosure, isRuleBehavior, parseRuleText } from "./permission-rule-model.js";
+import { applyTombstones, errText, joinFrontiers, joinRuleStates, normalizePersistedRule, ruleSyncVector, sameRuleIdentity, screenRuleSyncState, writerOf, } from "./permission-rule-store.js";
 import { emitTrace } from "./trace.js";
 export const PERMISSION_RULE_SYNC_PATH = "/v1/permission-rules/sync";
 export const LOCAL_OWNER_UNSYNCABLE_CODE = "permission_rules.local_owner_unsyncable";
@@ -79,7 +79,7 @@ export async function syncPermissionRules(opts) {
         }
         const forged = forgedDot(t.deletedBy) ? t.deletedBy : t.removedDots.find(forgedDot);
         if (forged !== undefined) {
-            dropped.push({ rule: t.rule, scope: t.scope, dot: forged, reason: "own_actor_forged" });
+            dropped.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: forged, reason: "own_actor_forged" });
             tombstoneWithholding = true;
             continue;
         }
@@ -89,10 +89,10 @@ export async function syncPermissionRules(opts) {
         warnings.push("the response carried at least one malformed tombstone — every inbound add is withheld this round (legal tombstones land; the adds re-arrive once the peer repairs the tombstone: full-state exchange has no missed-forever window)");
     }
     for (const t of response.textRefusedTombstones) {
-        dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "invalid_rule_text" });
+        dropped.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: t.dot, reason: "invalid_rule_text" });
     }
     for (const t of response.sessionScopeTombstones) {
-        dropped.push({ rule: t.rule, scope: t.scope, dot: t.dot, reason: "session_scope_not_durable" });
+        dropped.push({ behavior: t.behavior, rule: t.rule, scope: t.scope, dot: t.dot, reason: "session_scope_not_durable" });
     }
     if (response.textRefusedTombstones.length > 0) {
         const named = response.textRefusedTombstones
@@ -109,12 +109,12 @@ export async function syncPermissionRules(opts) {
             const n = normalizePersistedRule(r);
             if ("reject" in n) {
                 for (const a of r.adds)
-                    dropped.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: n.reject });
+                    dropped.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: n.reject });
                 continue;
             }
             const kept = r.adds.filter((a) => {
                 if (a.dot.actor === raw.actor && a.dot.counter > raw.counter) {
-                    dropped.push({ rule: r.rule, scope: r.scope, dot: a.dot, reason: "own_actor_forged" });
+                    dropped.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, dot: a.dot, reason: "own_actor_forged" });
                     return false;
                 }
                 return true;
@@ -128,7 +128,7 @@ export async function syncPermissionRules(opts) {
     const localScreen = screenRuleSyncState({ rules: raw.rules, tombstones: raw.tombstones });
     for (const rej of localScreen.rejected) {
         if (rej.reason === "invalid_rule_text" || rej.reason === "metadata_mismatch") {
-            quarantine.push({ rule: rej.rule, scope: rej.scope, dots: [rej.dot], reason: rej.reason });
+            quarantine.push({ behavior: rej.behavior, rule: rej.rule, scope: rej.scope, dots: [rej.dot], reason: rej.reason });
             dropped.push(rej);
         }
     }
@@ -140,8 +140,8 @@ export async function syncPermissionRules(opts) {
         }
         if (localDots.has(JSON.stringify([d.dot.actor, d.dot.counter]))) {
             const reason = d.reason === "below_gc_frontier" ? "below_gc_frontier" : "server_rejected";
-            quarantine.push({ rule: d.rule, scope: d.scope, dots: [d.dot], reason });
-            dropped.push({ rule: d.rule, scope: d.scope, dot: d.dot, reason });
+            quarantine.push({ behavior: d.behavior, rule: d.rule, scope: d.scope, dots: [d.dot], reason });
+            dropped.push({ behavior: d.behavior, rule: d.rule, scope: d.scope, dot: d.dot, reason });
         }
         else {
             warnings.push(`the server dropped an inbound-side record (${escapeForDisclosure(d.rule)}, dot ${escapeForDisclosure(d.dot.actor)}#${d.dot.counter}): ${escapeForDisclosure(d.reason)}`);
@@ -193,22 +193,22 @@ export async function syncPermissionRules(opts) {
         const postLive = applyTombstones(landedRaw.rules, landedRaw.tombstones);
         const resurrected = [];
         for (const r of postLive) {
-            const pre = preLive.find((p) => p.rule === r.rule && sameScope(p.scope, r.scope));
+            const pre = preLive.find((p) => sameRuleIdentity(p, r));
             if (pre !== undefined)
                 continue;
-            const hadAdds = current.rules.some((p) => p.rule === r.rule && sameScope(p.scope, r.scope));
-            const covered = current.tombstones.some((t) => t.rule === r.rule && sameScope(t.scope, r.scope));
+            const hadAdds = current.rules.some((p) => sameRuleIdentity(p, r));
+            const covered = current.tombstones.some((t) => sameRuleIdentity(t, r));
             if (hadAdds && covered) {
-                const preRuleDots = new Set(current.rules.filter((p) => p.rule === r.rule && sameScope(p.scope, r.scope)).flatMap((p) => p.adds.map((a) => JSON.stringify([a.dot.actor, a.dot.counter]))));
+                const preRuleDots = new Set(current.rules.filter((p) => sameRuleIdentity(p, r)).flatMap((p) => p.adds.map((a) => JSON.stringify([a.dot.actor, a.dot.counter]))));
                 const by = r.adds.find((a) => !preRuleDots.has(JSON.stringify([a.dot.actor, a.dot.counter]))) ?? r.adds[0];
                 if (by !== undefined)
-                    resurrected.push({ rule: r.rule, scope: r.scope, byDot: by.dot });
+                    resurrected.push({ behavior: r.behavior, rule: r.rule, scope: r.scope, byDot: by.dot });
             }
         }
         const dotKeyOf = (d) => JSON.stringify([d.actor, d.counter]);
         const preDots = new Set(current.rules.flatMap((r) => r.adds.map((a) => dotKeyOf(a.dot))));
         const newAdds = landedRaw.rules.flatMap((r) => r.adds).filter((a) => !preDots.has(dotKeyOf(a.dot))).length;
-        const tombKeyOf = (t) => JSON.stringify([t.rule, t.scope.kind, t.scope.kind === "project" ? t.scope.root : t.scope.kind === "session" ? t.scope.sessionId : null, dotKeyOf(t.deletedBy)]);
+        const tombKeyOf = (t) => JSON.stringify([t.behavior, t.rule, t.scope.kind, t.scope.kind === "project" ? t.scope.root : t.scope.kind === "session" ? t.scope.sessionId : null, dotKeyOf(t.deletedBy)]);
         const preTombs = new Set(current.tombstones.map(tombKeyOf));
         const newTombstones = landedRaw.tombstones.filter((t) => !preTombs.has(tombKeyOf(t))).length;
         const landedReport = res.sync;
@@ -324,7 +324,8 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         const eTool = e?.tool;
         const eMatch = e?.match;
         const eAdds = e?.adds;
-        if (typeof eRule !== "string" || scope === undefined || !Array.isArray(eAdds) || typeof eCommand !== "string" || typeof eTool !== "string" || typeof eMatch !== "string") {
+        const eBehavior = isRuleBehavior(e?.behavior) ? e.behavior : undefined;
+        if (typeof eRule !== "string" || scope === undefined || !Array.isArray(eAdds) || typeof eCommand !== "string" || typeof eTool !== "string" || typeof eMatch !== "string" || eBehavior === undefined) {
             warnings.push("the response carried an unshapeable rule entry — skipped (it never reaches the local store)");
             continue;
         }
@@ -343,6 +344,7 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         if (adds.length === 0)
             continue;
         rules.push({
+            behavior: eBehavior,
             rule: eRule,
             tool: eTool,
             match: eMatch,
@@ -359,6 +361,7 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
         const pickedScope = pickScopeCaptured(t?.scope);
         const scope = pickedScope.scope;
         const ruleText = t?.rule;
+        const behavior = isRuleBehavior(t?.behavior) ? t.behavior : undefined;
         const deletedBy = pickDot(t?.deletedBy);
         const removedRaw = t?.removedDots;
         const removedDots = [];
@@ -373,28 +376,28 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
             }
         }
         if (pickedScope.kind === "session") {
-            if (typeof ruleText === "string" && deletedBy !== undefined && scope !== undefined) {
-                sessionScopeTombstones.push({ rule: ruleText, scope, dot: deletedBy });
+            if (typeof ruleText === "string" && deletedBy !== undefined && scope !== undefined && behavior !== undefined) {
+                sessionScopeTombstones.push({ behavior, rule: ruleText, scope, dot: deletedBy });
             }
             else {
                 warnings.push("the response carried a session-scope tombstone whose identity could not be read — dropped per-row (a session row never lands here, and nothing is withheld for it)");
             }
             continue;
         }
-        if (typeof ruleText !== "string" || scope === undefined || deletedBy === undefined || removedDots.length === 0) {
+        if (typeof ruleText !== "string" || scope === undefined || deletedBy === undefined || removedDots.length === 0 || behavior === undefined) {
             tombstones.push(undefined);
             continue;
         }
-        const canonicalTomb = parseAllowRuleText(ruleText);
+        const canonicalTomb = parseRuleText(ruleText, behavior);
         if ("reject" in canonicalTomb) {
-            textRefusedTombstones.push({ rule: ruleText, scope, dot: deletedBy, code: canonicalTomb.reject.code });
+            textRefusedTombstones.push({ behavior, rule: ruleText, scope, dot: deletedBy, code: canonicalTomb.reject.code });
             continue;
         }
         if (canonicalTomb.rule.rule !== ruleText) {
             tombstones.push(undefined);
             continue;
         }
-        tombstones.push({ rule: ruleText, scope, removedDots, deletedBy });
+        tombstones.push({ behavior, rule: ruleText, scope, removedDots, deletedBy });
     }
     const dropped = [];
     const rawDropped = r.dropped;
@@ -409,11 +412,12 @@ export function parseRuleSyncResponse(raw, expectedPrincipal) {
                 const dRule = d?.rule;
                 const dDot = pickDot(d?.dot);
                 const dReason = d?.reason;
-                if (typeof dRule !== "string" || scope === undefined || dDot === undefined || typeof dReason !== "string") {
+                const dBehavior = isRuleBehavior(d?.behavior) ? d.behavior : undefined;
+                if (typeof dRule !== "string" || scope === undefined || dDot === undefined || typeof dReason !== "string" || dBehavior === undefined) {
                     warnings.push("the response carried an unshapeable dropped entry — ignored (the server's own drop discipline is its contract obligation)");
                     continue;
                 }
-                dropped.push({ rule: dRule, scope, dot: dDot, reason: dReason });
+                dropped.push({ behavior: dBehavior, rule: dRule, scope, dot: dDot, reason: dReason });
             }
         }
     }

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

@@ -0,0 +1,30 @@
+/**
+ * The `Tool(content)` rule SYNTAX — the one reader every rule face shares, as a LEAF module.
+ *
+ * Two modules read this grammar and, until this file existed, one imported it from the other: the rule
+ * DSL compiler (`permission-rules.ts`) declared the parser and the persisted-rule model
+ * (`permission-rule-model.ts`) imported it. The model's command/path grammars are now consumed by the
+ * compiler too (a content-form `deny`/`ask` rule compiles through the model's own validator and
+ * matcher), which would have closed a value-import cycle between the two. The syntax layer has no
+ * dependency of its own, so it lives here and both read DOWN.
+ *
+ * Upstream parity: `Lh` (the split), `Dju`/`Pju` (the escape-aware paren search), `Hju` (the three
+ * unescapes) — INCLUDING the lenient downgrades (malformed parens / trailing garbage ⇒ the WHOLE string
+ * becomes the bare tool name). The strict complement that refuses the downgrades is the compiler's
+ * validator, not this reader.
+ */
+/** Parse result — the tool name and, for a `Tool(content)` spelling, its unescaped content. */
+export interface ParsedPermissionRule {
+    toolName: string;
+    ruleContent?: string;
+}
+/** First index of `ch` preceded by an EVEN number of backslashes. */
+export declare function indexOfUnescaped(s: string, ch: string): number;
+/** Last index of `ch` preceded by an EVEN number of backslashes. */
+export declare function lastIndexOfUnescaped(s: string, ch: string): number;
+/**
+ * Parse one rule string, including the lenient downgrades (malformed parens / trailing garbage ⇒ the
+ * WHOLE string becomes the bare tool name). Use the compiler's `validatePermissionRules` (or the policy
+ * factory) to refuse the downgrades.
+ */
+export declare function parsePermissionRule(rule: string): ParsedPermissionRule;

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

@@ -0,0 +1,44 @@
+export function indexOfUnescaped(s, ch) {
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== ch)
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
+            backslashes++;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+export function lastIndexOfUnescaped(s, ch) {
+    for (let i = s.length - 1; i >= 0; i--) {
+        if (s[i] !== ch)
+            continue;
+        let backslashes = 0;
+        for (let j = i - 1; j >= 0 && s[j] === "\\"; j--)
+            backslashes++;
+        if (backslashes % 2 === 0)
+            return i;
+    }
+    return -1;
+}
+function unescapeRuleContent(s) {
+    return s.replaceAll("\\(", "(").replaceAll("\\)", ")").replaceAll("\\\\", "\\");
+}
+export function parsePermissionRule(rule) {
+    const open = indexOfUnescaped(rule, "(");
+    if (open === -1)
+        return { toolName: rule.trim() };
+    const close = lastIndexOfUnescaped(rule, ")");
+    if (close === -1 || close <= open)
+        return { toolName: rule.trim() };
+    if (close !== rule.length - 1)
+        return { toolName: rule.trim() };
+    const name = rule.substring(0, open);
+    const content = rule.substring(open + 1, close);
+    if (!name)
+        return { toolName: rule.trim() };
+    if (content === "" || content === "*")
+        return { toolName: name.trim() };
+    return { toolName: name.trim(), ruleContent: unescapeRuleContent(content) };
+}