@portalshq/capability-interaction-orchestrator 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,248 @@
-# Temporary Holding Version
+# @portalshq/capability-interaction-orchestrator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A durable interaction lifecycle for input windows, moderated submissions, selection,
+credit-backed billing, execution handoff and replayable events. PostgreSQL owns
+admission, quotas, idempotency, credit allocations, resolutions and event ordering.
+
+## Setup
+
+Requires Node.js 22+, PostgreSQL, and the `@portalshq/monetization` entitlement schema
+in the **same database**. Apply migrations with errors stopping the transaction:
+
+```sh
+psql "$DATABASE_URL" -v ON_ERROR_STOP=1 --single-transaction \
+  -f node_modules/@portalshq/monetization/sql/001_monetization.sql \
+  -f node_modules/@portalshq/capability-interaction-orchestrator/sql/001_interaction_orchestrator_core.sql \
+  -f node_modules/@portalshq/capability-interaction-orchestrator/sql/002_durable_lifecycle.sql
+```
+
+Deploy the accompanying monetization update together with this package: both use
+ID order for grant locks while consuming the oldest matching credits first.
+The old `Stub*` exports have been removed. The executable classes now require their
+actual dependencies; no implementation silently grants a payment or host approval.
+
+## Lifecycle interface
+
+```typescript
+import { Pool } from 'pg';
+import {
+  InteractionRepository,
+  InteractionOrchestrator,
+} from '@portalshq/capability-interaction-orchestrator';
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const repository = new InteractionRepository(pool);
+const interactions = new InteractionOrchestrator(repository);
+
+const window = await interactions.windows.createWindow({
+  worldId: 'channel-123',
+  branchId: 'canonical',
+  baseCommitHash: 'current-commit',
+  conflictKey: 'story',
+  allowedInputKinds: ['custom_prompt'],
+  arbitrationPolicy: 'fifo',
+  billingPolicy: 'prepaid_credits',
+  billingTerms: {
+    tenantId: 'creator-tenant',
+    entitlementKind: 'creator-tenant:story_guide',
+    amountCredits: 1,
+    amountCents: 100,
+    currency: 'USD',
+    // Set sessionId only when the actual entitlement scope names a session.
+  },
+  maxSubmissionsPerUser: 1,
+  maxSelectedInputs: 5,
+  opensAt: new Date().toISOString(),
+  closesAt: null,
+  contentRating: 'E',
+});
+await interactions.windows.openWindow(window.id);
+
+const submission = await interactions.submissions.submitIntent({
+  windowId: window.id,
+  actorId: 'authenticated-consumer-id',
+  idempotencyKey: 'request-id-kept-across-retries',
+  kind: 'custom_prompt',
+  payload: { prompt: 'Explore the old lighthouse' },
+});
+if (submission.status !== 'eligible') {
+  // Rejected inputs and inputs awaiting human review do not enter selection.
+  console.log(submission.status);
+}
+```
+
+`actorId` must come from authenticated application identity. Authorize the caller
+against the window's world before exposing submission, cancellation, review,
+host-selection, refund or event methods over a network. This package is an internal
+module; it does not authenticate HTTP requests. Window configuration, billing terms,
+policy configuration and moderation context come from trusted application code.
+Submission payloads and app metadata cannot set prices, rank or host authority.
+
+The server reloads prices for `billing.quote(window, actorId)`; the quote is an
+informational display, not a payment approval. All paid policies settle **credits
+already granted by monetization**. Fiat checkout, Stripe authorization and monetary
+refunds belong to monetization's purchase lifecycle. No synthetic Stripe holds are
+created here.
+
+Input JSON is limited to 64 KiB and 32 nesting levels; timestamps use ISO UTC with
+`Z`. Prompts/messages require their text field; votes require an option or target ID
+(and both must agree when present); mutations require target IDs and a parameter
+object; object creation requires `payload.object`; branch creation requires a name.
+Configure `allowedInputKinds` to operations implemented by your execution adapter.
+
+### Resolve, execute, commit
+
+```typescript
+// For finite windows, closeWindow first. An always-open queue can resolve directly.
+const resolution = await interactions.resolveWindow(window.id, {
+  idempotencyKey: 'generation-request-id',
+});
+const executable = await interactions.prepareExecution(resolution.id);
+// Pass executable to your execution adapter to generate a private preview/artifact.
+// Keep proposed world changes private until output moderation and commit succeed.
+// Then call commitResolution(resolution.id, proposedOutput, resultingCommitHash).
+```
+
+`resolveWindow` persists selection and losing-input refunds atomically. Selection
+has a window-scoped retry key; reusing it with a different host selection fails.
+Only one selected/executing resolution may exist per window. `prepareExecution`
+checks backing grants and captures selection-dependent credits before execution.
+`commitResolution(id, output, hash)` moderates the complete output, captures deferred
+publication credits and records fulfillment and events together. A non-allow output
+fails the resolution and releases/refunds its credits. For parallel branches, supply
+`{ [selectedSubmissionId]: branchCommitHash }` instead of one hash; the canonical
+head stays unchanged. Output and commit targets must match on a retry.
+
+The owned execution adapter must enforce base-commit conflicts against its world
+store. A hash supplied to this module identifies a private proposed artifact;
+publication happens only after a committed resolution. PostgreSQL transactions do
+not make an external provider call or world-store write atomic.
+
+`failResolution(id, reason)` refunds selected work and records failure. Use it after
+an execution failure or expired/revoked hold; retrying a failed resolution requires
+a new submission. `cancelWindow(id)` cancels pending inputs and refunds their credits
+in one transaction, refusing to interrupt an active resolution.
+
+## Selection policies
+
+| Policy | Behavior |
+| --- | --- |
+| `fifo` | Admission order, with ID as the final deterministic tie-break |
+| `first_accepted` | The first eligible input |
+| `plurality` | Distinct actors per option/target, descending vote count, then admission order; selects one representative per winning target |
+| `ranked` | Trusted `arbitrationPolicyConfig.priorities[submissionId]`, then admission order; ignores payload priority |
+| `batch` | Admission order, combining nonoverlapping `targetEntityIds` up to capacity |
+| `parallel_branches` | Admission order up to capacity, one stable branch destination per selected input |
+| `host_selection` | Explicit `selectedSubmissionIds` passed to `resolveWindow`; rejects unknown, duplicate or excessive IDs |
+
+All policies respect `maxSelectedInputs`. Custom policies must partition the eligible
+inputs exactly once into selected and rejected IDs. The arbitration engine is a
+pure selection module; its `resolutionSequence: 0` is an unpersisted proposal.
+The orchestrator allocates the actual monotonic sequence under the window lock.
+
+For always-open FIFO/parallel queues, overflow stays eligible for the next generation
+and is recorded in `appMetadata.deferredSubmissionIds`. Finite-window losers are
+marked `not_selected` and refunded. Prompt/message/vote inputs can follow a moving
+queue head; state-changing inputs with an old base must be cancelled and resubmitted
+after application revalidation. Active per-user quota counts pending, eligible,
+selected and executing inputs; completed/rejected/cancelled inputs free that quota.
+Scheduled windows can coexist, but opening two windows with the same world, branch
+and conflict key fails.
+
+## Moderation
+
+`ModerationGateway` checks every nested string in JSON input/output. Its defaults
+provide configurable term rules, Unicode normalization, word edges, input length
+200 and output length 32,000. E blocks mild/strong profanity, explicit terms and
+graphic violence terms; T permits mild profanity; T+ permits strong profanity and
+graphic violence; M permits these categories. Blocked/prohibited terms apply at
+every rating. These are text rules, not semantic or image/video classification.
+Install application/model validators for contextual content decisions and non-text
+media inspection. Version your configuration with `moderationPolicyVersion`.
+
+Custom validators cannot bypass the built-in rules. Missing `validateOutput` falls
+back to `validate` with the complete output in a synthetic submission. Validator
+exceptions and malformed decisions stop qualification. `review` and `transform`
+remain in `moderating`; only an explicit trusted
+`submissions.reviewSubmission(id, 'allow' | 'reject', reasons)` completes them.
+Transforms are never silently applied. `contextFor(window)` injects application
+world rules; each request uses its own rating context.
+
+## Billing behavior
+
+| Policy | Admission | Selection/execution | Commit |
+| --- | --- | --- | --- |
+| `free` | Zero-credit reservation | Verify lifecycle | No charge |
+| `prepaid_credits` | Consume credits | Validate backing grants | Fulfill |
+| `pay_to_generate` | Consume credits | Validate backing grants | Fulfill |
+| `pay_for_guaranteed_slot` | Claim capacity and consume credits | Guaranteed FIFO/parallel selection | Fulfill |
+| `capture_if_selected` | Deduct a credit hold from spendable balance | Capture selected holds; release losers | Fulfill |
+| `pay_to_publish` | Deduct a credit hold | Generate a private preview | Capture only on allowed output |
+
+Guaranteed slots require FIFO or parallel selection and cannot overbook capacity.
+Reservations default to one hour; configure `reservationTtlMs` (1 second–24 hours).
+A hold expires no later than its earliest backing grant. Captured prepaid credits
+remain spent while queued. Cancellation, failed execution, non-allow output and
+finite-window loss release/refund exactly once, restoring only surviving unexpired
+original grants. A deleted/refunded purchase's grant is never recreated. Expired
+credits cannot be made spendable by an interaction refund. Deferred captures check
+expiry and revocation again at execution/publication.
+
+## Events and workers
+
+`EventPublisher` accepts `createPostgresFanoutBus(pool)` or `InMemoryFanoutBus` through
+the fanout seam. Set up `fanout_messages` as documented by
+[`capability-realtime-fanout-postgres`](../capability-realtime-fanout-postgres).
+Lifecycle writes enqueue events; call `drainOutbox()` from a worker. Publishing to
+the transport is at least once, with expiring claims and token-checked acknowledgment.
+Failed deliveries stay durable for retry. Each event has a stable ID and a
+transactionally allocated world sequence. Topics use `interaction:${worldId}`.
+
+`subscribe(worldId, afterSequence?, { signal? })` returns an async iterator. With a
+cursor it replays all later events in bounded pages; without one it starts at the
+current head. Fanout messages wake the iterator; the database remains authoritative
+for ordering and deduplication. Polling recovers missed hints. Abort, iterator return
+and exceptions release subscriptions and timers, including a read that is waiting.
+Use `String(event.sequence)` for SSE `id`; validate and authorize `Last-Event-ID`.
+`getEvents` returns at most 100 events per page. The iterator handles pagination.
+
+Run these bounded jobs with error reporting and nonoverlapping invocations:
+
+- `windows.startWindowCloser(5000)` closes due finite windows; always-open queues remain open.
+- `billing.expireReservations()` releases expired, unselected holds in batches of 100.
+- `submissions.resumeSubmission(id)` recovers a durable `received` admission after an outage. Find these through application recovery jobs or `listSubmissions(windowId, 'received')`.
+- `events.drainOutbox()` delivers a bounded outbox batch; repeat while work remains.
+
+Open scheduled windows explicitly at their scheduled time. Finish the active
+always-open queue resolution before explicitly closing its intake. Stop/await the closer,
+abort/return all event iterators, finish in-flight worker jobs and then close the
+caller-owned fanout bus and pool during shutdown. A selected/executing expired hold
+requires `failResolution`; it is never silently reassigned. Use trusted operator
+`billing.refund` for completed work; active resolutions must fail first.
+
+Repository transactions serialize admission/selection per window, world event writes
+per world, and credit mutations in grant-ID order. Keep network calls outside these
+transactions. The exported repository and `*InTransaction` methods are low-level
+integration seams; use `InteractionOrchestrator` for lifecycle operations. Retain
+outbox history for the promised replay period and monitor unpublished age, pending
+qualification age, expiring holds and failed resolutions. This package does not
+silently prune audit/replay data.
+
+## Validation and migration
+
+```sh
+npm run build --workspace=packages/monetization
+npm run build --workspace=packages/capability-interaction-orchestrator
+npm run typecheck --workspace=packages/capability-interaction-orchestrator
+npm run test:coverage --workspace=packages/capability-interaction-orchestrator
+```
+
+Tests use embedded PostgreSQL (PGlite) by default, applying real migrations. To verify
+multiple connections against a scratch PostgreSQL instance, set both
+`INTERACTION_TEST_MODE=non-production` and `INTERACTION_TEST_DATABASE_URL`. Each suite
+creates/drops only its randomly named schema. Coverage thresholds are 95% for lines,
+statements, functions and branches and are enforced in the PostgreSQL CI job.
+
+See the repository's
+[migration guide](https://github.com/portalshq/portals-cloud/blob/main/packages/capability-interaction-orchestrator/docs/bears-live-app-migration.md)
+and [advanced usage](https://github.com/portalshq/portals-cloud/blob/main/packages/capability-interaction-orchestrator/docs/advanced-usage.md).

package/dist/arbitration-engine.d.ts

@@ -0,0 +1,20 @@
+import type { ArbitrationPolicyName, InputWindow, Resolution, Submission } from "./types.js";
+export interface ArbitrationPolicy {
+    readonly name: ArbitrationPolicyName;
+    resolve(window: InputWindow, submissions: Submission[]): Resolution;
+}
+export interface IArbitrationEngine {
+    resolve(window: InputWindow, submissions: Submission[]): Promise<Resolution>;
+    registerPolicy(name: string, policy: ArbitrationPolicy): void;
+    setPolicyConfig(policyName: string, config: Record<string, unknown>): void;
+}
+/** Pure selection. Persistence and monotonic resolution sequences belong to the orchestrator. */
+export declare class ArbitrationEngine implements IArbitrationEngine {
+    private readonly policies;
+    private readonly configs;
+    constructor();
+    registerPolicy(name: string, policy: ArbitrationPolicy): void;
+    setPolicyConfig(name: string, config: Record<string, unknown>): void;
+    resolve(window: InputWindow, submissions: Submission[]): Promise<Resolution>;
+}
+//# sourceMappingURL=arbitration-engine.d.ts.map

package/dist/arbitration-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbitration-engine.d.ts","sourceRoot":"","sources":["../src/arbitration-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAkBpB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,UAAU,CAAC;CACrE;AACD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7E,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC9D,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC5E;AACD,iGAAiG;AACjG,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;;IAatE,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAS7D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAS9D,OAAO,CACX,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,UAAU,EAAE,GACxB,OAAO,CAAC,UAAU,CAAC;CAuDvB"}

package/dist/arbitration-engine.js

@@ -0,0 +1,67 @@
+import { BatchPolicy, FIFOPolicy, FirstAcceptedPolicy, HostSelectionPolicy, ParallelBranchesPolicy, PluralityPolicy, RankedPolicy, } from "./policies/index.js";
+import { integer, InteractionError, policyName, record, text, } from "./validation.js";
+/** Pure selection. Persistence and monotonic resolution sequences belong to the orchestrator. */
+export class ArbitrationEngine {
+    policies = new Map();
+    configs = new Map();
+    constructor() {
+        for (const policy of [
+            new FIFOPolicy(),
+            new FirstAcceptedPolicy(),
+            new PluralityPolicy(),
+            new RankedPolicy(),
+            new BatchPolicy(),
+            new ParallelBranchesPolicy(),
+            new HostSelectionPolicy(),
+        ])
+            this.registerPolicy(policy.name, policy);
+    }
+    registerPolicy(name, policy) {
+        policyName(name);
+        if (name !== policy.name || typeof policy.resolve !== "function")
+            throw new InteractionError("INVALID_INPUT", "Policy registration name must match policy.name");
+        this.policies.set(name, policy);
+    }
+    setPolicyConfig(name, config) {
+        if (!this.policies.has(name))
+            throw new InteractionError("INVALID_INPUT", `Unknown arbitration policy: ${name}`);
+        record(config, "policy config");
+        this.configs.set(name, structuredClone(config));
+    }
+    async resolve(window, submissions) {
+        const policy = this.policies.get(window.arbitrationPolicy);
+        if (!policy)
+            throw new InteractionError("INVALID_INPUT", `Unknown arbitration policy: ${window.arbitrationPolicy}`);
+        integer(window.maxSelectedInputs, "maxSelectedInputs");
+        if (new Set(submissions.map((s) => s.id)).size !== submissions.length ||
+            submissions.some((s) => s.windowId !== window.id ||
+                s.status !== "eligible" ||
+                !Number.isSafeInteger(s.admissionSequence) ||
+                s.admissionSequence < 1))
+            throw new InteractionError("INVALID_INPUT", "Arbitration requires distinct eligible submissions from this window");
+        const effective = {
+            ...window,
+            arbitrationPolicyConfig: {
+                ...this.configs.get(policy.name),
+                ...window.arbitrationPolicyConfig,
+            },
+        };
+        const resolution = policy.resolve(structuredClone(effective), structuredClone(submissions));
+        text(resolution.id, "resolution id");
+        text(resolution.policyVersion, "policyVersion");
+        record(resolution.appMetadata, "resolution metadata");
+        const selected = resolution.selectedSubmissionIds;
+        const rejected = resolution.rejectedSubmissionIds;
+        const all = [...selected, ...rejected];
+        if (resolution.windowId !== window.id ||
+            resolution.baseCommitHash !== window.baseCommitHash ||
+            resolution.arbitrationPolicy !== window.arbitrationPolicy ||
+            resolution.status !== "selected" ||
+            selected.length > window.maxSelectedInputs ||
+            all.length !== submissions.length ||
+            new Set(all).size !== all.length ||
+            all.some((id) => !submissions.some((s) => s.id === id)))
+            throw new InteractionError("INVALID_POLICY_RESULT", "Policy must partition submissions exactly once within capacity");
+        return resolution;
+    }
+}

package/dist/billing-controller.d.ts

@@ -0,0 +1,38 @@
+import type { InteractionRepository } from "./db/repository.js";
+import type { EntitlementReservation, InputWindow, PriceQuote, Resolution, Submission } from "./types.js";
+interface Allocation {
+    grantId: string;
+    amount: number;
+}
+export interface StoredReservation extends EntitlementReservation {
+    state: "reserved" | "captured" | "released" | "refunded";
+    allocations: Allocation[];
+}
+export interface IBillingController {
+    quote(window: InputWindow, actorId: string): Promise<PriceQuote>;
+    authorize(submission: Submission): Promise<EntitlementReservation>;
+    capture(resolution: Resolution): Promise<void>;
+    cancel(submission: Submission): Promise<void>;
+    refund(submission: Submission, reason: string): Promise<void>;
+}
+/** Credit-backed billing against monetization grants on the same PostgreSQL database.
+ * A hold deducts spendable balance once. Capture, release and refund are durable transitions.
+ */
+export declare class BillingController implements IBillingController {
+    private readonly repository;
+    constructor(repository: InteractionRepository);
+    /** Lock every allocation a lifecycle transaction will touch, in database ID order. */
+    lockReservations(r: InteractionRepository, submissionIds: string[]): Promise<void>;
+    quote(window: InputWindow, actorId: string): Promise<PriceQuote>;
+    authorize(submission: Submission): Promise<EntitlementReservation>;
+    getReservation(id: string, r?: InteractionRepository): Promise<StoredReservation | null>;
+    authorizeInTransaction(r: InteractionRepository, s: Submission, w: InputWindow): Promise<StoredReservation>;
+    capture(resolution: Resolution): Promise<void>;
+    captureInTransaction(r: InteractionRepository, s: Submission, w: InputWindow): Promise<void>;
+    cancel(submission: Submission): Promise<void>;
+    refund(submission: Submission, reason: string): Promise<void>;
+    releaseInTransaction(r: InteractionRepository, s: Submission, w: InputWindow, reason: string): Promise<void>;
+    expireReservations(limit?: number): Promise<number>;
+}
+export {};
+//# sourceMappingURL=billing-controller.d.ts.map

package/dist/billing-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing-controller.d.ts","sourceRoot":"","sources":["../src/billing-controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,KAAK,EACV,sBAAsB,EACtB,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAGpB,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,UAAU,GAAG,UAAU,CAAC;IACzD,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B;AACD,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjE,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;IACnE,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AACD;;GAEG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,qBAAqB;IAC9D,sFAAsF;IAChF,gBAAgB,CACpB,CAAC,EAAE,qBAAqB,EACxB,aAAa,EAAE,MAAM,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC;IAoBV,KAAK,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBhE,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAKlE,cAAc,CAClB,EAAE,EAAE,MAAM,EACV,CAAC,wBAAkB,GAClB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAiB9B,sBAAsB,CAC1B,CAAC,EAAE,qBAAqB,EACxB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,WAAW,GACb,OAAO,CAAC,iBAAiB,CAAC;IA+FvB,OAAO,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAkC9C,oBAAoB,CACxB,CAAC,EAAE,qBAAqB,EACxB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,WAAW,GACb,OAAO,CAAC,IAAI,CAAC;IAgDV,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB7C,MAAM,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7D,oBAAoB,CACxB,CAAC,EAAE,qBAAqB,EACxB,CAAC,EAAE,UAAU,EACb,CAAC,EAAE,WAAW,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAiDV,kBAAkB,CAAC,KAAK,SAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAkCvD"}

package/dist/billing-controller.js

@@ -0,0 +1,239 @@
+import { randomUUID } from "node:crypto";
+import { grantAppliesAt } from "@portalshq/monetization";
+import { integer, InteractionError, requireValue, text } from "./validation.js";
+/** Credit-backed billing against monetization grants on the same PostgreSQL database.
+ * A hold deducts spendable balance once. Capture, release and refund are durable transitions.
+ */
+export class BillingController {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    /** Lock every allocation a lifecycle transaction will touch, in database ID order. */
+    async lockReservations(r, submissionIds) {
+        const allocations = await r.query("SELECT allocations FROM interaction_reservations WHERE submission_id=ANY($1::text[])", [submissionIds]);
+        const ids = [
+            ...new Set(allocations.rows.flatMap((row) => row.allocations.map((allocation) => allocation.grantId))),
+        ];
+        if (ids.length)
+            await r.query("SELECT id FROM monetization_entitlements WHERE id=ANY($1::text[]) ORDER BY id FOR UPDATE", [ids]);
+    }
+    async quote(window, actorId) {
+        text(actorId, "actorId");
+        const current = requireValue(await this.repository.getWindow(window.id), "Window");
+        const terms = current.billingTerms;
+        if (current.billingPolicy !== "free" && !terms)
+            throw new InteractionError("INVALID_INPUT", "Paid window requires billingTerms");
+        return {
+            id: randomUUID(),
+            amountCents: current.billingPolicy === "free" ? 0 : terms.amountCents,
+            currency: terms?.currency ?? "USD",
+            expiresAt: new Date((await this.repository.now()) + 900000).toISOString(),
+        };
+    }
+    async authorize(submission) {
+        return this.repository.withSubmission(submission.id, async (r, s, w) => this.authorizeInTransaction(r, s, w));
+    }
+    async getReservation(id, r = this.repository) {
+        const row = (await r.query("SELECT * FROM interaction_reservations WHERE submission_id=$1", [id])).rows[0];
+        return row
+            ? {
+                id: row.id,
+                amountCredits: row.amount_credits,
+                expiresAt: new Date(row.expires_at).toISOString(),
+                state: row.state,
+                allocations: row.allocations,
+            }
+            : null;
+    }
+    async authorizeInTransaction(r, s, w) {
+        const existing = await this.getReservation(s.id, r);
+        if (existing) {
+            if (existing.state === "released" || existing.state === "refunded")
+                throw new InteractionError("INVALID_STATE", "Reservation was already released");
+            return existing;
+        }
+        if (s.status !== "awaiting_entitlement")
+            throw new InteractionError("INVALID_STATE", "Submission must pass moderation before billing");
+        const allocations = [];
+        const now = await r.now();
+        let expiresAt = now + (w.billingTerms?.reservationTtlMs ?? 3600000);
+        const terms = w.billingPolicy === "free"
+            ? undefined
+            : requireValue(w.billingTerms, "billingTerms");
+        if (terms) {
+            const site = {
+                channelId: w.worldId,
+                ...(terms.sessionId ? { sessionId: terms.sessionId } : {}),
+                ...(terms.date ? { date: terms.date } : {}),
+            };
+            const candidates = await r.query(`SELECT *, to_char(created_at AT TIME ZONE 'UTC', 'YYYY-MM-DD HH24:MI:SS.US') AS created_order
+         FROM monetization_entitlements WHERE tenant_id=$1 AND consumer_id=$2 AND kind=$3 AND remaining>0 AND (expires_at IS NULL OR expires_at>clock_timestamp()) ORDER BY id FOR UPDATE`, [terms.tenantId, s.actorId, terms.entitlementKind]);
+            const applicable = candidates.rows
+                .filter((row) => grantAppliesAt(row.scope, site))
+                .sort((a, b) => a.created_order < b.created_order
+                ? -1
+                : a.created_order > b.created_order
+                    ? 1
+                    : 0);
+            if (applicable.reduce((sum, row) => sum + Number(row.remaining), 0) <
+                terms.amountCredits)
+                throw new InteractionError("INSUFFICIENT_CREDITS", "Insufficient credits");
+            let owed = terms.amountCredits;
+            for (const row of applicable) {
+                if (!owed)
+                    break;
+                const amount = Math.min(owed, Number(row.remaining));
+                await r.query("UPDATE monetization_entitlements SET remaining=remaining-$2,updated_at=now() WHERE id=$1", [row.id, amount]);
+                allocations.push({ grantId: row.id, amount });
+                owed -= amount;
+                if (row.expires_at)
+                    expiresAt = Math.min(expiresAt, new Date(row.expires_at).getTime());
+            }
+        }
+        const state = ["capture_if_selected", "pay_to_publish"].includes(w.billingPolicy)
+            ? "reserved"
+            : "captured";
+        const reservation = {
+            id: randomUUID(),
+            state,
+            amountCredits: terms?.amountCredits ?? 0,
+            allocations,
+            expiresAt: new Date(expiresAt).toISOString(),
+        };
+        await r.query("INSERT INTO interaction_reservations(id,submission_id,state,amount_credits,allocations,expires_at) VALUES($1,$2,$3,$4,$5,$6)", [
+            reservation.id,
+            s.id,
+            state,
+            reservation.amountCredits,
+            JSON.stringify(allocations),
+            reservation.expiresAt,
+        ]);
+        await r.emit(w, "billing_authorized", {
+            submissionId: s.id,
+            reservationId: reservation.id,
+            state,
+            amountCredits: reservation.amountCredits,
+        });
+        return reservation;
+    }
+    async capture(resolution) {
+        await this.repository.transaction(async (r) => {
+            const w = requireValue(await r.getWindow(resolution.windowId, true), "Window");
+            const stored = requireValue(await r.getResolution(resolution.id), "Resolution");
+            if (stored.windowId !== w.id ||
+                !["selected", "executing", "committed"].includes(stored.status))
+                throw new InteractionError("INVALID_STATE", "Resolution cannot be captured");
+            // Pay-to-publish capture is owned by commitResolution, after output moderation.
+            if (w.billingPolicy === "pay_to_publish")
+                throw new InteractionError("OUTPUT_REQUIRED", "Use commitResolution to capture after output moderation");
+            if (stored.status === "committed")
+                return;
+            await this.lockReservations(r, stored.selectedSubmissionIds);
+            for (const id of stored.selectedSubmissionIds)
+                await this.captureInTransaction(r, requireValue(await r.getSubmission(id, true), "Submission"), w);
+        });
+    }
+    async captureInTransaction(r, s, w) {
+        const reservation = requireValue(await this.getReservation(s.id, r), "Reservation");
+        if (reservation.state !== "reserved" && reservation.state !== "captured")
+            throw new InteractionError("INVALID_STATE", "Reservation is no longer payable");
+        const now = await r.now();
+        if (reservation.state === "reserved" &&
+            Date.parse(reservation.expiresAt) <= now)
+            throw new InteractionError("RESERVATION_EXPIRED", "Credit reservation expired");
+        await this.lockReservations(r, [s.id]);
+        for (const allocation of [...reservation.allocations].sort((a, b) => a.grantId.localeCompare(b.grantId))) {
+            const grant = (await r.query("SELECT id,expires_at FROM monetization_entitlements WHERE id=$1 FOR UPDATE", [allocation.grantId])).rows[0];
+            if (!grant ||
+                (grant.expires_at && new Date(grant.expires_at).getTime() <= now))
+                throw new InteractionError("ENTITLEMENT_REVOKED", "Backing credit grant was revoked or expired");
+        }
+        if (reservation.state === "captured")
+            return;
+        await r.query("UPDATE interaction_reservations SET state='captured',updated_at=now() WHERE id=$1", [reservation.id]);
+        await r.emit(w, "billing_captured", {
+            submissionId: s.id,
+            reservationId: reservation.id,
+        });
+    }
+    async cancel(submission) {
+        await this.repository.withSubmission(submission.id, async (r, s, w) => {
+            if (s.status === "cancelled")
+                return;
+            if (![
+                "received",
+                "moderating",
+                "awaiting_entitlement",
+                "eligible",
+                "rejected",
+            ].includes(s.status))
+                throw new InteractionError("INVALID_STATE", "Cannot cancel selected or completed billing");
+            await this.releaseInTransaction(r, s, w, "cancelled");
+            await r.saveSubmission(s, "cancelled");
+        });
+    }
+    async refund(submission, reason) {
+        text(reason, "refund reason");
+        await this.repository.withSubmission(submission.id, async (r, s, w) => {
+            if (s.status === "selected" || s.status === "executing")
+                throw new InteractionError("INVALID_STATE", "Fail the active resolution before refunding");
+            await this.releaseInTransaction(r, s, w, reason);
+            if (s.status !== "refunded")
+                await r.saveSubmission(s, "refunded");
+        });
+    }
+    async releaseInTransaction(r, s, w, reason) {
+        const reservation = await this.getReservation(s.id, r);
+        if (!reservation ||
+            reservation.state === "released" ||
+            reservation.state === "refunded")
+            return;
+        // Lock grants in the same order as capture. Deleted or expired grants cannot be recreated.
+        await this.lockReservations(r, [s.id]);
+        let restored = 0;
+        for (const allocation of [...reservation.allocations].sort((a, b) => a.grantId.localeCompare(b.grantId))) {
+            const row = (await r.query("SELECT remaining,quantity,expires_at FROM monetization_entitlements WHERE id=$1 FOR UPDATE", [allocation.grantId])).rows[0];
+            if (!row ||
+                (row.expires_at &&
+                    new Date(row.expires_at).getTime() <= (await r.now())))
+                continue;
+            const amount = Math.min(allocation.amount, Number(row.quantity) - Number(row.remaining));
+            await r.query("UPDATE monetization_entitlements SET remaining=remaining+$2,updated_at=now() WHERE id=$1", [allocation.grantId, amount]);
+            restored += amount;
+        }
+        const state = reservation.state === "reserved" ? "released" : "refunded";
+        await r.query("UPDATE interaction_reservations SET state=$2,reason=$3,updated_at=now() WHERE id=$1", [reservation.id, state, reason]);
+        await r.emit(w, "billing_released", {
+            submissionId: s.id,
+            reservationId: reservation.id,
+            state,
+            restoredCredits: restored,
+            reason,
+        });
+    }
+    async expireReservations(limit = 100) {
+        integer(limit, "limit", 1, 1000);
+        const rows = await this.repository.query(`SELECT submission_id FROM interaction_reservations r JOIN submissions s ON s.id=r.submission_id
+      WHERE r.state='reserved' AND r.expires_at<=clock_timestamp() AND s.status IN ('received','moderating','awaiting_entitlement','eligible') ORDER BY r.expires_at LIMIT $1`, [limit]);
+        let expired = 0;
+        for (const row of rows.rows)
+            await this.repository.withSubmission(row.submission_id, async (r, s, w) => {
+                const reservation = await this.getReservation(s.id, r);
+                if (reservation?.state !== "reserved" ||
+                    Date.parse(reservation.expiresAt) > (await r.now()))
+                    return;
+                if (![
+                    "received",
+                    "moderating",
+                    "awaiting_entitlement",
+                    "eligible",
+                ].includes(s.status))
+                    return;
+                await this.releaseInTransaction(r, s, w, "reservation_expired");
+                await r.saveSubmission(s, "failed");
+                expired++;
+            });
+        return expired;
+    }
+}