@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/reporting/ledger/managed-postgres.d.ts

@@ -0,0 +1,231 @@
+import type { ReportingMaterialization, SyncReportingReceiptsResponse } from '../../types';
+import type { ReportingPgPool } from './postgres';
+import type { ReportingManagedDeliveryBindingV1, ReportingLedgerStore } from './types';
+import { type ReportingDestinationAuthorizationV1, type ReportingDestinationRevocationLeaseV1, type ReportingManagedDeliveryLeaseV1, type ReportingManagedDeliveryAdvertisedPoliciesV1, type ReportingManagedDeliveryStore, type ReportingReceiptBatchInputV1 } from './managed';
+/**
+ * Additive migration owned by #2944. It intentionally does not alter the Core
+ * tables so the #2943 notification/activity bridge can evolve that schema
+ * independently. Apply after REPORTING_LEDGER_MIGRATION in the same schema.
+ */
+export declare const REPORTING_MANAGED_DELIVERY_MIGRATION: string;
+export interface PostgresReportingManagedDeliveryStoreOptions {
+    /**
+     * The `automated_recovery_window_seconds` this deployment advertises.
+     *
+     * The capability is agent-wide and immutable once published, while bindings
+     * arrive over time, so validating only at startup leaves the window open:
+     * an agent advertising 60s starts clean and a 900s binding installed an hour
+     * later silently makes the published promise false until the next restart.
+     * Set here, `installBinding` refuses any Core configuration whose recovery
+     * window exceeds the advertised bound, inside the same transaction that
+     * checks binding eligibility. `createReportingManagedDeliveryRuntime` adopts
+     * its own advertised value into the store at wiring time, so setting it
+     * explicitly is only needed when bindings are installed without a runtime.
+     */
+    advertisedRecoveryWindowSeconds?: number;
+    /**
+     * The `status_retention_days` this deployment advertises.
+     *
+     * Supply it together with `evidenceRetentionDays` so the store can refuse a
+     * retention shorter than a horizon you have already promised. Pruning
+     * evidence the capability document still says is queryable is a broken
+     * promise, not a capacity optimisation.
+     */
+    statusRetentionDays?: number;
+    /**
+     * Days of managed evidence an account is still accountable for.
+     *
+     * MAX_MATERIALIZATIONS_PER_ACCOUNT and MAX_RECEIPTS_PER_CONSUMER are
+     * lifetime counts. Left unbounded they are a one-way door: a long-lived
+     * account eventually reaches them and then stops planning materializations
+     * and refuses every receipt, permanently, with no operator-visible way back
+     * — evidence is immutable, so nothing ever frees capacity.
+     *
+     * Setting this makes the caps active-scope: only evidence recorded inside
+     * the window counts against them, and `pruneExpiredEvidence` can delete what
+     * falls outside it. Choose a value at least as long as the
+     * `status_retention_days` you advertise, since that is the period you
+     * promised the metadata stays queryable. Omit it to keep the previous
+     * lifetime accounting with no pruning.
+     */
+    evidenceRetentionDays?: number;
+}
+export declare class PostgresReportingManagedDeliveryStore implements ReportingManagedDeliveryStore {
+    private readonly pool;
+    private readonly evidenceRetentionDays;
+    private readonly statusRetentionDays;
+    private readonly pendingRecoveryWindowSeconds;
+    private policyRegistered;
+    /**
+     * Durably records the agent-wide advertised recovery window.
+     *
+     * Written to the database, not held in memory: the promise is agent-wide,
+     * so a second store instance — in this process or another replica — must be
+     * held to the same value, and `installBinding` must read it inside its own
+     * transaction rather than trusting whatever the local object happens to
+     * know. Multiple replicas monotonically retain the smallest registered
+     * maximum: a shorter recovery promise is stronger and can never be widened
+     * by a later runtime.
+     */
+    adoptAdvertisedRecoveryWindowSeconds(seconds: number): Promise<void>;
+    /**
+     * Durably records the advertised `status_retention_days`.
+     *
+     * Retention is enforced against the widest promise any runtime registered
+     * over this database, so a store configured with a short evidence retention
+     * cannot prune inside a horizon a differently configured runtime published.
+     */
+    adoptAdvertisedStatusRetentionDays(days: number): Promise<void>;
+    /** Registers the complete capability policy under one lock and transaction. */
+    adoptAdvertisedPolicies(policy: ReportingManagedDeliveryAdvertisedPoliciesV1): Promise<ReportingManagedDeliveryAdvertisedPoliciesV1>;
+    /**
+     * Flushes constructor-supplied promises into the durable registry.
+     *
+     * Called from every entry point that depends on them, so a store built with
+     * options behaves identically to one a runtime adopted into.
+     */
+    private ensurePolicyRegistered;
+    private upsertPolicy;
+    private upsertPolicies;
+    private validateRecoveryWindow;
+    private readPolicyRow;
+    private readPolicy;
+    constructor(pool: ReportingPgPool, options?: PostgresReportingManagedDeliveryStoreOptions);
+    /** SQL fragment scoping a count to the active retention window, if one is set. */
+    private activeScope;
+    /**
+     * Deletes managed evidence that has aged out of `evidenceRetentionDays`.
+     *
+     * Only ever removes evidence the deployment no longer promises: nothing
+     * inside the retention window, nothing still `pending` or leased, and no
+     * receipt batch inside its own replay retention. Immutable evidence stays
+     * immutable while it is retained — this frees capacity at the far end of the
+     * window rather than rewriting anything. Returns what it removed so a
+     * scheduler can page through with `limit`.
+     */
+    pruneExpiredEvidence(input: {
+        account_id: string;
+        limit?: number;
+    }): Promise<{
+        materializations: number;
+        receipts: number;
+        batches: number;
+    }>;
+    probe(coreStore: ReportingLedgerStore): Promise<boolean>;
+    listInstalledRecoveryWindowSeconds(): Promise<number[]>;
+    authorizeDestination(input: Omit<ReportingDestinationAuthorizationV1, 'revoked_at' | 'cleanup_completed_at'>): Promise<void>;
+    revokeDestination(input: {
+        account_id: string;
+        destination_ref: string;
+        generation: number;
+        revoked_at: string;
+    }): Promise<boolean>;
+    installBinding(binding: ReportingManagedDeliveryBindingV1): Promise<{
+        inserted: boolean;
+    }>;
+    planMaterializations(input?: {
+        account_id?: string;
+        limit?: number;
+    }): Promise<number>;
+    claimMaterialization(input: {
+        owner: string;
+        now: string;
+        lease_milliseconds: number;
+        account_id?: string;
+    }): Promise<ReportingManagedDeliveryLeaseV1 | null>;
+    /**
+     * Fails materializations that have used every delivery attempt.
+     *
+     * The claim predicate stops handing them out, so without this they would
+     * stay `pending` — invisible to the planner, which skips an obligation with
+     * any pending row, and so never retried or replanned.
+     */
+    failExhaustedMaterializations(input?: {
+        account_id?: string;
+        limit?: number;
+    }): Promise<number>;
+    settleMaterialization(input: {
+        lease: ReportingManagedDeliveryLeaseV1;
+        now: string;
+        /** Retention the database must see satisfied, not just the worker. */
+        minimum_resource_retention_days?: number;
+        outcome: {
+            status: 'available' | 'delivered';
+            resource: NonNullable<ReportingMaterialization['resource']>;
+            verification: NonNullable<ReportingMaterialization['verification']>;
+        } | {
+            status: 'failed';
+            failure_code: string;
+        };
+    }): Promise<boolean>;
+    claimRevocation(input: {
+        owner: string;
+        now: string;
+        lease_milliseconds: number;
+        account_id?: string;
+        authorization_revocation_seconds?: number;
+        steal_after_milliseconds?: number;
+    }): Promise<ReportingDestinationRevocationLeaseV1 | null>;
+    completeRevocation(input: {
+        lease: ReportingDestinationRevocationLeaseV1;
+        completed_at: string;
+    }): Promise<boolean>;
+    releaseRevocation(input: {
+        lease: ReportingDestinationRevocationLeaseV1;
+        backoff_milliseconds?: number;
+    }): Promise<boolean>;
+    getReadableResource(input: {
+        account_id: string;
+        resource_ref: string;
+    }): Promise<{
+        materialization: {
+            reporting_materialization_id: string;
+            reporting_revision_id: string;
+            reporting_obligation_id: string;
+            delivery_config_id: string;
+            delivery_config_version: number;
+            destination_ref: string;
+            feed_purpose: import("../../types/tools.generated").ReportingFeedPurpose;
+            method: "file_transfer" | "dataset_share" | "warehouse_materialization";
+            transport?: string;
+            attempt: number;
+            status: "pending" | "available" | "delivered" | "failed";
+            ready_at?: string;
+            failed_at?: string;
+            failure_code?: string;
+            resource?: import("../../types").ReportingResource;
+            verification?: import("../../types").ReportingVerification;
+            created_at: string;
+        };
+        binding: ReportingManagedDeliveryBindingV1;
+    } | null>;
+    isAuthorizationCurrent(input: {
+        account_id: string;
+        destination_ref: string;
+        generation: number;
+    }): Promise<boolean>;
+    syncReceiptBatch(input: ReportingReceiptBatchInputV1): Promise<SyncReportingReceiptsResponse['results']>;
+    /**
+     * Rebuilds a prior batch response from the compact replay record plus the
+     * append-only receipt rows, re-checking authorization exactly as the first
+     * call did so a revoked destination cannot be replayed back into disclosure.
+     */
+    /**
+     * Replays a prior batch response exactly.
+     *
+     * An exact same-key replay is side-effect free and returns the caller its own
+     * previously recorded verdict, so later revocation of the destination does
+     * not change it. Downgrading a replay to `failed` once authorization ended
+     * broke the protocol-wide rule that a replayed idempotency key returns the
+     * same response, and bought nothing: the body is the caller's own receipt
+     * echoed back with the verdict it already received, so a revoked caller
+     * learns nothing it did not already hold. Fail-closed still governs every
+     * path that *accepts* new evidence — `loadReceiptEvidence` joins
+     * `revoked_at IS NULL` — and nothing here reads another consumer's rows.
+     */
+    private replayReceiptBatch;
+    private recordReceipt;
+    private loadReceiptEvidence;
+    private transaction;
+    private query;
+}