@happyvertical/smrt-approvals 0.0.0-stage → 0.55.11

package/dist/models/ApprovalEvent.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ApprovalEvent: the append-only ledger of an approval request.
+ *
+ * Events are the source of truth for who did what: every transition inserts
+ * exactly one event in the same transaction as its guarded UPDATE. The
+ * generated surface is read-only, `save()` only ever inserts, and `delete()`
+ * is refused. `(requestId, sequence)` is unique (one event per request
+ * version) and `(requestId, voteKey)` is unique (one decision per actor).
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type ApprovalEventType, type ApprovalPrincipalType } from '../types.js';
+/** Constructor options for {@link ApprovalEvent}. */
+export interface ApprovalEventOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    requestId?: string;
+    type?: ApprovalEventType;
+    actorId?: string;
+    actorType?: ApprovalPrincipalType;
+    reason?: string;
+    subjectRevisionHash?: string;
+    sequence?: number;
+    voteKey?: string | null;
+    occurredAt?: Date | null;
+}
+/** One immutable entry in an approval request's history. */
+export declare class ApprovalEvent extends SmrtObject {
+    /** Owning tenant; always the request's tenant. */
+    tenantId: string;
+    /**
+     * The request this event belongs to. DuckDB executes an UPDATE of an
+     * indexed column on a referenced row as delete plus insert, so a physical
+     * FK there would refuse every transition of a request that has events;
+     * the constraint is physical on PostgreSQL and SQLite only. Requests are
+     * never deleted, so no engine can orphan an event.
+     */
+    requestId: string;
+    /** What happened. */
+    type: ApprovalEventType;
+    /** Principal id of the actor. */
+    actorId: string;
+    /** Principal type of the actor. */
+    actorType: ApprovalPrincipalType;
+    /** Free-text reason (rejection note, cancellation reason, and so on). */
+    reason: string;
+    /** The subject revision the request was bound to when this happened. */
+    subjectRevisionHash: string;
+    /** The request `version` this event produced; unique per request. */
+    sequence: number;
+    /**
+     * The deciding actor's id on decision events, `null` otherwise; unique per
+     * request so one actor decides at most once.
+     */
+    voteKey: string | null;
+    /** When the event happened. */
+    occurredAt: Date | null;
+    constructor(options?: ApprovalEventOptions);
+    /**
+     * Append the event. An event is written once and never updated.
+     *
+     * @throws {ApprovalError} `APPROVAL_FORBIDDEN` for a persisted event.
+     */
+    save(): Promise<this>;
+    /**
+     * Refuse any insert `ApprovalService` did not mint in the same transaction
+     * as its guarded UPDATE (see `write-capability.ts`): a forged `approved`
+     * event would otherwise count toward quorum. Runs for ordinary saves and
+     * bulk creates alike.
+     *
+     * @throws {ApprovalError} `APPROVAL_FORBIDDEN`.
+     */
+    protected validateBeforeSave(): Promise<void>;
+    private assertInsertAllowed;
+    /**
+     * Events are append-only.
+     *
+     * @throws {ApprovalError} always.
+     */
+    delete(): Promise<void>;
+}
+//# sourceMappingURL=ApprovalEvent.d.ts.map

package/dist/models/ApprovalEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApprovalEvent.d.ts","sourceRoot":"","sources":["../../src/models/ApprovalEvent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAGL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AAIrB,qDAAqD;AACrD,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC1B;AAED,4DAA4D;AAC5D,qBAuBa,aAAc,SAAQ,UAAU;IAC3C,kDAAkD;IAElD,QAAQ,EAAE,MAAM,CAAM;IAEtB;;;;;;OAMG;IAQH,SAAS,EAAE,MAAM,CAAM;IAEvB,qBAAqB;IAErB,IAAI,EAAE,iBAAiB,CAAa;IAEpC,iCAAiC;IAEjC,OAAO,EAAE,MAAM,CAAM;IAErB,mCAAmC;IAEnC,SAAS,EAAE,qBAAqB,CAAW;IAE3C,yEAAyE;IAEzE,MAAM,EAAE,MAAM,CAAM;IAEpB,wEAAwE;IAExE,mBAAmB,EAAE,MAAM,CAAM;IAEjC,qEAAqE;IAErE,QAAQ,EAAE,MAAM,CAAK;IAErB;;;OAGG;IAEH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE9B,+BAA+B;IAE/B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;gBAEnB,OAAO,GAAE,oBAAyB;IAgB9C;;;;OAIG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAapC;;;;;;;OAOG;cACsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5D,OAAO,CAAC,mBAAmB;IAQ3B;;;;OAIG;IACY,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC"}

