@sema-agent/client-core 0.97.0 → 0.98.0

package/dist/hitl/sessionPolicyWire.d.ts

@@ -1,8 +1,9 @@
 import type { SessionPermissionRules, StoredSessionRules } from '@sema-agent/sdk';
 import type { SessionPolicyReading } from '../sessionPolicyCapability.js';
 import type { ToolRosterView } from '../toolRoster.js';
-import { CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
+import { CORE_ALLOW_ENTRY_INERT_REASONS, CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
 export type LegacyToolNameVerdict = Exclude<(typeof CORE_RULE_TOOL_NAME_VERDICTS)[number], 'current'>;
+export type SessionRuleInertReason = (typeof CORE_ALLOW_ENTRY_INERT_REASONS)[number];
 export interface SessionPolicyFacade {
     getPolicy(sessionId: string, opts?: {
         signal?: AbortSignal;
@@ -41,10 +42,16 @@ export type SessionPolicyFailure = {
     kind: 'request-rejected';
     message: string;
 } | {
-    kind: 'legacy-tool-name';
+    kind: 'earlier-grammar';
+    message: string;
+    field?: 'toolAllow';
+    entry?: string;
+} | {
+    kind: 'inert-entry';
     message: string;
     field?: SessionPolicyRemovedEntry['field'];
-    name?: string;
+    entry?: string;
+    reason?: SessionRuleInertReason;
     verdict?: LegacyToolNameVerdict;
     currentName?: string;
 } | {
@@ -58,11 +65,12 @@ export type SessionPolicyFailure = {
     message: string;
 };
 export declare function classifySessionPolicyFailure(e: unknown): SessionPolicyFailure;
-export type SessionPolicyMalformedWhy = 'envelope' | 'rev' | 'rule_field';
+export type SessionPolicyMalformedWhy = 'envelope' | 'rev' | 'rule_field' | 'grammar_stamp';
 export type SessionPolicyReadOutcome = {
     kind: 'present';
     rev: number;
     rules: SessionPermissionRules;
+    grammar?: number;
 } | {
     kind: 'malformed';
     why: SessionPolicyMalformedWhy;
@@ -82,6 +90,11 @@ export interface SessionPolicyTightenRequest {
 }
 export type SessionPolicyTightenUnknownWhy = 'face_unavailable' | 'session_not_found' | 'session_ownerless' | 'unauthorized' | 'request_rejected' | 'store_corrupt' | 'read_unreadable' | 'read_failed' | 'write_refused' | 'write_indeterminate' | 'write_receipt_unreadable' | 'write_receipt_mismatch';
 export declare const SESSION_POLICY_TIGHTEN_UNKNOWN_WHY: readonly SessionPolicyTightenUnknownWhy[];
+export type SessionPolicyEarlierGrammarRefusal = {
+    kind: 'refused';
+    why: 'earlier_grammar_rows';
+    entries: readonly SessionPolicyRemovedEntry[];
+};
 export type SessionPolicyTightenOutcome = {
     kind: 'written';
     rev: number;
@@ -94,19 +107,23 @@ export type SessionPolicyTightenOutcome = {
 } | {
     kind: 'capability_absent';
     why: 'not_reported' | 'absent';
-} | {
-    kind: 'legacy_tool_name';
-    message: string;
-    field?: SessionPolicyRemovedEntry['field'];
-    name?: string;
-    verdict?: LegacyToolNameVerdict;
-    currentName?: string;
+} | SessionPolicyEarlierGrammarRefusal | ({
+    kind: 'inert_entry';
+} & SessionPolicyInertEntryRefusal & {
     alreadyInRecord?: boolean;
-} | {
+}) | {
     kind: 'unknown';
     why: SessionPolicyTightenUnknownWhy;
     message?: string;
 };
+export interface SessionPolicyInertEntryRefusal {
+    message: string;
+    field?: SessionPolicyRemovedEntry['field'];
+    entry?: string;
+    reason?: SessionRuleInertReason;
+    verdict?: LegacyToolNameVerdict;
+    currentName?: string;
+}
 export declare function tightenSessionPolicy(facade: SessionPolicyFacade, req: SessionPolicyTightenRequest, opts?: {
     signal?: AbortSignal;
 }): Promise<SessionPolicyTightenOutcome>;
@@ -153,14 +170,9 @@ export type SessionPolicyRemovalOutcome = {
     kind: 'write_unconfirmed';
     why: Extract<SessionPolicyTightenUnknownWhy, 'write_indeterminate' | 'write_receipt_unreadable' | 'write_receipt_mismatch'>;
     message?: string;
-} | {
-    kind: 'legacy_tool_name';
-    message: string;
-    field?: SessionPolicyRemovedEntry['field'];
-    name?: string;
-    verdict?: LegacyToolNameVerdict;
-    currentName?: string;
-};
+} | SessionPolicyEarlierGrammarRefusal | ({
+    kind: 'inert_entry';
+} & SessionPolicyInertEntryRefusal);
 export type SessionPolicyRosterRequiredWhy = 'absent' | 'unreadable';
 export declare function removeRefusedSessionRules(facade: SessionPolicyFacade, sessionId: string, roster: ToolRosterView | undefined, opts?: {
     signal?: AbortSignal;

package/dist/hitl/sessionPolicyWire.js

@@ -1,10 +1,16 @@
 import { wireFailureShapeOf } from '../wireFailureShape.js';
 import { hostLog } from '../host.js';
 import { ruleToolNameVerdictOf } from '../protocolSegment.js';
-import { RULES_LEGACY_TOOL_NAME_WRITE_NOTE } from './refusedToolNameProse.js';
-import { RULES_LEGACY_TOOL_NAME, isRulesRefusalCode } from '../engineErrorCodes.js';
+import { RULES_INERT_ENTRY, RULES_INVALID_SHAPE, isRulesRefusalCode } from '../engineErrorCodes.js';
+import { deniedEntryToolName } from '../engineToolDirectory.js';
 import { rosterMountedNames } from '../rosterMountedNames.js';
-import { CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
+import { CORE_ALLOW_ENTRY_INERT_REASONS, CORE_RULE_TOOL_NAME_VERDICTS } from '../generated/engineFactTables.js';
+const EARLIER_GRAMMAR_REASON = 'earlier_grammar';
+const _inertReasonPin = true;
+void _inertReasonPin;
+function isSessionRuleInertReason(v) {
+    return typeof v === 'string' && CORE_ALLOW_ENTRY_INERT_REASONS.includes(v);
+}
 function isLegacyToolNameVerdict(v) {
     return typeof v === 'string' && v !== 'current' && CORE_RULE_TOOL_NAME_VERDICTS.includes(v);
 }
@@ -12,25 +18,43 @@ const RULE_FIELD_PRESENCE = {
     toolAllow: true,
     toolDeny: true,
     allowDirs: true,
-    commandAllow: true,
-    commandDeny: true,
 };
+const RECORD_META_KEYS = Object.freeze(['rev', 'gen', 'grammar']);
+const _metaKeysPin = true;
+void _metaKeysPin;
 export const SESSION_POLICY_RULE_FIELDS = Object.freeze(Object.keys(RULE_FIELD_PRESENCE));
+function foreignRecordKeysOf(record) {
+    return Object.getOwnPropertyNames(record).filter((key) => !SESSION_POLICY_RULE_FIELDS.includes(key) && !RECORD_META_KEYS.includes(key));
+}
+function recordKeyLabel(key) {
+    return /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) ? `"${key}"` : 'unnamed';
+}
 const MAX_RULE_ENTRIES = 10_000;
 export function classifySessionPolicyFailure(e) {
-    const { status, errorCode, message, bodyField, bodyName, bodyVerdict, bodyCurrentName } = wireFailureShapeOf(e);
+    const { status, errorCode, message, bodyField, bodyVerdict, bodyCurrentName, bodyEntry, bodyReason } = wireFailureShapeOf(e);
     if (errorCode === undefined || errorCode === '')
         return { kind: 'no-verdict', message };
-    if (errorCode === RULES_LEGACY_TOOL_NAME) {
+    if (errorCode === RULES_INERT_ENTRY && bodyReason === EARLIER_GRAMMAR_REASON && status !== undefined && status >= 400 && status < 500) {
+        return {
+            kind: 'earlier-grammar',
+            message,
+            ...(bodyField === 'toolAllow' ? { field: bodyField } : {}),
+            ...(bodyEntry !== undefined && bodyEntry !== '' ? { entry: bodyEntry } : {}),
+        };
+    }
+    if (errorCode === RULES_INERT_ENTRY && status !== undefined && status >= 400 && status < 500) {
         return {
-            kind: 'legacy-tool-name',
+            kind: 'inert-entry',
             message,
             ...(bodyField === 'toolDeny' || bodyField === 'toolAllow' ? { field: bodyField } : {}),
-            ...(bodyName !== undefined && bodyName !== '' ? { name: bodyName } : {}),
+            ...(bodyEntry !== undefined && bodyEntry !== '' ? { entry: bodyEntry } : {}),
+            ...(isSessionRuleInertReason(bodyReason) ? { reason: bodyReason } : {}),
             ...(isLegacyToolNameVerdict(bodyVerdict) ? { verdict: bodyVerdict } : {}),
             ...(bodyCurrentName !== undefined && bodyCurrentName !== '' ? { currentName: bodyCurrentName } : {}),
         };
     }
+    if (errorCode === RULES_INVALID_SHAPE && status !== undefined && status >= 400 && status < 500)
+        return { kind: 'request-rejected', message };
     if (isRulesRefusalCode(errorCode) && status !== undefined && status >= 400 && status < 500)
         return { kind: 'error', message };
     if (status === 501 || errorCode === 'capability.session_store_required') {
@@ -95,6 +119,21 @@ function narrowStoredRecord(body) {
     if (typeof rev !== 'number' || !Number.isSafeInteger(rev) || rev < 0) {
         return { ok: false, why: 'rev', detail: 'policy record carries no readable version stamp' };
     }
+    let grammarSlot;
+    try {
+        grammarSlot = Object.getOwnPropertyDescriptor(envelope, 'grammar');
+    }
+    catch {
+        return { ok: false, why: 'grammar_stamp', detail: 'policy record’s rule-grammar stamp could not be read' };
+    }
+    let grammar;
+    if (grammarSlot !== undefined) {
+        const v = Object.hasOwn(grammarSlot, 'value') ? grammarSlot.value : undefined;
+        if (typeof v !== 'number' || !Number.isSafeInteger(v) || v < 0) {
+            return { ok: false, why: 'grammar_stamp', detail: 'policy record carries a rule-grammar stamp that is not a whole number of 0 or more' };
+        }
+        grammar = v;
+    }
     const rules = {};
     for (const field of SESSION_POLICY_RULE_FIELDS) {
         if (!Object.hasOwn(envelope, field))
@@ -107,7 +146,19 @@ function narrowStoredRecord(body) {
             return { ok: false, why: 'rule_field', detail: read.detail };
         rules[field] = read.list;
     }
-    return { ok: true, rev, rules };
+    for (const key of foreignRecordKeysOf(envelope)) {
+        const slot = Object.getOwnPropertyDescriptor(envelope, key);
+        if (slot === undefined)
+            continue;
+        if (!Object.hasOwn(slot, 'value') || Array.isArray(slot.value)) {
+            return {
+                ok: false,
+                why: 'rule_field',
+                detail: `policy record carries a rule field this client does not read (${recordKeyLabel(key)}) — refusing to treat it as readable, since writing the record back would drop that field`,
+            };
+        }
+    }
+    return { ok: true, rev, rules, grammar };
 }
 export async function readSessionPolicy(facade, sessionId, opts) {
     let body;
@@ -126,7 +177,7 @@ export async function readSessionPolicy(facade, sessionId, opts) {
     }
     if (!read.ok)
         return { kind: 'malformed', why: read.why, detail: read.detail };
-    return { kind: 'present', rev: read.rev, rules: read.rules };
+    return { kind: 'present', rev: read.rev, rules: read.rules, ...(read.grammar !== undefined ? { grammar: read.grammar } : {}) };
 }
 export function tightenedSessionRules(prior, add) {
     const p = narrowRulesInput(prior, 'prior');
@@ -159,6 +210,10 @@ function narrowRulesInput(raw, side) {
     if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new TypeError(`tightenedSessionRules: "${side}" must be a rules record object`);
     }
+    const foreign = foreignRecordKeysOf(raw);
+    if (foreign.length > 0) {
+        throw new TypeError(`tightenedSessionRules: "${side}" carries a key that is not a rule field (${recordKeyLabel(foreign[0] ?? '')}) — it would not be written, so the record is refused instead of written without it`);
+    }
     const out = {};
     for (const field of SESSION_POLICY_RULE_FIELDS) {
         if (!Object.hasOwn(raw, field))
@@ -173,10 +228,13 @@ function narrowRulesInput(raw, side) {
     }
     return out;
 }
-function receiptMismatch(sent, receipt, sentRev, receiptRev) {
+function receiptMismatch(sent, receipt, sentRev, receiptRev, sentGrammar, receiptGrammar) {
     if (receiptRev <= sentRev) {
         return `policy write receipt did not advance the version stamp (sent with ${sentRev}, receipt says ${receiptRev})`;
     }
+    if (sentGrammar !== undefined && (receiptGrammar === undefined || receiptGrammar < sentGrammar)) {
+        return `policy write receipt does not carry the rule-grammar stamp that was sent (sent ${sentGrammar}, receipt ${receiptGrammar === undefined ? 'carries none' : `says ${receiptGrammar}`}) — the stored entries may now read differently`;
+    }
     for (const field of SESSION_POLICY_RULE_FIELDS) {
         const s = Object.hasOwn(sent, field) ? sent[field] : undefined;
         if (s === undefined)
@@ -227,32 +285,66 @@ function unknownFrom(failure, leg) {
             return { kind: 'unknown', why: leg === 'read' ? 'read_failed' : 'write_indeterminate', message };
         case 'loosen-forbidden':
         case 'cas-conflict':
-        case 'legacy-tool-name':
+        case 'earlier-grammar':
+        case 'inert-entry':
         case 'error':
             return { kind: 'unknown', why: leg === 'read' ? 'read_failed' : 'write_refused', message };
     }
 }
-function legacyToolNameOutcome(failure, prior, add) {
-    const { field, name, verdict, currentName } = failure;
-    let alreadyInRecord;
-    if (field !== undefined && name !== undefined) {
-        const inPrior = Object.hasOwn(prior, field) ? prior[field] : undefined;
-        const inAdd = Object.hasOwn(add, field) ? add[field] : undefined;
-        if (inPrior !== undefined && inPrior.includes(name))
-            alreadyInRecord = true;
-        else if (inAdd !== undefined && inAdd.includes(name))
-            alreadyInRecord = false;
-    }
+function alreadyInRecordOf(field, entry, prior, add) {
+    if (field === undefined || entry === undefined)
+        return undefined;
+    const inPrior = Object.hasOwn(prior, field) ? prior[field] : undefined;
+    const inAdd = Object.hasOwn(add, field) ? add[field] : undefined;
+    if (inPrior !== undefined && inPrior.includes(entry))
+        return true;
+    if (inAdd !== undefined && inAdd.includes(entry))
+        return false;
+    return undefined;
+}
+function inertEntryRefusalOf(failure) {
+    const { field, entry, reason, verdict, currentName } = failure;
     return {
-        kind: 'legacy_tool_name',
         message: failure.message,
         ...(field !== undefined ? { field } : {}),
-        ...(name !== undefined ? { name } : {}),
+        ...(entry !== undefined ? { entry } : {}),
+        ...(reason !== undefined ? { reason } : {}),
         ...(verdict !== undefined ? { verdict } : {}),
         ...(currentName !== undefined ? { currentName } : {}),
-        ...(alreadyInRecord !== undefined ? { alreadyInRecord } : {}),
     };
 }
+function earlierGrammarEntriesOf(prior, outgoing) {
+    const priorAllow = Object.hasOwn(prior, 'toolAllow') ? prior.toolAllow : undefined;
+    const outAllow = Object.hasOwn(outgoing, 'toolAllow') ? outgoing.toolAllow : undefined;
+    if (priorAllow === undefined || outAllow === undefined)
+        return [];
+    const carried = new Set(outAllow);
+    const seen = new Set();
+    const out = [];
+    for (const rule of priorAllow) {
+        if (seen.has(rule) || !carried.has(rule))
+            continue;
+        const name = deniedEntryToolName(rule);
+        if (name === undefined || name === rule)
+            continue;
+        seen.add(rule);
+        out.push({ field: 'toolAllow', rule });
+    }
+    return out;
+}
+function earlierGrammarOutcome(failure) {
+    return {
+        kind: 'refused',
+        why: 'earlier_grammar_rows',
+        entries: Object.hasOwn(failure, 'field') && Object.hasOwn(failure, 'entry') && failure.field !== undefined && failure.entry !== undefined ? [{ field: failure.field, rule: failure.entry }] : [],
+    };
+}
+function rulesWithStamp(rules, grammar) {
+    return grammar === undefined ? rules : { ...rules, grammar };
+}
+function grammarStampOf(read) {
+    return Object.hasOwn(read, 'grammar') ? read.grammar : undefined;
+}
 async function attemptTighten(facade, req, opts) {
     const read = await readSessionPolicy(facade, req.sessionId, opts);
     if (read.kind === 'failed')
@@ -261,9 +353,15 @@ async function attemptTighten(facade, req, opts) {
         return { done: { kind: 'unknown', why: 'read_unreadable', message: read.detail } };
     }
     const rules = tightenedSessionRules(read.rules, req.add);
+    const stamp = grammarStampOf(read);
+    if (stamp === undefined) {
+        const earlier = earlierGrammarEntriesOf(read.rules, rules);
+        if (earlier.length > 0)
+            return { done: { kind: 'refused', why: 'earlier_grammar_rows', entries: earlier } };
+    }
     let receipt;
     try {
-        receipt = await facade.putPolicy(req.sessionId, { rules, expectedRev: read.rev }, opts);
+        receipt = await facade.putPolicy(req.sessionId, { rules: rulesWithStamp(rules, stamp), expectedRev: read.rev }, opts);
     }
     catch (e) {
         const failure = classifySessionPolicyFailure(e);
@@ -271,8 +369,12 @@ async function attemptTighten(facade, req, opts) {
             return { done: { kind: 'loosen_forbidden', message: failure.message } };
         if (failure.kind === 'cas-conflict')
             return { retryAtRev: read.rev };
-        if (failure.kind === 'legacy-tool-name')
-            return { done: legacyToolNameOutcome(failure, read.rules, req.add) };
+        if (failure.kind === 'earlier-grammar')
+            return { done: earlierGrammarOutcome(failure) };
+        if (failure.kind === 'inert-entry') {
+            const alreadyInRecord = alreadyInRecordOf(failure.field, failure.entry, read.rules, req.add);
+            return { done: { kind: 'inert_entry', ...inertEntryRefusalOf(failure), ...(alreadyInRecord !== undefined ? { alreadyInRecord } : {}) } };
+        }
         return { done: unknownFrom(failure, 'write') };
     }
     let narrowed;
@@ -285,7 +387,7 @@ async function attemptTighten(facade, req, opts) {
     if (!narrowed.ok) {
         return { done: { kind: 'unknown', why: 'write_receipt_unreadable', message: narrowed.detail } };
     }
-    const mismatch = receiptMismatch(rules, narrowed.rules, read.rev, narrowed.rev);
+    const mismatch = receiptMismatch(rules, narrowed.rules, read.rev, narrowed.rev, stamp, narrowed.grammar);
     if (mismatch !== null)
         return { done: { kind: 'unknown', why: 'write_receipt_mismatch', message: mismatch } };
     return { done: { kind: 'written', rev: narrowed.rev } };
@@ -309,6 +411,8 @@ export async function tightenSessionPolicy(facade, req, opts) {
         return second.done;
     return { kind: 'conflict', rev: second.retryAtRev };
 }
+const SESSION_POLICY_INERT_ENTRY_WRITE_NOTE = 'The engine refused to write these session rules, and the stored record was not changed at all: one entry in them reads as matching nothing — written in, it would neither block nor allow any call (the engine’s own error text names the entry and why). Correct that entry or take it out, then write the rules again. If that entry was already in this session’s rule record, it has to be removed from the record before the record can be written again.';
+const SESSION_POLICY_EARLIER_GRAMMAR_NOTE = 'Nothing was written: this session’s rules were saved before the current rule grammar, when an allow entry written in a tool’s own rule form (such as Bash(git:*)) was read as a plain tool name and so allowed nothing. Writing the record back now would read those entries in the current grammar, where they do allow calls — a widening nobody asked for — so the record was left as it is. Rewrite this session’s allow entries in the current form, or take those entries out, before changing its rules here.';
 export function sessionPolicyTightenNotice(outcome) {
     switch (outcome.kind) {
         case 'written':
@@ -321,8 +425,10 @@ export function sessionPolicyTightenNotice(outcome) {
             return outcome.why === 'absent'
                 ? 'This deployment does not keep per-session tool rules, so there is nothing to tighten here.'
                 : 'This engine does not say whether it keeps per-session tool rules — it predates that answer — so the tightening entry stays hidden rather than being written blind.';
-        case 'legacy_tool_name':
-            return RULES_LEGACY_TOOL_NAME_WRITE_NOTE;
+        case 'refused':
+            return SESSION_POLICY_EARLIER_GRAMMAR_NOTE;
+        case 'inert_entry':
+            return SESSION_POLICY_INERT_ENTRY_WRITE_NOTE;
         case 'unknown':
             switch (outcome.why) {
                 case 'face_unavailable':
@@ -348,7 +454,7 @@ export function sessionPolicyTightenNotice(outcome) {
                 case 'write_receipt_unreadable':
                     return 'The tightening was sent but the engine’s answer could not be read — it may already be in effect. Re-read the current rules before writing anything else.';
                 case 'write_receipt_mismatch':
-                    return 'The tightening was sent but the engine’s answer does not account for it (the version did not advance, or the entries sent here are not in the returned record) — it may already be in effect. Re-read the current rules before writing anything else.';
+                    return 'The tightening was sent but the engine’s answer does not account for it (the version did not advance, the entries sent here are not in the returned record, or the record came back without the rule-grammar mark it was sent with, so its entries may now read differently) — it may already be in effect. Re-read the current rules before writing anything else.';
             }
     }
 }
@@ -371,8 +477,10 @@ function readFailureSentence(kind) {
             return 'This session is not readable from here — it may not exist, or it may belong to someone else (the engine answers both the same way, so this client cannot tell which) — so its rule record cannot be shown. Check that you are connected to the engine and the session you meant, or continue in a new session.';
         case 'request-rejected':
             return 'The engine rejected the request to read this session’s rule record as malformed, so it could not be read. Sending the same request again will not change that; check which session was asked for.';
-        case 'legacy-tool-name':
-            return 'The engine answered this read with a refusal about a tool name it no longer accepts, so this session’s rule record could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
+        case 'earlier-grammar':
+            return 'The engine answered this read with a refusal that only applies to writing back rules saved under an earlier rule grammar, so this session’s rule record could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
+        case 'inert-entry':
+            return 'The engine answered this read with a refusal that only applies to writing a rule entry it reads as matching nothing, so this session’s rule record could not be read. Try again; if it keeps happening, whoever runs the engine needs to look at it.';
         case 'unauthorized':
             return 'This call could not present a verifiable identity, so this session’s rule record could not be read.';
         case 'error':
@@ -389,6 +497,8 @@ function readMalformedSentence(why) {
             return 'The engine’s answer for this session’s rule record carried no usable version, so this version will not show it — a record it cannot place may still hold restrictions that are in effect. Try again.';
         case 'rule_field':
             return 'One of the lists in this session’s rule record came back in a form this version cannot read, so none of the record is shown rather than part of it — a partly shown record could leave out restrictions that are in effect.';
+        case 'grammar_stamp':
+            return 'The engine’s answer for this session’s rule record carried a rule-grammar mark this version cannot read, so it will not show the record — the same entry can mean different things in different grammars, so what it allows is not known. Try again; if it keeps happening, this version and the engine may be out of step.';
     }
 }
 function ownRead(o, key) {
@@ -492,9 +602,15 @@ async function attemptRemoval(facade, sessionId, mounted, opts) {
     const { next, removed } = judged;
     if (removed.length === 0)
         return { done: { kind: 'nothing_to_remove', rev: read.rev } };
+    const stamp = grammarStampOf(read);
+    if (stamp === undefined) {
+        const earlier = earlierGrammarEntriesOf(read.rules, next);
+        if (earlier.length > 0)
+            return { done: { kind: 'refused', why: 'earlier_grammar_rows', entries: earlier } };
+    }
     let receipt;
     try {
-        receipt = await facade.putPolicy(sessionId, { rules: next, expectedRev: read.rev }, opts);
+        receipt = await facade.putPolicy(sessionId, { rules: rulesWithStamp(next, stamp), expectedRev: read.rev }, opts);
     }
     catch (e) {
         const failure = classifySessionPolicyFailure(e);
@@ -502,18 +618,10 @@ async function attemptRemoval(facade, sessionId, mounted, opts) {
             return { done: { kind: 'loosen_forbidden', message: failure.message, refused: removed } };
         if (failure.kind === 'cas-conflict')
             return { retryAtRev: read.rev };
-        if (failure.kind === 'legacy-tool-name') {
-            return {
-                done: {
-                    kind: 'legacy_tool_name',
-                    message: failure.message,
-                    ...(failure.field !== undefined ? { field: failure.field } : {}),
-                    ...(failure.name !== undefined ? { name: failure.name } : {}),
-                    ...(failure.verdict !== undefined ? { verdict: failure.verdict } : {}),
-                    ...(failure.currentName !== undefined ? { currentName: failure.currentName } : {}),
-                },
-            };
-        }
+        if (failure.kind === 'earlier-grammar')
+            return { done: earlierGrammarOutcome(failure) };
+        if (failure.kind === 'inert-entry')
+            return { done: { kind: 'inert_entry', ...inertEntryRefusalOf(failure) } };
         return { done: removalFailed(failure, 'write') };
     }
     let narrowed;
@@ -525,7 +633,7 @@ async function attemptRemoval(facade, sessionId, mounted, opts) {
     }
     if (!narrowed.ok)
         return { done: { kind: 'write_unconfirmed', why: 'write_receipt_unreadable', message: narrowed.detail } };
-    const mismatch = receiptMismatch(next, narrowed.rules, read.rev, narrowed.rev) ??
+    const mismatch = receiptMismatch(next, narrowed.rules, read.rev, narrowed.rev, stamp, narrowed.grammar) ??
         (removed.some((e) => {
             const r = Object.hasOwn(narrowed.rules, e.field) ? narrowed.rules[e.field] : undefined;
             return r !== undefined && r.includes(e.rule);
@@ -609,8 +717,10 @@ export function sessionPolicyRemovalNotice(outcome) {
             }
         case 'write_unconfirmed':
             return 'The removal was sent but no clear answer came back from the engine — it may already be in effect. Run the removal again: it re-reads the record, and reports nothing left to remove if it did take effect.';
-        case 'legacy_tool_name':
-            return 'Nothing was changed: the engine refused to write this session’s rule record back, because an entry this removal keeps is a name the engine no longer accepts in that record (the engine\'s own error text names the entry). The removal keeps it on purpose — the supplied roster mounts a tool by exactly that name, or this version does not yet recognise the name as one the engine refuses. While the record holds that entry it cannot be written, so the entries this removal meant to take out stay in it as well.';
+        case 'refused':
+            return SESSION_POLICY_EARLIER_GRAMMAR_NOTE;
+        case 'inert_entry':
+            return 'Nothing was changed: the engine refused to write this session’s rule record back, because an entry this removal keeps reads as matching nothing (the engine’s own error text names the entry and why). This removal only takes out names the engine refuses to start a run with, so it leaves that entry for a person to correct or remove; while the record holds it, it cannot be written, so the entries this removal meant to take out stay in it as well.';
         default:
             return generic;
     }

package/dist/hitl/standingRows.d.ts

@@ -1,4 +1,6 @@
-export type StandingRowWhy = 'given' | 'card_unreadable' | 'remember_refused' | 'remember_unreadable' | 'route_cannot_carry' | 'classes_unreadable' | 'not_deployment_list_question' | 'evidence_unreadable' | 'offers_unreadable' | 'engine_lane_closed' | 'args_unavailable' | 'grant_binding' | 'tool_name_unreadable' | 'rule_cannot_clear' | 'host_fact_missing' | 'face_not_generic' | 'rule_not_sent';
+import { type PermissionsKeptReason } from '../permissionsDeclaration.js';
+import type { PermissionsAllowGrantReading } from '../permissionsAllowGrantCapability.js';
+export type StandingRowWhy = 'given' | 'card_unreadable' | 'remember_refused' | 'remember_unreadable' | 'route_cannot_carry' | 'classes_unreadable' | 'not_deployment_list_question' | 'evidence_unreadable' | 'offers_unreadable' | 'engine_lane_closed' | 'args_unavailable' | 'grant_binding' | 'tool_name_unreadable' | 'rule_cannot_clear' | 'host_fact_missing' | 'card_face_absent' | 'face_not_generic' | 'rule_not_sent';
 export type StandingPersistentRow = 'engine_offer' | 'local_whole_tool' | 'none';
 export interface StandingRowsWhy {
     readonly session: StandingRowWhy;
@@ -12,8 +14,24 @@ export interface StandingRows {
     readonly why: StandingRowsWhy;
 }
 export interface StandingRowsHostFacts {
-    readonly cardFace?: string;
     readonly wholeToolRuleSent?: boolean;
 }
 export declare function standingRowsOf(card: object | null | undefined, host?: StandingRowsHostFacts | null): StandingRows;
 export declare function seatSessionRowOf(card: object | null | undefined, requestId: string | undefined): boolean;
+export type RememberOffer = 'offerable' | 'refused' | 'unknown';
+export interface RememberOfferable {
+    readonly session: RememberOffer;
+    readonly persistentRule: RememberOffer;
+    readonly deploymentList: RememberOffer;
+}
+export declare function rememberOfferable(card: object | null | undefined, host?: StandingRowsHostFacts | null): RememberOfferable;
+export interface LocalAllowRuleHostFacts {
+    readonly hostLadderEnforces?: boolean;
+}
+export interface LocalAllowRuleEnforcement {
+    readonly enforceable: boolean;
+    readonly by?: 'host_ladder' | 'engine_grant';
+    readonly engine: 'sent' | 'kept' | 'unreadable';
+    readonly keptReason?: PermissionsKeptReason;
+}
+export declare function localAllowRuleEnforceable(rule: string, caps: PermissionsAllowGrantReading, host?: LocalAllowRuleHostFacts | null): LocalAllowRuleEnforcement;

package/dist/hitl/standingRows.js

@@ -1,8 +1,9 @@
-import { readAskClassPairState } from './askClassPair.js';
+import { DEPLOYMENT_LIST_ASK_CLASSES, readAskClassPairState } from './askClassPair.js';
 import { automaticAnswerVerdict } from './automaticAnswerVerdict.js';
-import { readRuleOffers } from './toolApprovalWire.js';
+import { readApprovalCardWord, readRuleOffers } from './toolApprovalWire.js';
+import { CORE_SKILL_TOOL_NAME } from '../generated/toolNameTables.js';
 import { toolPermissionRequestIdDomain } from '../seatContract.js';
-const DEPLOYMENT_LIST_ASK_CLASSES = Object.freeze(['ask_rule']);
+import { permissionsDeclarationReport } from '../permissionsDeclaration.js';
 const UNREADABLE = Symbol('unreadable');
 function ownData(v, key) {
     try {
@@ -65,15 +66,17 @@ function persistentRowOf(card, host, evidenceUnreadable) {
     const tool = ownData(card, 'toolName');
     if (typeof tool !== 'string' || tool.length === 0)
         return { row: 'none', why: 'tool_name_unreadable' };
+    if (tool === CORE_SKILL_TOOL_NAME)
+        return { row: 'none', why: 'grant_binding' };
     if (automaticAnswerVerdict(card, 'standing_rule').kind !== 'may_answer')
         return { row: 'none', why: 'rule_cannot_clear' };
-    if (typeof host !== 'object' || host === null)
-        return { row: 'none', why: 'host_fact_missing' };
-    const face = ownData(host, 'cardFace');
-    if (typeof face !== 'string')
-        return { row: 'none', why: 'host_fact_missing' };
+    const face = readApprovalCardWord(card);
+    if (face === undefined)
+        return { row: 'none', why: 'card_face_absent' };
     if (face !== 'generic')
         return { row: 'none', why: 'face_not_generic' };
+    if (typeof host !== 'object' || host === null)
+        return { row: 'none', why: 'host_fact_missing' };
     const sent = ownData(host, 'wholeToolRuleSent');
     if (typeof sent !== 'boolean')
         return { row: 'none', why: 'host_fact_missing' };
@@ -146,3 +149,61 @@ export function seatSessionRowOf(card, requestId) {
         return false;
     }
 }
+const SESSION_OFFER = Object.freeze({
+    given: 'offerable',
+    card_unreadable: 'unknown',
+    remember_refused: 'refused',
+    remember_unreadable: 'unknown',
+    route_cannot_carry: 'refused',
+    classes_unreadable: 'unknown',
+    not_deployment_list_question: 'refused',
+    evidence_unreadable: 'unknown',
+    offers_unreadable: 'unknown',
+    engine_lane_closed: 'refused',
+    args_unavailable: 'refused',
+    grant_binding: 'refused',
+    tool_name_unreadable: 'unknown',
+    rule_cannot_clear: 'refused',
+    host_fact_missing: 'unknown',
+    card_face_absent: 'unknown',
+    face_not_generic: 'refused',
+    rule_not_sent: 'refused',
+});
+const PERSISTENT_OFFER = Object.freeze({ ...SESSION_OFFER, remember_refused: 'unknown' });
+export function rememberOfferable(card, host) {
+    const rows = standingRowsOf(card, host);
+    return Object.freeze({
+        session: SESSION_OFFER[rows.why.session],
+        persistentRule: PERSISTENT_OFFER[rows.why.persistent],
+        deploymentList: SESSION_OFFER[rows.why.deploymentList],
+    });
+}
+export function localAllowRuleEnforceable(rule, caps, host) {
+    const ladder = typeof host === 'object' && host !== null && ownData(host, 'hostLadderEnforces') === true;
+    let engine = 'unreadable';
+    let keptReason;
+    if (typeof rule === 'string' && rule.trim() !== '') {
+        try {
+            const report = permissionsDeclarationReport({ deny: [], ask: [], allow: [rule], settingsRead: 'clean' }, caps);
+            const kept = report.kept.find((k) => k.bucket === 'allow' && k.rule === rule);
+            if (kept !== undefined) {
+                engine = 'kept';
+                keptReason = kept.reason;
+            }
+            else {
+                const sentAs = report.rewritten.find((r) => r.bucket === 'allow' && r.from === rule)?.to ?? rule;
+                engine = report.permissions?.allow?.includes(sentAs) === true ? 'sent' : 'unreadable';
+            }
+        }
+        catch {
+            engine = 'unreadable';
+        }
+    }
+    const by = ladder ? 'host_ladder' : engine === 'sent' ? 'engine_grant' : undefined;
+    return Object.freeze({
+        enforceable: by !== undefined,
+        ...(by !== undefined ? { by } : {}),
+        engine,
+        ...(keptReason !== undefined ? { keptReason } : {}),
+    });
+}