approval-md 0.4.5 → 0.4.7

package/dist/src/core/exec-code.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The `exec.code` gate: what the attested policy says about opaque agent code
+ * (APRV-510, 0.4.5 candidate).
+ *
+ * `python3 -c`, `node -e` and kin, an interpreter running a file that is not a
+ * skill script, and a Hermes `execute_code` call are all programs whose effect
+ * no classifier reads. Before this module every one of them was refused before
+ * policy (`hook-opaque`, `hook-unclassified`, `hook-hermes-execute-code-unbound`),
+ * and that stays the answer for every policy that does not speak: the gate is
+ * CLOSED unless the operator's policy opens it, key by key.
+ *
+ * Two keys, each opening one thing, and an absent key is the closed answer:
+ *
+ * - `exec.code.custody: attested` opens the class for the shell forms. It is the
+ *   operator's statement that credential custody is in place: opaque code run by
+ *   an agent that can read the tenant's credentials is a way round every gate
+ *   that guards them, so the class may not exist without that statement.
+ * - `exec.code.execute_code: hooked`, beside the first, opens Hermes's
+ *   `execute_code`. It is the operator's statement that a tool call made from
+ *   inside the `execute_code` kernel re-fires the hook, which only a live probe
+ *   can establish (`docs/hermes-hook.md`); without it one `execute_code` call
+ *   would be an unbounded bypass of the adapter.
+ *
+ * Pure: a function of the parsed policy and nothing else. It decides whether a
+ * call may be CLASSIFIED `exec.code`; what the class then resolves to is the
+ * policy's ordinary class resolution (an `exec.code` row, an `exec.*` row, or
+ * `defaults.autonomy`), unchanged.
+ */
+import type { Policy } from "./policy-load.js";
+/** The `exec` policy block (schema/policy.schema.json, APRV-510). */
+export interface ExecBlock {
+    code?: {
+        custody?: "attested" | "unattested";
+        execute_code?: "hooked" | "unhooked";
+    };
+}
+/** The class an opened program is judged under. Mirrors `command-class.ts`. */
+export declare const EXEC_CODE_POLICY_CLASS = "exec.code";
+/** The policy line that opens the class, as a refusal names it. */
+export declare const EXEC_CODE_CUSTODY_KEY = "exec.code.custody: attested";
+/** The policy line that opens Hermes `execute_code`, as a refusal names it. */
+export declare const EXEC_CODE_EXECUTE_KEY = "exec.code.execute_code: hooked";
+/**
+ * Why the gate is closed, which decides the refusal's code and words.
+ *
+ * - `silent`: the policy says nothing about `exec.code` (no `exec` block and no
+ *   `exec.code` class row), or there is no policy. The refusal is today's,
+ *   byte for byte.
+ * - `unattested`: the policy names `exec.code` (an `exec` block, or a class row
+ *   for it) without `custody: attested`. The refusal is
+ *   `hook-exec-code-custody-unattested`, naming the key.
+ * - `window`: an open window is standing. A window suspends the policy's
+ *   answer, and opening this class is a policy statement, so it is not reached
+ *   through one; the refusal is today's.
+ * - `harness`: the adapter binds native bytes this class's payload cannot
+ *   carry (Codex), so the class is not opened there; the refusal is today's.
+ */
+export type ExecCodeClosed = "silent" | "unattested" | "window" | "harness";
+export interface ExecCodeGate {
+    /** May a shell segment be classified `exec.code`? */
+    shell: boolean;
+    /** May a Hermes `execute_code` call be classified `exec.code`? */
+    executeCode: boolean;
+    /** Why `shell` is false; `null` when it is true. */
+    closed: ExecCodeClosed | null;
+}
+/** The gate with everything closed for `reason`. */
+export declare function closedExecCodeGate(reason: ExecCodeClosed): ExecCodeGate;
+/**
+ * Does the policy name `exec.code` anywhere? An `exec` block, or a `classes`
+ * key that is exactly `exec.code`. A family row (`exec.*`) is not a mention:
+ * it was written for `exec.local`, and a policy that predates the class keeps
+ * its refusals byte for byte.
+ */
+export declare function execCodeMentioned(policy: Policy): boolean;
+/** What `policy` opens. `null` (no policy loaded) opens nothing. */
+export declare function execCodeGate(policy: Policy | null): ExecCodeGate;