package/dist/models/ApprovalPolicy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ApprovalPolicy: a tenant's tightening of one approval kind.
+ *
+ * A row may raise the quorum, shorten the expiry, or add one required
+ * permission; it can never loosen the kind's package defaults. Writes go
+ * through `ApprovalService.setPolicy`, which refuses loosening, and
+ * `effectiveRules` clamps any stored row when a request is made. A policy
+ * applies to requests made after it is written; existing requests keep the
+ * rules fixed at request time.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+/** Constructor options for {@link ApprovalPolicy}. */
+export interface ApprovalPolicyOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    kind?: string;
+    requiredApprovals?: number;
+    ttlMs?: number;
+    requiredPermission?: string;
+    updatedBy?: string;
+}
+/** Tenant-level tightening of an approval kind. One row per tenant and kind. */
+export declare class ApprovalPolicy extends SmrtObject {
+    /** Owning tenant. */
+    tenantId: string;
+    /** Approval kind key this row tightens. */
+    kind: string;
+    /** Raised quorum; `0` inherits the kind default. */
+    requiredApprovals: number;
+    /** Shortened lifetime in milliseconds; `0` inherits the kind default. */
+    ttlMs: number;
+    /** Extra permission slug a decider must hold; empty for none. */
+    requiredPermission: string;
+    /** Principal id that last wrote the row. */
+    updatedBy: string;
+    constructor(options?: ApprovalPolicyOptions);
+    /**
+     * Validate against the registered kind, then persist. A row for an unknown
+     * kind, or one that would loosen the kind, is refused.
+     *
+     * @throws {ApprovalError} `APPROVAL_KIND_UNKNOWN`,
+     *   `APPROVAL_POLICY_LOOSENS`, or `APPROVAL_INVALID`.
+     */
+    save(): Promise<this>;
+}
+//# sourceMappingURL=ApprovalPolicy.d.ts.map

package/dist/models/ApprovalPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApprovalPolicy.d.ts","sourceRoot":"","sources":["../../src/models/ApprovalPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAIlC,sDAAsD;AACtD,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gFAAgF;AAChF,qBAca,cAAe,SAAQ,UAAU;IAC5C,qBAAqB;IAErB,QAAQ,EAAE,MAAM,CAAM;IAEtB,2CAA2C;IAE3C,IAAI,EAAE,MAAM,CAAM;IAElB,oDAAoD;IAEpD,iBAAiB,EAAE,MAAM,CAAK;IAE9B,yEAAyE;IAEzE,KAAK,EAAE,MAAM,CAAK;IAElB,iEAAiE;IAEjE,kBAAkB,EAAE,MAAM,CAAM;IAEhC,4CAA4C;IAE5C,SAAS,EAAE,MAAM,CAAM;gBAEX,OAAO,GAAE,qBAA0B;IAY/C;;;;;;OAMG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAWrC"}

package/dist/models/ApprovalRequest.d.ts

