@sema-agent/core/dist/core/persisted-rule-arms.d.ts

Stateless, task-oriented AI agent core

/**
 * The tool gate's PERSISTED-RULE arms — the pieces of the persisted-rule lane's consumption that are pure
 * functions of (the lane's answer, the standing decision), pulled out of the gate's lane station so the
 * station holds only the wiring: where the read happens, and where each arm is applied.
 *
 * What lives here: {@link applyPersistedTightening} — the DENY and ASK arms (a person's own standing
 * "never run this" and "ask me each time" rows, their settings' deny/ask lists imported into their store),
 * which the station applies to EVERY decision right after the org layer, and again on an approved edit's
 * bytes — and {@link disclosedRuleSet}, the display form both arms and the allow arm's disclosure use. The
 * lane's bounded READ and the ALLOW arm (a standing yes clearing a classify-tier ask) stay in the station:
 * the read closes over the gate input, and the allow arm is a conjunction over the gate's own state
 * (mandates, the org latch, the marked-call seat) rather than a function of the answer alone.
 */
import { type PermissionResult, type ToolCallRequest } from "./tool-policy.js";
import type { PersistedRuleAnswer, PersistedRuleHit, PersistedRuleHitRule } from "./hooks.js";
/** The lane's one read, normalized: at most one of `hit` / `unreadable` / `coverage` (the gate's reader
 *  produces it; the arms below read it). */
export interface PersistedRuleRead {
    readonly hit?: PersistedRuleHit;
    /** The lane could not answer: with `reason`, the CALL could not be read against the person's deny/ask rows;
     *  without, a partition of the store (or all of it) could not be read — a deny / ask row inside it may forbid this call,
     *  so no allow beside it is a yes (the lane has already folded that: an allow, a coverage or nothing reads as this). */
    readonly unreadable?: true;
    /** The lexer's reason when the CALL could not be read against the person's deny/ask rows. */
    readonly reason?: string;
}
/** The answers of one store read judged under each of a call's names, folded as one table folds its rows (deny >
 *  unreadable > ask > allow > coverage > nothing); among equals the first (the wire name's) stands. */
export declare function strongestAnswer(answers: readonly PersistedRuleAnswer[]): PersistedRuleAnswer;
/** Display form of a rule set (design/375 §5.1): every rule text is a DISPLAY value on a human trust
 *  boundary, and the set must stay readable however large a lane makes it — each member rides
 *  `inlineUntrusted` (200 cap, the same cap the durable leg's `RiskDescriptor.shadowedRule` carries),
 *  at most FIVE are listed, and the rest are counted rather than dropped silently. */
export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[]): string;
/**
 * The persisted-rule lane's TIGHTENING arms — a person's own standing DENY and ASK rows — applied to
 * `decision`. The station runs this on EVERY decision, right after the org layer and in the same
 * posture: an allow from the policy fold is exactly what a deny row must be able to refuse, and a bare
 * ask is exactly what an ask row must be able to mark. Precedence across the person's rows is the
 * upstream arbiter's (deny > ask > allow), already resolved inside the lane's one verdict; precedence
 * across AUTHORITIES is org > personal (the org layer ran first, and a personal ask never loosens an
 * org outcome — it stamps a marker on an ask, or turns an allow into one).
 *  · DENY — the call is refused outright, with `decisionReason: "persisted_rule"` (the same word the
 *    lane's allow carries: one authority, one word) and the rule text disclosed through the display
 *    transform; the STATION attributes the refusal (`tightened: "deny"` ⇒ it writes the pass's refusing
 *    layer — the attribution is a station's word and lives in the station file). A path row's hit reports where
 *    it met the call; with `call` given and the face the call's own, the deny carries that as its attested `pathDenial`, so every exit that
 *    reads the deny (the gate's exit, the approved-edit re-check, a resumed leg's belt) mints the same card from the same fact.
 *  · ASK — on an allow, a fresh ask is minted carrying `matchedAskRule` (the marker an explicit `ask`
 *    permission rule stamps, so the ask's origin derives as `ask_rule`: the classifier never answers
 *    it, the persisted ALLOW arm never clears it, and the rule-offer face reports `ask_rule_matched`); on an
 *    ask, the marker is stamped if absent and the message names the rule — the standing question
 *    outranks a remembered yes across lanes, exactly as the DSL's own order says within one; a deny
 *    stays a deny.
 *  · UNREADABLE CALL — the store was read, but the CALL could not be read against the person's standing
 *    deny/ask rows (`reason` carries the lexer's word: an expansion where a rule reads a word, an
 *    unterminated quote, a syntax error): whether a row forbids this call is unknown, so it fails CLOSED —
 *    an allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
 *    derives the origin `rule_store_unavailable` from its own record of the read), an ask acquires the
 *    bit, a deny stays a deny.
 *  · UNREADABLE STORE — a partition of the store (or all of it) could not be READ (`unreadable` without a `reason`): a deny
 *    or ask row inside it may forbid this call and nobody can tell, so it fails CLOSED the same way, to the question
 *    only a person answers — an allow becomes an ask carrying `requiresRealApproval`, an ask acquires the bit, a deny stays
 *    a deny. Every call the lane judges is in this state until a read succeeds again (the lane announces the skipped store,
 *    once per run, and reads again on the next call). The two forms differ in WHICH fact the gate records (one class for
 *    both, `rule_unreadable`, bypass-immune) and in the
 *    resumed-call belt, which vetoes only the call form: a person already answered that call's question.
 * An allow hit (or no hit) returns the decision untouched: the allow arm is the station's.
 */
export declare function applyPersistedTightening(decision: PermissionResult, read: PersistedRuleRead | undefined, call?: ToolCallRequest): {
    decision: PermissionResult;
    tightened?: "deny" | "ask" | "unreadable" | "store_unreadable";
};