package/dist/src/core/exec-code.js

@@ -0,0 +1,60 @@
+/**
+ * The `exec.code` gate: what the attested policy says about opaque agent code
+ * (APRV-510, 0.4.5 candidate).
+ *
+ * `python3 -c`, `node -e` and kin, an interpreter running a file that is not a
+ * skill script, and a Hermes `execute_code` call are all programs whose effect
+ * no classifier reads. Before this module every one of them was refused before
+ * policy (`hook-opaque`, `hook-unclassified`, `hook-hermes-execute-code-unbound`),
+ * and that stays the answer for every policy that does not speak: the gate is
+ * CLOSED unless the operator's policy opens it, key by key.
+ *
+ * Two keys, each opening one thing, and an absent key is the closed answer:
+ *
+ * - `exec.code.custody: attested` opens the class for the shell forms. It is the
+ *   operator's statement that credential custody is in place: opaque code run by
+ *   an agent that can read the tenant's credentials is a way round every gate
+ *   that guards them, so the class may not exist without that statement.
+ * - `exec.code.execute_code: hooked`, beside the first, opens Hermes's
+ *   `execute_code`. It is the operator's statement that a tool call made from
+ *   inside the `execute_code` kernel re-fires the hook, which only a live probe
+ *   can establish (`docs/hermes-hook.md`); without it one `execute_code` call
+ *   would be an unbounded bypass of the adapter.
+ *
+ * Pure: a function of the parsed policy and nothing else. It decides whether a
+ * call may be CLASSIFIED `exec.code`; what the class then resolves to is the
+ * policy's ordinary class resolution (an `exec.code` row, an `exec.*` row, or
+ * `defaults.autonomy`), unchanged.
+ */
+/** The class an opened program is judged under. Mirrors `command-class.ts`. */
+export const EXEC_CODE_POLICY_CLASS = "exec.code";
+/** The policy line that opens the class, as a refusal names it. */
+export const EXEC_CODE_CUSTODY_KEY = "exec.code.custody: attested";
+/** The policy line that opens Hermes `execute_code`, as a refusal names it. */
+export const EXEC_CODE_EXECUTE_KEY = "exec.code.execute_code: hooked";
+/** The gate with everything closed for `reason`. */
+export function closedExecCodeGate(reason) {
+    return { shell: false, executeCode: false, closed: reason };
+}
+/**
+ * Does the policy name `exec.code` anywhere? An `exec` block, or a `classes`
+ * key that is exactly `exec.code`. A family row (`exec.*`) is not a mention:
+ * it was written for `exec.local`, and a policy that predates the class keeps
+ * its refusals byte for byte.
+ */
+export function execCodeMentioned(policy) {
+    if (policy.exec !== undefined)
+        return true;
+    return Object.prototype.hasOwnProperty.call(policy.classes ?? {}, EXEC_CODE_POLICY_CLASS);
+}
+/** What `policy` opens. `null` (no policy loaded) opens nothing. */
+export function execCodeGate(policy) {
+    if (policy === null)
+        return closedExecCodeGate("silent");
+    const code = policy.exec?.code;
+    if (code?.custody !== "attested") {
+        return closedExecCodeGate(execCodeMentioned(policy) ? "unattested" : "silent");
+    }
+    return { shell: true, executeCode: code.execute_code === "hooked", closed: null };
+}
+//# sourceMappingURL=exec-code.js.map

package/dist/src/core/exec-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-code.js","sourceRoot":"","sources":["../../../src/core/exec-code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAYH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD,mEAAmE;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,6BAA6B,CAAC;AAEnE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,gCAAgC,CAAC;AA4BtE,oDAAoD;AACpD,MAAM,UAAU,kBAAkB,CAAC,MAAsB;IACvD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,sBAAsB,CAAC,CAAC;AAC5F,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC;IAC/B,IAAI,IAAI,EAAE,OAAO,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,kBAAkB,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,YAAY,KAAK,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AACpF,CAAC"}

package/dist/src/core/gate.d.ts