@@ -0,0 +1,118 @@
+/**
+ * ApprovalRequest: one decision gate on one revision of one subject.
+ *
+ * The row is the authority for the decision; a consumer's own status column
+ * is a projection it writes in the same transaction as `consume`. Every
+ * lifecycle field is changed only by `ApprovalService` through one guarded
+ * conditional UPDATE, so the generated surface is read-only and a plain
+ * `save()` of a loaded request is refused.
+ *
+ * @packageDocumentation
+ */
+import { SmrtObject, type SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { type ApprovalPrincipalType, type ApprovalStatus } from '../types.js';
+/** Constructor options for {@link ApprovalRequest}. */
+export interface ApprovalRequestOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    kind?: string;
+    subjectType?: string;
+    subjectId?: string;
+    subjectRevisionHash?: string;
+    requestKey?: string;
+    requestedBy?: string;
+    requestedByType?: ApprovalPrincipalType;
+    summary?: string;
+    status?: ApprovalStatus;
+    requiredApprovals?: number;
+    approvalCount?: number;
+    requiredPermissions?: string;
+    version?: number;
+    expiresAt?: Date | null;
+    decidedAt?: Date | null;
+    consumedAt?: Date | null;
+    consumedBy?: string;
+}
+/**
+ * A request for approval of one subject revision.
+ *
+ * Status moves `pending` to `approved`, `rejected`, `changes_requested`,
+ * `cancelled`, or `expired`; an approved request is consumed once
+ * (`consumedAt` set, status stays `approved`) or expires unconsumed.
+ */
+export declare class ApprovalRequest extends SmrtObject {
+    /** Owning tenant. Every read and transition is pinned to it. */
+    tenantId: string;
+    /** Approval kind key, e.g. `social.post.publish`. */
+    kind: string;
+    /** Qualified subject class, e.g. `@happyvertical/smrt-social:SocialPost`. */
+    subjectType: string;
+    /** Subject id. Bare string: the subject table is polymorphic. */
+    subjectId: string;
+    /**
+     * Hash of the exact subject revision being approved. `consume` must
+     * present the same hash, so an approval never transfers to changed content.
+     */
+    subjectRevisionHash: string;
+    /** Idempotency key, unique per tenant. A replay returns the same request. */
+    requestKey: string;
+    /** Principal id of the requester. The requester can never decide. */
+    requestedBy: string;
+    /** Principal type of the requester (`human`, `agent`, or `service`). */
+    requestedByType: ApprovalPrincipalType;
+    /** Short human-readable description shown to deciders. */
+    summary: string;
+    /** Lifecycle status. Changed only by guarded transitions. */
+    status: ApprovalStatus;
+    /** Distinct approvers needed, fixed when the request is made. */
+    requiredApprovals: number;
+    /** Distinct approvals recorded so far. */
+    approvalCount: number;
+    /**
+     * JSON array of permission slugs a decider must hold, fixed at request
+     * time. Read it through {@link getRequiredPermissions}.
+     */
+    requiredPermissions: string;
+    /** Transition counter; every guarded UPDATE requires and bumps it. */
+    version: number;
+    /** After this instant the request can no longer be decided or consumed. */
+    expiresAt: Date | null;
+    /** When the request reached a terminal decision. */
+    decidedAt: Date | null;
+    /** When the approval was consumed (single use). */
+    consumedAt: Date | null;
+    /** Principal id that consumed the approval. */
+    consumedBy: string;
+    constructor(options?: ApprovalRequestOptions);
+    /** The permission slugs a decider must hold (never throws; bad JSON = none valid). */
+    getRequiredPermissions(): string[];
+    /** Store the permission slugs a decider must hold. */
+    setRequiredPermissions(slugs: readonly string[]): void;
+    /** The expiry as epoch milliseconds (`NaN` when unset or unparseable). */
+    expiresAtMs(): number;
+    /** True when the approval was consumed. */
+    isConsumed(): boolean;
+    /**
+     * Refuse any insert `ApprovalService` did not mint (see
+     * `write-capability.ts`), and any minted insert that does not start in the
+     * initial state. Runs for ordinary saves and bulk creates alike (core
+     * wraps an error thrown here; `save()` checks first so callers see it).
+     *
+     * @throws {ApprovalError} `APPROVAL_FORBIDDEN`.
+     */
+    protected validateBeforeSave(): Promise<void>;
+    private assertInsertAllowed;
+    /**
+     * Insert a new request. A loaded request is never re-saved: every later
+     * change is a guarded transition in `ApprovalService`.
+     *
+     * @throws {ApprovalError} `APPROVAL_FORBIDDEN` for a persisted request.
+     */
+    save(): Promise<this>;
+    /**
+     * Requests are durable records of a decision.
+     *
+     * @throws {ApprovalError} always.
+     */
+    delete(): Promise<void>;
+}
+//# sourceMappingURL=ApprovalRequest.d.ts.map

