@intutic/gate 2.9.1 → 3.0.0

package/dist/gateRuleRecord.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Rule records in the policy snapshot: the `@rule` record, its
+ * fallback line, and how a gate that reads it decides a call (Tier R).
+ *
+ * A gate that cannot evaluate a rule must refuse what the rule covers, never
+ * skip it. So for each rule a gate is to enforce, the snapshot writer emits
+ * two lines inside the digest, as the decide records do:
+ *
+ * - an `@rule` record of five tab-separated columns: the tag, the fallback
+ *   line's id or `-`, the kind, the rollout (`shadow` or `enforce`), and
+ *   base64 of the canonical JSON of its payload, `{v, ref, sopTitle, …kind
+ *   fields}`. Every reader up to v22 needs six
+ *   columns for a rule, so it skips the record;
+ * - for an enforcing record, a fallback line: an ordinary `block` rule whose
+ *   id is `<kind>-fallback:<n>@<sha256(sopId)[:12]>`
+ *   ({@link gateRuleFallbackId}), on what the rule covers
+ *   ({@link gateRuleFallback}). A gate that reads `@rule` records skips a
+ *   fallback line only when a record that decodes names it.
+ *
+ * A snapshot with any `@rule` record is written in format 3
+ * ({@link RULE_SNAPSHOT_FORMAT}). Kinds in this batch:
+ *
+ * | Kind | From | Gate decision |
+ * |---|---|---|
+ * | `requires_outcome` | `requires_before: action:run_tests[ok] -> X` | X refused `PREREQUISITE_UNMET` unless the latest test run in the session passed |
+ * | `scope_paths` | `scope_paths:` with `scope_paths_mode: enforce` | a file change outside the scope refused `OUT_OF_SCOPE` |
+ * | `plan_approval` | `plan_approval: required\|strict` | refused `PLAN_NOT_APPROVED` until the session's plan is approved; under `strict`, a tool not in the plan refused `OFF_PLAN` |
+ *
+ * Only SOPs with no `roles:` compile: a gate knows no agent role.
+ *
+ * Self-contained but for `./testOutcome.ts`, `./scopeMatch.ts`, `./lanes.ts`
+ * and `./phrases.ts` (all carried by `@intutic/gate` as byte-identical
+ * copies), so `@intutic/gate` keeps a byte-identical copy of this file too.
+ * The Python port is `intutic_clawde/gate/rule_record.py`; both run
+ * `fixtures/rule-record-vectors.json`.
+ *
+ * @module
+ */
+import { type OutcomeState } from './testOutcome.js';
+import type { RefusalScope } from './refusalDetail.js';
+/** First column of a rule record. */
+export declare const RULE_RECORD_TAG = "@rule";
+/** The snapshot format a snapshot carrying any rule record is written in. */
+export declare const RULE_SNAPSHOT_FORMAT = 3;
+/** The longest SOP title a record carries, in code points. */
+export declare const RULE_SOP_TITLE_MAX_CHARS = 80;
+/** The most scope paths one record carries, and the longest of them in code points. */
+export declare const RULE_SCOPE_PATHS_MAX = 64;
+export declare const RULE_SCOPE_PATH_MAX_CHARS = 512;
+export type GateRuleKind = 'requires_outcome' | 'scope_paths' | 'plan_approval';
+export declare const GATE_RULE_KINDS: readonly GateRuleKind[];
+/** The four action tokens a v22 hook gate's classifier knows: a fallback on one of them can use the `action` subject. */
+export declare const V22_ACTION_TOKENS: readonly string[];
+interface GateRuleRecordBase {
+    v: 1;
+    /** `<sopId>#<kind>:<n>`. */
+    ref: string;
+    sopTitle: string;
+    /** The paired fallback line's id; null when the record is shadow and has none. */
+    fallbackId: string | null;
+    rollout: 'shadow' | 'enforce';
+}
+export interface RequiresOutcomeRecord extends GateRuleRecordBase {
+    kind: 'requires_outcome';
+    first: 'action:run_tests';
+    qualifier: 'ok';
+    /** The gated token or tool. */
+    then: string;
+    /** `~>`: the run must be the call right before. */
+    adjacent: boolean;
+}
+export interface ScopePathsRecord extends GateRuleRecordBase {
+    kind: 'scope_paths';
+    scopePaths: string[];
+}
+export interface PlanApprovalRecord extends GateRuleRecordBase {
+    kind: 'plan_approval';
+    mode: 'required' | 'strict';
+}
+export type GateRuleRecord = RequiresOutcomeRecord | ScopePathsRecord | PlanApprovalRecord;
+/** `ref`: `<sopId>#<kind>:<n>`. */
+export declare function gateRuleRef(sopId: string, kind: GateRuleKind, n: number): string;
+/** `fallbackId`: `<kind>-fallback:<n>@<first 12 hex of sha256(sopId)>`. */
+export declare function gateRuleFallbackId(kind: GateRuleKind, n: number, sopId: string, sha256Hex: (text: string) => string): string;
+/** What an older gate says when a rule's fallback line refuses. The writer scrubs and bounds it like any reason. */
+export declare function gateRuleFallbackReason(kind: GateRuleKind, sopTitle: string): string;
+/** The record's payload: everything but the kind, the fallback id and the rollout, which are columns. */
+export declare function gateRulePayload(record: GateRuleRecord): {
+    v: 1;
+    ref: string;
+    sopTitle: string;
+} & Record<string, unknown>;
+/** The record as one `.rules` line. */
+export declare function encodeGateRuleRecord(record: GateRuleRecord): string;
+/**
+ * Reads an `@rule` line back, its kind, fallback id and rollout from the
+ * columns and the rest from the payload. Null, and so the fallback line stays
+ * in force, for any other line or when: it does not have five columns; the
+ * base64 or JSON is damaged; the kind (column 3) is unknown; the payload has
+ * a field its kind does not have or lacks one; the rollout (column 4) is not
+ * `shadow` or `enforce`; a field is out of its bounds; the ref does not end
+ * `#<kind>:<n>`; an enforcing record's fallback id (column 2) is not
+ * `<kind>-fallback:<n>@<12 hex>` for the same n, or a shadow record's is
+ * not `-`.
+ */
+export declare function decodeGateRuleRecord(line: string): GateRuleRecord | null;
+/**
+ * A record as the control plane serves it from policy resolve
+ * (`ResolvedPolicy.gateRecords`): which SOP it came from, its kind, rollout
+ * and fallback id, and the payload the `@rule` line carries.
+ */
+export interface ServedGateRecord {
+    sopId: string;
+    kind: GateRuleKind;
+    rollout: 'shadow' | 'enforce';
+    fallbackId: string | null;
+    payload: {
+        v: 1;
+        ref: string;
+        sopTitle: string;
+    } & Record<string, unknown>;
+}
+/** A record in the served shape. */
+export declare function toServedGateRecord(record: GateRuleRecord, sopId: string): ServedGateRecord;
+/**
+ * A served record as a gate record, or null when it does not hold together:
+ * checked by encoding it and reading the line back, so a writer never emits
+ * a record no gate can decode (its fallback line would refuse instead).
+ */
+export declare function fromServedGateRecord(served: ServedGateRecord): GateRuleRecord | null;
+/** The parts of a parsed SOP (`ParsedFrontMatter`, guardrailRender.ts) the records are compiled from. */
+export interface GateRuleFrontMatter {
+    roles: readonly string[];
+    mode: 'shadow' | 'enforce';
+    requiresBefore: ReadonlyArray<readonly [string, string, boolean]>;
+    scopePaths: readonly string[];
+    scopePathsMode: 'advise' | 'enforce';
+    planApproval: 'required' | 'strict' | null;
+}
+/** One fallback line, in the shape the snapshot writer's `GuardPattern` takes (it adds the rationale). */
+export interface GateRuleFallback {
+    id: string;
+    severity: 'block';
+    subject: 'tool' | 'action' | 'phrase';
+    source: string;
+    ignoreCase: boolean;
+    reason: string;
+}
+/**
+ * The fallback line for an enforcing record: what an older gate refuses in
+ * its place. `requires_outcome`: the gated call (by the action subject for
+ * the four tokens a v22 classifier knows, by the token's phrases for a newer
+ * token, by the shell tools for a token with no phrases, by the tool subject
+ * for a tool); `scope_paths`: every mutation tool; `plan_approval`: every call.
+ */
+export declare function gateRuleFallback(record: GateRuleRecord): GateRuleFallback | null;
+/**
+ * The records (and, for each enforcing one, its fallback line) one SOP
+ * compiles to: each qualified `requires_before`, then its `scope_paths` when
+ * `scope_paths_mode: enforce`, then its `plan_approval:`. Nothing for a SOP
+ * with `roles:` (a gate knows no role). A shadow SOP (`mode: shadow`, or
+ * `entry.shadow`, which the writer sets for SILENT_LOG) gets shadow records
+ * and no fallback lines.
+ */
+export declare function compileSopGateRecords(entry: {
+    sopId: string;
+    sopTitle: string;
+    shadow?: boolean;
+}, fm: GateRuleFrontMatter, sha256Hex: (text: string) => string): {
+    records: GateRuleRecord[];
+    fallbacks: GateRuleFallback[];
+};
+/** The refusal codes Tier R gives. */
+export type GateRuleCode = 'PREREQUISITE_UNMET' | 'OUT_OF_SCOPE' | 'OFF_PLAN' | 'PLAN_NOT_APPROVED';
+/** The session's plan as a gate reads it: approved (APPROVED or EXECUTING) with its tools, none, or not readable. */
+export type GateRulePlan = {
+    status: 'approved';
+    tools: readonly string[];
+} | {
+    status: 'none';
+} | {
+    status: 'unavailable';
+};
+/**
+ * The session's plan from `GET /api/v1/plans/session/:sessionId`: `status`
+ * is the HTTP status, or null when the control plane could not be reached.
+ * 200 with `lifecycleState` APPROVED or EXECUTING is approved, its tools the
+ * steps' `tool` (or `toolName`) names; 200 in any other state, and 404, are
+ * none; anything else is unavailable, which refuses as none does.
+ */
+export declare function gateRulePlanFromResponse(status: number | null, body: unknown): GateRulePlan;
+/** One call, and what the gate knows of its session, for {@link evaluateGateRuleRecords}. */
+export interface GateRuleCall {
+    tool: string;
+    input: unknown;
+    /** The action tokens the call classifies to. */
+    actions: readonly string[];
+    /** The gate's working directory and the workspace root (the nearest `.git` above it, else the directory itself). */
+    cwd: string;
+    root: string;
+    /** The session id; empty when the harness sent none. */
+    sessionId: string;
+    /** The harness's name, for the reasons. */
+    harness: string;
+    /** The session's outcome state, or null when there is none or it does not read. */
+    outcomes: OutcomeState | null;
+    /** The harness reports tool results the gate can read (its post event is confirmed). */
+    observable: boolean;
+    /** The session's plan; only read when a `plan_approval` record applies. */
+    plan: GateRulePlan;
+    nowMs: number;
+}
+export interface GateRuleFinding {
+    code: GateRuleCode;
+    /** The rule id the refusal and its events name. */
+    ruleId: string;
+    reason: string;
+    scope: RefusalScope;
+    /** The record's ref, or the first record's when several decided together. */
+    ref: string;
+}
+export interface GateRuleEvaluation {
+    /** The first enforcing record that refuses, or null to let the call on. */
+    refusal: GateRuleFinding | null;
+    /** What the shadow records would have refused, recorded and not acted on. */
+    shadow: GateRuleFinding[];
+}
+/**
+ * Tier R: the snapshot's rule records against one call. The enforcing
+ * records' first finding refuses; the shadow records' findings are reported
+ * and change nothing. A rule failure (an unreadable plan feed, an unreadable
+ * outcome state) is a finding, so it refuses whatever the client's
+ * `failClosed` says.
+ */
+export declare function evaluateGateRuleRecords(records: readonly GateRuleRecord[], call: GateRuleCall): GateRuleEvaluation;
+/**
+ * The decoder and Tier R as JavaScript source, for the hook gates to embed
+ * after `PHRASES_JS_SOURCE`, `TEST_OUTCOME_JS_SOURCE` and
+ * `SCOPE_MATCH_JS_SOURCE`, whose functions these call. The constants the
+ * functions read are written into the source.
+ */
+export declare const RULE_RECORD_JS_SOURCE: string;
+export {};
+//# sourceMappingURL=gateRuleRecord.d.ts.map

package/dist/gateRuleRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateRuleRecord.d.ts","sourceRoot":"","sources":["../src/gateRuleRecord.ts"],"names":[],"mappings":"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"}