@@ -1096,6 +1096,33 @@ export type RequestResult = {
  * may have changed.
  */
 export declare function request(logPath: string, input: RequestInput, actor: string, options?: GateOptions): RequestResult;
+/**
+ * Why a study denied a request (amended SPEC.md §8), the closed vocabulary of
+ * `payload.study.reason` on `approval.rejected`.
+ *
+ * - `study_withdrawn`: a hosted operator withdrew a still-pending request
+ *   before it could run. Written by the operator's withdraw verb alone, under
+ *   `human:study-team` on channel `study`; a channel may never pass it.
+ * - `looks_wrong`: the resident flagged the card as a suspected study card and
+ *   skipped it. An ordinary resident deny with the flag recorded.
+ */
+export declare const STUDY_REASONS: readonly ["study_withdrawn", "looks_wrong"];
+export type StudyReason = (typeof STUDY_REASONS)[number];
+/**
+ * The study record on a reject (amended SPEC.md §8), written as
+ * `payload.study` on `approval.rejected` only.
+ *
+ * `operator` is an 8-hex pseudonymous id the operator's control plane derives
+ * from the staff email under its own key (never the email), and `ref` is the withdraw's replay reference; both belong to
+ * `study_withdrawn` and the schema refuses them on `looks_wrong`. A record of
+ * why a person denied, never an input: no enforcement path reads it, and a
+ * reader that ignores it reads an ordinary rejection.
+ */
+export interface DecisionStudy {
+    reason: StudyReason;
+    operator?: string;
+    ref?: string;
+}
 export interface DecideOptions extends GateOptions {
     /** Free-text note recorded in the event payload (SPEC.md §8's example). */
     note?: string;
@@ -1188,6 +1215,17 @@ export interface DecideOptions extends GateOptions {
      * here or anywhere reads it back.
      */
     rendering?: PromptRendering;
+    /**
+     * Why a study denied this request (amended SPEC.md §8), recorded as
+     * `payload.study` on `approval.rejected` only.
+     *
+     * Written under the reject's own branch, the way `reaction` sits under the
+     * grant's, so a value passed with `grant` or `revoke` is structurally unable
+     * to reach a record. Copied field by field in a fixed shape, so nothing else
+     * a caller hangs on the object reaches the log. A decision surface supplies
+     * it; there is no CLI flag for it on `approval reject`.
+     */
+    study?: DecisionStudy;
 }
 export type DecideResult = {
     ok: true;

package/dist/src/core/gate.js

@@ -1901,6 +1901,20 @@ function attemptRequest(logPath, input, actor, options) {
         ...(live === null ? {} : { live }),
     };
 }
+// ---------------------------------------------------------------------------
+// decide
+// ---------------------------------------------------------------------------
+/**
+ * Why a study denied a request (amended SPEC.md §8), the closed vocabulary of
+ * `payload.study.reason` on `approval.rejected`.
+ *
+ * - `study_withdrawn`: a hosted operator withdrew a still-pending request
+ *   before it could run. Written by the operator's withdraw verb alone, under
+ *   `human:study-team` on channel `study`; a channel may never pass it.
+ * - `looks_wrong`: the resident flagged the card as a suspected study card and
+ *   skipped it. An ordinary resident deny with the flag recorded.
+ */
+export const STUDY_REASONS = ["study_withdrawn", "looks_wrong"];
 /**
  * The two grades a grant may not carry without the approver's own words
  * (amended SPEC.md §5.2). The same pair `core/audit.ts` enforces on a review,
@@ -2169,6 +2183,18 @@ function attemptDecide(logPath, actionKey, decision, actor, options) {
             ...(options.rendering.say_does_ignored === true ? { say_does_ignored: true } : {}),
         };
     }
+    // Amended SPEC.md §8 (the study record). Reject only: a study may DENY a
+    // pending request and never grant, alter or reopen one, so the field exists
+    // on the one decision that denies. Copied field by field, `operator` and
+    // `ref` only when present; the schema then holds each reason to its shape at
+    // the write boundary.
+    if (decision === "reject" && options.study !== undefined) {
+        payload["study"] = {
+            reason: options.study.reason,
+            ...(options.study.operator === undefined ? {} : { operator: options.study.operator }),
+            ...(options.study.ref === undefined ? {} : { ref: options.study.ref }),
+        };
+    }
     if (decision === "grant") {
         const cls = derivation.declared.class ?? "";
         const resolution = resolve(load, cls, derivation.declared.reversible === null ? {} : { reversible: derivation.declared.reversible });