package/dist/models/ApprovalRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApprovalRequest.d.ts","sourceRoot":"","sources":["../../src/models/ApprovalRequest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,UAAU,EACV,KAAK,iBAAiB,EAEvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AAGrB,uDAAuD;AACvD,MAAM,WAAW,sBAAuB,SAAQ,iBAAiB;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAsBa,eAAgB,SAAQ,UAAU;IAC7C,gEAAgE;IAEhE,QAAQ,EAAE,MAAM,CAAM;IAEtB,qDAAqD;IAErD,IAAI,EAAE,MAAM,CAAM;IAElB,6EAA6E;IAE7E,WAAW,EAAE,MAAM,CAAM;IAEzB,iEAAiE;IAEjE,SAAS,EAAE,MAAM,CAAM;IAEvB;;;OAGG;IAEH,mBAAmB,EAAE,MAAM,CAAM;IAEjC,6EAA6E;IAE7E,UAAU,EAAE,MAAM,CAAM;IAExB,qEAAqE;IAErE,WAAW,EAAE,MAAM,CAAM;IAEzB,wEAAwE;IAExE,eAAe,EAAE,qBAAqB,CAAW;IAEjD,0DAA0D;IAE1D,OAAO,EAAE,MAAM,CAAM;IAErB,6DAA6D;IAE7D,MAAM,EAAE,cAAc,CAAa;IAEnC,iEAAiE;IAEjE,iBAAiB,EAAE,MAAM,CAAK;IAE9B,0CAA0C;IAE1C,aAAa,EAAE,MAAM,CAAK;IAE1B;;;OAGG;IAEH,mBAAmB,EAAE,MAAM,CAAQ;IAEnC,sEAAsE;IAEtE,OAAO,EAAE,MAAM,CAAK;IAEpB,2EAA2E;IAE3E,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B,oDAAoD;IAEpD,SAAS,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE9B,mDAAmD;IAEnD,UAAU,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE/B,+CAA+C;IAE/C,UAAU,EAAE,MAAM,CAAM;gBAEZ,OAAO,GAAE,sBAA2B;IA8BhD,sFAAsF;IACtF,sBAAsB,IAAI,MAAM,EAAE;IAWlC,sDAAsD;IACtD,sBAAsB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAItD,0EAA0E;IAC1E,WAAW,IAAI,MAAM;IASrB,2CAA2C;IAC3C,UAAU,IAAI,OAAO;IAIrB;;;;;;;OAOG;cACsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5D,OAAO,CAAC,mBAAmB;IAuB3B;;;;;OAKG;IACY,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAYpC;;;;OAIG;IACY,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAMvC"}

package/dist/permissions.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Permission slugs contributed by `@happyvertical/smrt-approvals` to the
+ * runtime permission catalog. Deciding a request is gated by the per-kind
+ * slug a package passes to `defineApprovalKind`; these slugs cover the
+ * package-wide operations.
+ *
+ * @packageDocumentation
+ */
+import { type PermissionDefinition } from '@happyvertical/smrt-users';
+/** Cancel a pending request someone else made. */
+export declare const CANCEL_ANY_APPROVAL_PERMISSION = "approvals.cancel-any";
+/** Write tenant approval policy rows (tighten-only). */
+export declare const MANAGE_APPROVAL_POLICY_PERMISSION = "approvals.manage-policy";
+/** Catalog definitions for the package-wide slugs. */
+export declare const APPROVAL_PERMISSION_DEFINITIONS: PermissionDefinition[];
+/** Register the package slugs (returns an unregister function for tests). */
+export declare function registerApprovalPermissions(): () => void;
+/** Register the package slugs once per process (package entry side effect). */
+export declare function ensureApprovalPermissionsRegistered(): void;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAEnC,kDAAkD;AAClD,eAAO,MAAM,8BAA8B,yBAAyB,CAAC;AAErE,wDAAwD;AACxD,eAAO,MAAM,iCAAiC,4BAA4B,CAAC;AAE3E,sDAAsD;AACtD,eAAO,MAAM,+BAA+B,EAAE,oBAAoB,EAejE,CAAC;AAIF,6EAA6E;AAC7E,wBAAgB,2BAA2B,IAAI,MAAM,IAAI,CAExD;AAED,+EAA+E;AAC/E,wBAAgB,mCAAmC,IAAI,IAAI,CAI1D"}

