@fungi.computer/approvals 0.0.0-stage → 0.0.2

package/dist/ledger.d.ts

@@ -0,0 +1,203 @@
+import * as Schema from "effect/Schema";
+import type { WatchdogSqliteOwner } from "@fungi.computer/watchdog";
+import { type ApprovalEvidence, type ApprovalRecord, type Approvals, type ApprovalRefusal, type ApprovalAnswerInput, type AutoApproveInput, type PendingApproval } from "./contract.js";
+/** Canonical zero-effect or lifecycle refusal at a tool result boundary. */
+export declare const ApprovalRefusalSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"refused">;
+    readonly reason: Schema.Literals<readonly ["not-found", "not-eligible", "already-answered", "stale-revision", "expired", "declined", "fenced", "not-granted", "read-only", "pending", "in-flight", "outcome-unknown", "identity-conflict"]>;
+}>;
+/** Native owner of this ledger; the Local runtime supplies its own SQLite owner. */
+export type ApprovalHome = Readonly<{
+    kind: "team" | "oyster" | "local";
+    id: string;
+}>;
+/** A request is host-attested metadata and JSON bytes, never renderer-provided identity. */
+export type ApprovalRequest = Readonly<{
+    requester: ApprovalRecord["requester"];
+    module: string;
+    operation: string;
+    access: ApprovalRecord["access"];
+    reversibility: ApprovalRecord["reversibility"];
+    authorityFence: string;
+    /** Persisted turn/tool identity and operation ordinal; never random on retry. */
+    idempotencyKey: string;
+    inputJson: string;
+}>;
+/** Host-only policy read for an admitted Agent/module/access selection, not execution authority. */
+export type AutoApproveQuery = Readonly<{
+    agentId: ApprovalRequest["requester"]["agentId"];
+    module: ApprovalRequest["module"];
+    access: ApprovalRequest["access"];
+}>;
+/** Host-attested human identity and current authority over this exact operation. */
+export type ApprovalAnswerer = Readonly<{
+    kind: "human";
+    memberId: string;
+    role: "owner" | "admin" | "member";
+    actingForAgent: boolean;
+    mayUseOperation: boolean;
+}> | Readonly<{
+    kind: "agent" | "key";
+}>;
+/**
+ * Host-attested authority to write one auto-approve rule. A Team home
+ * resolves it against the exact rule: mayUseOperation for that family and
+ * mayManageAgent (agent.manage on that Agent; owners and admins hold it
+ * Team-wide). An answerer without mayManageAgent never manages an Agent.
+ * Oyster and Local homes are owner-only.
+ */
+export type ApprovalRuleSetter = ApprovalAnswerer | (Extract<ApprovalAnswerer, {
+    kind: "human";
+}> & Readonly<{
+    mayManageAgent: boolean;
+}>);
+/** Mycelium owns admission; the ledger compares its opaque fence, never grant grammar. */
+export type ApprovalAdmission = Readonly<{
+    kind: "authorized";
+    authorityFence: string;
+}> | Readonly<{
+    kind: "refused";
+    reason: "not-granted" | "read-only";
+}>;
+/** Host verdict outside App JSON: only an attested zero-effect refusal is denied. */
+export type ApprovalDispatchCompletion = Readonly<{
+    kind: "completed";
+    output: typeof Schema.Json.Type;
+}> | Readonly<{
+    kind: "refused";
+    reason: "not-granted" | "read-only";
+}>;
+/** Host-only adapter to the existing operation door; not an Agent continuation. */
+export type ApprovalApplyHost = Readonly<{
+    /** Re-read requester grants and the operation fence immediately before dispatch. */
+    recheck: (record: ApprovalRecord) => Promise<ApprovalAdmission>;
+    /** Attempt the admitted operation once through the existing host operation door. */
+    dispatch: (request: Readonly<{
+        record: ApprovalRecord;
+        input: typeof Schema.Json.Type;
+    }>) => Promise<ApprovalDispatchCompletion>;
+}>;
+/** Only the submitting capability may attach evidence; never spread tool input here. */
+export type ApprovalSubmitHost = ApprovalApplyHost & Readonly<{
+    evidence?: ApprovalEvidence;
+}>;
+/** Private result for inline tool output or ordinary deferred new-message delivery. */
+export type ApprovalApplyResult = Readonly<{
+    kind: "applied";
+    record: ApprovalRecord;
+    output: typeof Schema.Json.Type;
+}> | ApprovalRefusal;
+/** Deferred result cargo; stored request input is not a field on this port. */
+export type ApprovalResultNotice = Readonly<{
+    deliveryId: string;
+    record: ApprovalRecord;
+    result: ApprovalApplyResult;
+}>;
+/** Ordinary new-message receipt, explicit no-delivery result, or typed refusal. */
+export type ApprovalHandoffResult = Readonly<{
+    kind: "delivered";
+    commandId: string;
+}> | Readonly<{
+    kind: "not-required";
+}>
+/** The home's attempt limit was reached; the decided record is kept. */
+ | Readonly<{
+    kind: "undeliverable";
+}> | ApprovalRefusal;
+/** The initial owner-controlled wait duration; passing the deadline never approves. */
+export declare const DEFAULT_APPROVAL_EXPIRY_MS: number;
+/** SQLite lifecycle beside Mycelium. Native owner transactions serialize every transition. */
+export declare class ApprovalLedger {
+    private readonly options;
+    private readonly homeKey;
+    constructor(options: Readonly<{
+        owner: WatchdogSqliteOwner;
+        home: ApprovalHome;
+        now: () => number;
+        /** Host-private dispatch target, committed in the same SQLite transaction as the record. */
+        persistIntent?: (record: ApprovalRecord) => undefined;
+        /**
+         * Present when this home's wake sends result messages: its wake then
+         * covers undelivered results, and a failed send waits retryDelay(attempt)
+         * from the home's existing delivery policy before the next try. The
+         * attemptLimit-th failure makes the result undeliverable: no more wakes.
+         */
+        resultDelivery?: Readonly<{
+            retryDelay: (attempt: number) => number;
+            attemptLimit: number;
+        }>;
+    }>);
+    /** Bound control surface; null identity means membership is gone, never an impersonated key. */
+    capability(host: Readonly<{
+        actor: (record: ApprovalRecord | null) => Promise<ApprovalAnswerer | null>;
+        decision: (recordId: string) => Promise<void>;
+        /** Team homes: the setter's authority over this exact rule. Without it a Team rule write is refused. */
+        setter?: (rule: AutoApproveInput) => Promise<ApprovalRuleSetter | null>;
+    }>): Approvals;
+    private eligible;
+    /** Normal tool admission returns pending immediately, or applies policy approval inline. */
+    submit(input: ApprovalRequest, host: ApprovalSubmitHost): Promise<PendingApproval | ApprovalApplyResult>;
+    /** A retried request's current outcome, without claiming any work. */
+    outcome(record: ApprovalRecord): PendingApproval | ApprovalApplyResult;
+    /**
+     * Stage one stable intended effect. Duplicate identities never create
+     * another action; created says whether this call staged the record.
+     */
+    request(input: ApprovalRequest, evidence?: ApprovalEvidence): Promise<Readonly<{
+        kind: "record";
+        record: ApprovalRecord;
+        created: boolean;
+    }> | ApprovalRefusal>;
+    /** Answering is revision-pinned and never changes the requester's underlying grants. */
+    answer(input: ApprovalAnswerInput, actor: ApprovalAnswerer | null): Readonly<{
+        kind: "answered";
+        record: ApprovalRecord;
+    }> | ApprovalRefusal;
+    /** Policy changes are attributed; an Agent can never enable its own writes. */
+    setAutoApprove(input: AutoApproveInput, setter: ApprovalRuleSetter | null): Readonly<{
+        kind: "updated";
+        rule: AutoApproveInput;
+    }> | ApprovalRefusal;
+    /**
+     * Team: a rule for one Agent and one module needs live use of that family
+     * and agent.manage on that Agent; any wider rule is the owner's alone.
+     * Oyster and Local rules are owner-only.
+     */
+    private canManagePolicy;
+    /** Pure policy selection: no record, claim, dispatch, grant widening or containment choice. */
+    selectAutoApprove(query: AutoApproveQuery): boolean;
+    /** Expire one bounded home-local quantum without a member read or an approval. */
+    expirePending(): void;
+    /** Earliest native wake for waiting or unfinished effects; no claim or dispatch. */
+    nextWakeAt(): number | null;
+    /** Bounded approved work for the native owner; selection never claims or dispatches. */
+    pendingApplications(): readonly string[];
+    /** Bounded, home-local terminal notices for the native owner's work loop. */
+    pendingHandoffs(): readonly string[];
+    /**
+     * Retry only the ordinary message, with the same recipient-side idempotency key.
+     * A send rejection leaves the intent pending; it never reopens effect execution.
+     * The host must return the real Session acceptance, not a success-shaped placeholder.
+     */
+    handoff(recordId: string, send: (notice: ApprovalResultNotice) => Promise<Readonly<{
+        commandId: string;
+    }>>): Promise<ApprovalHandoffResult>;
+    /**
+     * The home's work loop: only a durable approved record claims the existing
+     * host operation, and its result always reaches a waiting Agent as a message.
+     */
+    apply(recordId: string, host: ApprovalApplyHost): Promise<ApprovalApplyResult>;
+    /**
+     * Apply the caller's own just-staged policy approval inside its live tool
+     * call; that call's result is the outcome, so no later message is owed.
+     */
+    applyInline(recordId: string, host: ApprovalApplyHost): Promise<ApprovalApplyResult>;
+    private run;
+    private finishDenied;
+    /** Native host boot only: orphaned durable claims must never be redispatched. */
+    recoverClaims(): readonly ApprovalRecord[];
+    private payload;
+    private save;
+    /** Read a record from this home only; the maintained decoder owns stored JSON. */
+    get(recordId: string): ApprovalRecord | null;
+}