@sema-agent/core 7.52.0 → 7.54.0

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

@@ -34,8 +34,30 @@
  * refused and disclosed — identity comparison alone cannot catch it, and an in-memory-only mark would
  * accept revision N−1 after a restart. Signature / predecessor chaining belongs to the privilege-
  * separation ticket; the high-water mark is the floor that needs no key distribution.
+ *
+ * ## One reading of a row
+ *
+ * A snapshot is installed and served on its ENVELOPE ({@link validateOrgSnapshot}: revision, observation
+ * time, a rules list) and the anti-rollback fence; what its rows say never decides which snapshot is in
+ * force. Whether the rules are a list is judged in ONE place ({@link listRefusalOf}) for the partition and for
+ * every store that hands a resolution over — rules that are not a list, or that carry more places than a rule set may
+ * (the same cap the rule compiler holds a set to), are governance nobody can read (the
+ * partition refuses the snapshot; the org lane answers unavailable), never a policy of zero rows — and ONE reader
+ * ({@link orgRuleListOf}) copies the whole list in one receipt: a member of a row that cannot be read is left out of
+ * that row's copy alone, and every row is judged on its copy. A snapshot the partition holds — fetched or read back
+ * from its persistence — is that same copy ({@link orgSnapshotCopyOf}). Every row is then read by ONE reader
+ * ({@link readOrgRules}), the same for every store that hands a resolution over, on its policy members
+ * ({@link ORG_ROW_POLICY_MEMBERS}): a row is READ when its behavior is `deny` or `ask` and its text is a shell command
+ * rule under that behavior. Any other row — another grammar's rule, a shell rule the validator refuses, a row
+ * with no text, a behavior this layer has no bucket for — is UNREADABLE, and stands at its strictest
+ * reading over the calls it may reach ({@link OrgRowReach}): an `ask` row asks a person, every other row
+ * refuses. Readable deny and ask rows hold as published beside it. One unreadable row therefore never
+ * takes the rest of the policy down with it, and never turns a published deny into a question; the
+ * snapshot is served DEGRADED, and every resolution and every adjudication over it names the unreadable
+ * rows ({@link describeUnreadableOrgRows}).
  */