package/dist/service.d.ts

@@ -0,0 +1,203 @@
+/**
+ * ApprovalService: the only write path for approval requests.
+ *
+ * Every transition is ONE guarded conditional `UPDATE ... WHERE id AND
+ * tenant_id AND status AND version AND expiry ... RETURNING version` plus
+ * one {@link ApprovalEvent} insert, in the same database transaction (the
+ * `CliAuthRequestCollection.approvePendingRequest` and
+ * `CommissionPayoutService.transitionPayoutForSource` shape):
+ *
+ * - The guarded UPDATE is the arbiter. Two concurrent transitions of one
+ *   request both read version `v`; only one UPDATE can match `version = v`.
+ *   The loser matches zero rows, writes nothing, and retries from a fresh
+ *   read, where it sees the winner's state and is refused cleanly
+ *   (`not_pending`, `already_decided`, `already_consumed`).
+ * - PostgreSQL runs each transaction on its own pooled connection; the
+ *   UPDATE's row lock serializes writers and READ COMMITTED re-evaluates the
+ *   predicate after the winner commits. On embedded engines (SQLite,
+ *   DuckDB) each transaction runs through core's embedded write queue
+ *   (`withEmbeddedWriteTransaction`), which takes the queue before the
+ *   connection lock and serializes writers per database; the predicate
+ *   still decides.
+ * - Every statement names the tenant explicitly and the work runs inside
+ *   `withTenant(principal.tenantId)`, so tenancy interceptors and the raw
+ *   predicate both pin the row; a cross-tenant id is `not_found`.
+ * - Events are inserted through a collection bound to the transaction
+ *   database (the tx-bound collection pattern), so a failed insert rolls
+ *   the UPDATE back.
+ *
+ * @packageDocumentation
+ */
+import type { DatabaseInterface } from '@happyvertical/sql';
+import { type ApprovalPolicyRules } from './kinds.js';
+import type { ApprovalEvent } from './models/ApprovalEvent.js';
+import type { ApprovalPolicy } from './models/ApprovalPolicy.js';
+import type { ApprovalRequest } from './models/ApprovalRequest.js';
+import { type ApprovalDecision, type ApprovalKind, type ApprovalPrincipal, type ApprovalTransitionResult } from './types.js';
+/** Options for {@link ApprovalService}. */
+export interface ApprovalServiceOptions {
+    /** The database every transition runs against. Must support transactions. */
+    db: DatabaseInterface;
+    /** Clock override for deterministic tests. */
+    now?: () => Date;
+    /** Attempts before a contended transition is refused. Default 8. */
+    maxAttempts?: number;
+}
+/** Input for {@link ApprovalService.requestApproval}. */
+export interface RequestApprovalInput {
+    /** A kind registered with `defineApprovalKind` (or its key). */
+    kind: ApprovalKind | string;
+    /** The subject's id. */
+    subjectId: string;
+    /** Hash of the exact subject revision to approve. */
+    subjectRevisionHash: string;
+    /**
+     * Idempotency key, unique per tenant. A replay with the same subject and
+     * revision returns the existing request as `already_applied`; a replay with
+     * different content is refused `request_key_conflict`. Default: random.
+     */
+    requestKey?: string;
+    /** Short description shown to deciders. */
+    summary?: string;
+}
+/** Input for {@link ApprovalService.decide}. */
+export interface DecideInput {
+    decision: ApprovalDecision;
+    /** Required for `reject` and `request_changes`. */
+    reason?: string;
+}
+/** Options for {@link ApprovalService.consume}. */
+export interface ConsumeOptions {
+    /**
+     * Run inside the caller's open transaction (a `db.transaction()` callback
+     * handle) so the consumer's own write commits or rolls back together with
+     * the consumption. The caller owns the transaction. On embedded engines
+     * (SQLite, DuckDB, libsql) the handle must come from
+     * `withEmbeddedWriteTransaction(db, isEmbeddedDatabase(db), fn)` or
+     * `SmrtObject.withTransaction()` so it holds core's embedded write queue;
+     * a raw `db.transaction()` handle can deadlock against concurrent saves.
+     */
+    transaction?: DatabaseInterface;
+}
+/** Result type of every transition. */
+export type ApprovalResult = ApprovalTransitionResult<ApprovalRequest>;
+/**
+ * The decision gate. Construct it over the application's database; it binds
+ * its own collections per call and per transaction.
+ */
+export declare class ApprovalService {
+    private readonly db;
+    private readonly clock;
+    private readonly maxAttempts;
+    constructor(options: ApprovalServiceOptions);
+    /** One request in the principal's tenant, or `null`. */
+    getRequest(principal: ApprovalPrincipal, requestId: string): Promise<ApprovalRequest | null>;
+    /** A request's events in order, in the principal's tenant. */
+    listEvents(principal: ApprovalPrincipal, requestId: string): Promise<ApprovalEvent[]>;
+    /**
+     * Open a request for approval of one subject revision. Any principal type
+     * may request. The quorum, expiry, and required permissions are fixed now
+     * from the kind's defaults tightened by the tenant's policy.
+     */
+    requestApproval(principal: ApprovalPrincipal, input: RequestApprovalInput): Promise<ApprovalResult>;
+    /**
+     * Record a decision. Only a `human` principal of the request's tenant who
+     * is not the requester and holds every required permission may decide,
+     * once, while the request is pending and unexpired. `approve` counts
+     * toward the quorum of distinct approvers; `reject` and `request_changes`
+     * end the request.
+     */
+    decide(principal: ApprovalPrincipal, requestId: string, input: DecideInput): Promise<ApprovalResult>;
+    /**
+     * Cancel a pending request. The requester may cancel their own request;
+     * anyone else needs `approvals.cancel-any`.
+     */
+    cancel(principal: ApprovalPrincipal, requestId: string, input?: {
+        reason?: string;
+    }): Promise<ApprovalResult>;
+    /**
+     * Mark one request expired: a pending request, or an approved one that
+     * was never consumed, whose expiry has passed. Needs no permission (it
+     * only records what time already decided), so a job may call it.
+     */
+    expire(principal: ApprovalPrincipal, requestId: string): Promise<ApprovalResult>;
+    /**
+     * Expire every due request in the principal's tenant: pending requests
+     * and unconsumed approvals past their deadline, oldest expiry first, at
+     * most `limit`. Returns the ids this call expired.
+     */
+    expireDue(principal: ApprovalPrincipal, options?: {
+        limit?: number;
+    }): Promise<string[]>;
+    /**
+     * Consume an approval exactly once. The presented hash must equal the
+     * revision that was approved; the request must be approved, unconsumed,
+     * and unexpired. Any principal type of the tenant may consume (the
+     * consumer's own service is the executor). Pass `options.transaction` to
+     * make the consumption part of the consumer's own transaction.
+     */
+    consume(principal: ApprovalPrincipal, requestId: string, subjectRevisionHash: string, options?: ConsumeOptions): Promise<ApprovalResult>;
+    /**
+     * Write the tenant's tightening of a kind. Needs
+     * `approvals.manage-policy`; a rule that would loosen the kind's defaults
+     * throws `APPROVAL_POLICY_LOOSENS`. `0`/`''` clear a rule back to the
+     * default. Applies to requests made afterwards.
+     */
+    setPolicy(principal: ApprovalPrincipal, kindKey: ApprovalKind | string, rules: ApprovalPolicyRules): Promise<ApprovalPolicy>;
+    /** The effective rules a new request of `kind` would get in the tenant. */
+    rulesFor(principal: ApprovalPrincipal, kindKey: ApprovalKind | string): Promise<import("./types.js").EffectiveApprovalRules>;
+    /**
+     * Run a guarded transition with retry. `body` runs inside a transaction
+     * on a fresh read of the request and returns `retry` when its guarded
+     * UPDATE matched no row (a concurrent transition won).
+     */
+    private transition;
+    /** True when an active tenant context names a different tenant. */
+    private contextMismatch;
+    /** The refusal returned when {@link contextMismatch} holds. */
+    private static mismatchResult;
+    /** Pin the work to the principal's tenant; refuse a conflicting context. */
+    private inTenant;
+    /**
+     * Run `fn` in a transaction through core's embedded write queue.
+     *
+     * On embedded engines (SQLite, DuckDB, libsql) the transaction takes the
+     * queue for its database BEFORE the adapter's connection lock, and the
+     * model writes inside it (event inserts, change-feed appends) re-enter that
+     * hold. Taking the connection lock first deadlocks against an unrelated
+     * save that holds the queue and then opens its own write transaction, and
+     * lets other root writes land inside this BEGIN..COMMIT. The queue also
+     * serializes these transactions per database in-process, which is what
+     * the former per-handle promise chain did, so that chain is gone.
+     * PostgreSQL is not queued: each transaction has its own pooled
+     * connection and the guarded UPDATE's row lock arbitrates.
+     */
+    private runTransaction;
+    /** A collection bound to a transaction database. */
+    private txCollection;
+    private loadRequest;
+    private loadPolicy;
+    /**
+     * Every slug a decider must hold now: the slugs fixed at request time
+     * plus the kind's and the tenant policy's current ones (tightening only:
+     * a later policy can add a slug, never remove one).
+     */
+    private requiredPermissionsFor;
+    private appendEvent;
+    /**
+     * Defence in depth for `consume`: the request row says `approved`, so the
+     * ledger must agree. It needs the `created` event at sequence 1, no
+     * terminal event, and approvals from at least `requiredApprovals` distinct
+     * human actors other than the requester. Catches a status written around
+     * the service (raw SQL); model-layer inserts are already capability-gated.
+     */
+    private ledgerBacksApproval;
+    /**
+     * The guarded UPDATE bypasses save hooks, so record the change-feed entry
+     * the save path would have written. Best effort, like the save path.
+     */
+    private recordChange;
+    /** Re-read the request after commit (ids only cross the boundary). */
+    private toResult;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAaH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,EACL,KAAK,mBAAmB,EAKzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAKnE,OAAO,EAEL,KAAK,gBAAgB,EAGrB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EAGtB,KAAK,wBAAwB,EAC9B,MAAM,YAAY,CAAC;AAmCpB,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,EAAE,EAAE,iBAAiB,CAAC;IACtB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,IAAI,EAAE,YAAY,GAAG,MAAM,CAAC;IAC5B,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,wBAAwB,CAAC,eAAe,CAAC,CAAC;AAmGvE;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAA6B;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,OAAO,EAAE,sBAAsB;IAyB3C,wDAAwD;IAClD,UAAU,CACd,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQlC,8DAA8D;IACxD,UAAU,CACd,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,EAAE,CAAC;IAiB3B;;;;OAIG;IACG,eAAe,CACnB,SAAS,EAAE,iBAAiB,EAC5B,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,cAAc,CAAC;IA4G1B;;;;;;OAMG;IACG,MAAM,CACV,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,cAAc,CAAC;IA+I1B;;;OAGG;IACG,MAAM,CACV,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9B,OAAO,CAAC,cAAc,CAAC;IAgE1B;;;;OAIG;IACG,MAAM,CACV,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC;IAgE1B;;;;OAIG;IACG,SAAS,CACb,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,MAAM,EAAE,CAAC;IA4BpB;;;;;;OAMG;IACG,OAAO,CACX,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,EACjB,mBAAmB,EAAE,MAAM,EAC3B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC;IAmF1B;;;;;OAKG;IACG,SAAS,CACb,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,YAAY,GAAG,MAAM,EAC9B,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,cAAc,CAAC;IAoE1B,2EAA2E;IACrE,QAAQ,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,YAAY,GAAG,MAAM;IAiB3E;;;;OAIG;YACW,UAAU;IAgExB,mEAAmE;IACnE,OAAO,CAAC,eAAe;IASvB,+DAA+D;IAC/D,OAAO,CAAC,MAAM,CAAC,cAAc;IAY7B,4EAA4E;YAC9D,QAAQ;IAatB;;;;;;;;;;;;;OAaG;YACW,cAAc;IAU5B,oDAAoD;YACtC,YAAY;YAWZ,WAAW;YAiBX,UAAU;IAgBxB;;;;OAIG;YACW,sBAAsB;YActB,WAAW;IA+BzB;;;;;;OAMG;YACW,mBAAmB;IAgCjC;;;OAGG;YACW,YAAY;IAkB1B,sEAAsE;YACxD,QAAQ;CAmBvB"}