-import { type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import { type ParsedRule, type PersistedRule, type RuleRejectCode } from "./permission-rule-model.js";
+import type { DenyFace } from "../tools/fs/read-deny.js";
 import type { PermissionRuleStore } from "./permission-rule-provider.js";
 /** One org rule. There is structurally no allow bucket (design/179 §9: the org layer only tightens). */
 export interface OrgPermissionRule {
@@ -171,42 +193,183 @@ export declare const UNGOVERNED_ORG_RESOLUTION: Readonly<OrgRuleResolution>;
  *    bound is refused loudly, never coerced.
  */
 export declare function createOrgRulePartition(cfg: OrgRulePartitionConfig): OrgRulePartition;
+/** Whether two snapshots carry the same POLICY: row for row, the same policy members ({@link ORG_ROW_POLICY_MEMBERS}) — never
+ *  observation metadata, never a member no judgment reads (which a copy may carry or leave out). The ONE test of "the same
+ *  revision, the same content": the partition's equal-revision guard asks it of two snapshots it holds in one form
+ *  ({@link orgSnapshotCopyOf}), and a persistence backend asks it of what it stores. */
+export declare function sameOrgPolicyContent(a: OrgRuleSnapshot, b: OrgRuleSnapshot): boolean;
 /**
- * Which entries of an org snapshot the CURRENT rule validator refuses — the published deny/ask rules
- * that can match nothing on this build. Empty ⟺ every rule is enforceable.
+ * Which calls an UNREADABLE row may reach — the calls its strictest reading stands over.
  *
- * Separate from {@link validateOrgSnapshot} because BOTH gates need it: the install gate (a fetched
- * snapshot) and the serving gate (backlog #177 — a snapshot persisted by an earlier build is read back
- * and served without ever having met this validator). It reports every offender rather than the first,
- * since a refusal an administrator cannot act on names no line to fix.
+ * `"every"` when the row names no tool this layer can place: no rule text, a head the rule syntax cannot read, the lone
+ * `*`, or a tool with no rule grammar (a misspelled tool name and a tool this build does not know look the same, and
+ * both may be the shell). Otherwise the rule WORD it names — a shell tool's head is the command word, as a call's is —
+ * and, for a tool whose path rules speak for a face ({@link PATH_RULE_FACES}), the faces of the column its strictest
+ * behavior reads: such a row reaches what a readable rule of its tool could reach, and nothing else.
+ */
+export type OrgRowReach = "every" | {
+    readonly words: readonly string[];
+    readonly faces: readonly DenyFace[];
+};
+/**
+ * A row the layer cannot read: its text (as published; the rendering of the scalar its `rule` holds when that is not a string;
+ * `<unreadable>` when it holds none — a structure is no value, {@link orgRowPolicyOf}), its 1-based place in the
+ * snapshot, why (`code`, and `detail` for a row whose shape — not its text — is at fault), the behavior it stands at, and
+ * the calls it reaches. `behavior` is the row's STRICTEST reading: `ask` only when the row says `ask`, `deny` for a row
+ * that says `deny` and for one whose behavior cannot be read.
+ */
+export interface UnreadableOrgRow {
+    readonly kind: "unreadable";
+    readonly index: number;
+    readonly rule: string;
+    readonly code: RuleRejectCode;
+    readonly detail?: string;
+    readonly behavior: "deny" | "ask";
+    readonly reach: OrgRowReach;
+}
+/** A row the layer reads: a shell command rule under the behavior it publishes. */
+export interface ReadOrgRow {
+    readonly kind: "read";
+    readonly index: number;
+    readonly rule: string;
+    readonly behavior: "deny" | "ask";
+    readonly parsed: ParsedRule;
+}
+/** One call as the org layer judges it: the rule words it answers to (`laneToolNamesOf`; one word is enough), its shell
+ *  command when it is the shell tool's, and the face of its path target when it has one (`callPathFaceOf`). */
+export interface OrgRuleCall {
+    readonly tool: string | readonly string[];
+    readonly command?: string;
+    readonly face?: DenyFace;
+}
+/** Every row of a snapshot read once, and the one judgment of a call against them. */
+export interface OrgRulesReading {
+    readonly rows: readonly (ReadOrgRow | UnreadableOrgRow)[];
+    readonly unreadable: readonly UnreadableOrgRow[];
+    verdictFor(call: OrgRuleCall): OrgRuleVerdict | undefined;
+}
+/**
+ * The members of an org row the layer reads to judge a call — the row's POLICY. A row IS these members: every reader holds and
+ * judges a row as its policy ({@link orgRowPolicyOf}), and two rows with the same policy members are the same policy
+ * ({@link sameOrgPolicyContent}). Any other member a row carries is never judged, held, served or persisted (the receipt reads
+ * each of a row's own members once — a getter on one runs once — and copies none of what it holds beyond a scalar).
+ */
+export declare const ORG_ROW_POLICY_MEMBERS: readonly ["rule", "behavior"];
+/** A JSON scalar — the only value a member the partition keeps holds as data. */
+type Scalar = string | number | boolean | null;
+type ScalarMembers<K extends string> = {
+    [P in K]?: Scalar;
+};
+type OrgRowPolicy = Readonly<ScalarMembers<(typeof ORG_ROW_POLICY_MEMBERS)[number]>>;
+/**
+ * The envelope's rules LIST, read once: `refused` when it is not a list of at most the cap's places ({@link listRefusalOf} —
+ * judged before the list is received, so an oversized or sparse list builds no row) or cannot be received at all;
+ * otherwise its rows, each as its policy ({@link orgRowPolicyOf}) — the list received whole in one receipt
+ * ({@link ORG_RULES_RECEIPT}), so a row's member that cannot be read is that row's alone, a row that cannot be read at all (and
+ * a hole) is a row with nothing in it (`{}`: no rule text, read at its strictest reading) and the rows beside it are untouched.
+ * The ONE reader of the list — the partition holds a snapshot's rows as these, fetched and read back alike
+ * ({@link orgSnapshotCopyOf}), and every reading of rows ({@link readOrgRules}) reads them through it — so no store's rows can be
+ * read two ways, and no row can take the reading of another down with it.
+ */
+export declare function orgRuleListOf(rules: unknown): {
+    readonly rows: readonly OrgRowPolicy[];
+} | {
+    readonly refused: string;
+};
+/** A snapshot the partition holds whose rules the list judgment refused: the envelope it carried and the words it was refused in,
+ *  judged ONCE, on the list as it stood at the receipt. It has no `rules` at all (so no reading can take it for a table of zero
+ *  rows) and keeps none of the caller's value (a list past the cap is a live array, and the partition awaits its persistence
+ *  between the receipt and the validator, so a source that shrank the list it handed over in between would otherwise be admitted,
+ *  uncopied and mutable, on a judgment it no longer meets). It is never installed or served. */
+export interface RefusedOrgSnapshot extends Omit<OrgRuleSnapshot, "rules"> {
+    readonly refused: string;
+}
+/** What the partition holds of one snapshot, fetched or read back: one that can be installed, or the refusal of one that cannot.
+ *  Read it by its shape — `rules` is on the first arm only, and {@link validateOrgSnapshot} is the one way from a held snapshot to an
+ *  installable one. */
+export type HeldOrgSnapshot = OrgRuleSnapshot | RefusedOrgSnapshot;
+/** A snapshot as the partition holds it — fetched from the source or read back from its persistence alike: its envelope's members
+ *  ({@link ORG_SNAPSHOT_ENVELOPE_MEMBERS} through {@link scalarMembersOf}; anything else it carries is never read or kept), its
+ *  rows as the one list reader reads them (each row its policy) — so a snapshot read back reads, and compares, exactly as the one
+ *  fetched, and what is persisted is never larger than these. Rules the list judgment refuses (not a list, a Proxy, past the cap)
+ *  are held as that refusal alone ({@link RefusedOrgSnapshot}; the list judgment runs no code of the value's); such a snapshot — and
+ *  one that is not an object, whose envelope has no members — is never installed or served. A list that cannot be received, and a
+ *  Proxy snapshot (its traps would answer for the envelope), throw: an envelope that cannot be copied. Exported for the pins; the
+ *  package root does not carry it. */
+export declare function orgSnapshotCopyOf(v: unknown): HeldOrgSnapshot;
+/**
+ * The ONE reading of an org snapshot's rows: each row read once ({@link readOrgRow}), and the one judgment of a call
+ * against them. Every reader of org rows goes through it — the partition's degraded line, the lane's adjudication,
+ * {@link orgRuleVerdictFor}, {@link unenforceableOrgRules} and the shadow view — so no two of them can read one row two ways.
+ *
+ * A call meets the rows in three answers. DENY: a readable deny reaches one of its program runs, or an unreadable row
+ * standing at deny reaches the call — the first such row in snapshot order speaks. ASK: a readable rule the call cannot be
+ * READ against (the lexer's reason — a rule that cannot be judged may be a deny, so it outranks a reached ask), else a
+ * readable ask reaching it or an unreadable row standing at ask reaching it, the first in snapshot order. Otherwise none.
+ * An unreadable row's verdict carries its reason ({@link unreadableOrgRowReason}) beside its text.
+ *
+ * The rows are read off the one list reader's copy ({@link orgRuleListOf}): rules that are not a list come back `refused` —
+ * the org's rules cannot be read, which is never a policy of zero rows — and a row is judged on what its copy holds: a policy
+ * member that could not be read is one the row does not have (no `rule` ⇒ no rule text, every call; no `behavior` ⇒ its
+ * strictest reading over the calls of the tool it names), read like any other unreadable row while the rows beside it keep
+ * their effect.
+ */
+export declare function readOrgRules(rules: unknown): OrgRulesReading | {
+    readonly refused: string;
+};
+/**
+ * Which rows of an org snapshot this layer cannot read, each with its code — the rows that stand at their strictest
+ * reading instead of as published. Empty ⟺ every row is read. Every unreadable row is reported, a row with no rule text
+ * or a behavior other than deny / ask included (its text rendered when it is not a string). Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a reading of fewer rows.
  */
 export declare function unenforceableOrgRules(rules: readonly OrgPermissionRule[]): Array<{
     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 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;
+/**
+ * The ONE line naming a snapshot's unreadable rows (count, the first {@link DISCLOSED_UNREADABLE_ROWS} by place, text and
+ * code, the rest summarized), or `undefined` when every row is read. The partition puts it on every resolution that
+ * serves such a snapshot, and the org lane hands it to its operator sink on every adjudication over one, so the two seats
+ * describe one snapshot in one sentence. Each text is escaped — the characters that most often make a row unreadable are
+ * exactly the ones that do not render.
+ */
+export declare function describeUnreadableOrgRows(unreadable: readonly UnreadableOrgRow[], revision?: unknown): string | undefined;
 /**
- * design/182 §7.2 — which org rule speaks for this command, if any. Deny outranks ask; within a
- * behavior the first textual match wins (reporting order only — all denies are the same one answer).
- * Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
- * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a
- * legitimately wide tightening and matches; a segment hit is a hit; a call the lexer cannot read
- * against a rule is an ASK with the reason — fail closed, never silence).
- *
- * The skip below is a defensive floor, and what stands behind it is worth stating precisely: rules that
- * arrive from the org partition's `resolve` ({@link createOrgRulePartition}) have passed {@link validateOrgSnapshot} on BOTH the install
- * and the serving path (backlog #177), so an unenforceable entry cannot reach here through the overlay
- * — the whole snapshot is refused, or the resolution reports `unavailable`, and either way it is
- * disclosed. A caller that hands this function a snapshot it obtained ELSEWHERE gets no such guarantee:
- * the skip is silent, and naming the dead entries is that caller's job — {@link unenforceableOrgRules}
- * is the shared way to do it.
+ * Envelope validation of one held snapshot — what the staleness bound and the anti-rollback fence need to judge it. Answers
+ * the snapshot as an installable one, or the words it is refused in: a finite revision, a finite observation time not in the
+ * future beyond the skew allowance, and rules that are a LIST ({@link listRefusalOf}, judged at the receipt — a held snapshot
+ * whose list was refused there is answered in those words). The rows inside are not judged here: a row this layer cannot
+ * read is read as such by {@link readOrgRules}, and never takes the rest of the snapshot down with it.
+ *
+ * Run on BOTH the fetch path (before install) and the serving path (before a persisted snapshot adjudicates), so the
+ * two cannot diverge on what an installable snapshot is — see backlog #177. The only way from a {@link HeldOrgSnapshot} to an
+ * installable {@link OrgRuleSnapshot}: install and serve read the `admitted` arm.
  */
-export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: {
-    tool: string;
-    command: string;
-}): OrgRuleVerdict | undefined;
-/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the call could
- *  not be READ against the org's rules, the lexer's reason beside the first rule it could not judge
- *  (`behavior` is then `ask`: the org published a rule that may reach this call, and nobody can say). */
+export declare function validateOrgSnapshot(s: HeldOrgSnapshot, nowMs: number): {
+    readonly admitted: OrgRuleSnapshot;
+} | {
+    readonly refused: string;
+};
+/**
+ * design/182 §7.2 — which org rule speaks for this call, if any: {@link readOrgRules}'s judgment, over a snapshot read for
+ * this call alone. Matching uses the SAME parser and the SAME tightening reach the personal deny/ask rows use
+ * ({@link programRunReachOf}: an interpreter-headed prefix deny like `Bash(node:*)` is a legitimately wide tightening and
+ * matches; a segment hit is a hit; a call the lexer cannot read against a rule is an ASK with the reason — fail closed,
+ * never silence), and a row this layer cannot read stands at its strictest reading over the calls it may reach. A caller
+ * judging many calls against one snapshot reads it once with {@link readOrgRules} instead. Rules that are not a list, or a
+ * list past the cap, throw the one list judgment's sentence ({@link readListedOrgRules}) — never a verdict over fewer rows.
+ */
+export declare function orgRuleVerdictFor(rules: readonly OrgPermissionRule[], call: OrgRuleCall): OrgRuleVerdict | undefined;
+/** The org layer's answer for one call: which rule spoke, with what behavior — and, when the rule could not be judged
+ *  against the call, why (`unreadable`): either the call could not be READ against it (the lexer's reason; `behavior` is
+ *  then `ask` — the org published a rule that may reach this call, and nobody can say), or the row is not one this layer
+ *  reads ({@link unreadableOrgRowReason}; `behavior` is the row's strictest reading). */
 export interface OrgRuleVerdict {
     readonly behavior: "deny" | "ask";
     readonly rule: string;
@@ -234,14 +397,18 @@ export interface OrgRuleVerdict {
  * either way. org ASK rules do not shadow: the personal lane never consumes a `requiresRealApproval`
  * ask, so the two never actually meet on one call.
  *
- * design/382 §2.6 — a Read directory rule is never org-shadowed in this version: the org layer has no
- * Read grammar (a snapshot carrying one refuses whole at the validator), so there is no deny that could
- * reach it, and its `command` is a PATH that must not be fed to the shell lane's segment reader as
- * though it were a command line.
+ * An UNREADABLE row standing at deny refuses every call it reaches ({@link readOrgRules}), so it shadows every personal
+ * rule of a tool it reaches — by the rule word, or by the face that tool's calls are on — exactly as the gate refuses
+ * those calls; one standing at ask does not shadow, as a readable ask does not.
+ *
+ * design/382 §2.6 — no READABLE org row reaches a Read directory rule in this version: the org layer has no Read
+ * grammar, and the rule's `command` is a PATH that must not be fed to the shell lane's segment reader as though it
+ * were a command line.
  */
 export declare function orgRuleShadows(orgRules: readonly OrgPermissionRule[], rule: Pick<PersistedRule, "tool" | "command">): boolean;
-/** The shadow predicate with the org denies parsed ONCE — what a read over many rows uses. */
+/** The shadow predicate with the org rows read ONCE — what a read over many rows uses. */
 export declare function compileOrgShadowPredicate(orgRules: readonly OrgPermissionRule[]): (rule: Pick<PersistedRule, "tool" | "command">) => boolean;
 /** Does this store carry a write face? Re-exported convenience for org-ticket integrations that need to
  *  distinguish a read-only projection from a writable personal bucket without importing the writer seam. */
 export declare function isWritablePermissionRuleStore(store: PermissionRuleStore): boolean;
+export {};