Class SqlSourceDerivationStore

Durable private provenance on PostgreSQL. All source writers use this owner fence; model/provider work stays outside it. No method logs SQL, content or exceptions.

Every method that reads or writes an owner's results runs in one transaction that first locks that owner's fence row, so commits, deliveries, invalidations and expiry for one owner are serialized, while different owners proceed independently. Writing a deletion record also locks one shared journal row, last, so the records' sequence follows commit order.

Example

const store = new SqlSourceDerivationStore(db, { bindings });
const ticket = await store.capture({ tenantId, ownerId });
// ...generate an answer outside the store...
if (ticket && await store.commit(ticket, answerId, derivation, answerText, context)) {
  await store.deliver(answerId, context, (text) => {
    queue.push(text);
    return true;
  });
}

Constructors

constructor

Methods

activateOwner blockOwner capture apply commit deliver invalidate expireResults readTombstones replayTombstones

Constructors

constructor

  • new SqlSourceDerivationStore(db, options): SqlSourceDerivationStore

  • Parameters

    • db: StorageAdapter

      A PostgreSQL adapter with transactions. Each call that reads or writes an owner's state runs in a transaction of its own on it. On a transaction view (the adapter a transaction callback receives, whose own transaction runs a callback in that same transaction) each call runs inside the caller's transaction instead: it holds the owner's row, and after writing a deletion record the shared journal row, until the caller commits or rolls back, and the caller's rollback undoes it.

    • options: SourceDerivationStoreOptions

      Table prefix, clock and the host's bindings.

    Returns SqlSourceDerivationStore

    Throws

    derivations_require_postgres_transactions for another kind of adapter or one without transactions, and invalid_derivation_table_prefix for a malformed prefix.

Methods

activateOwner

  • activateOwner(scope, authorize): Promise<boolean>

  • Fresh authorization must also reject deleting/deleted host accounts.

    Runs authorize under the owner lock; when it answers true, an inactive owner becomes active with a new epoch.

    Parameters

    • scope: SourceOwnerScope
    • authorize: ((tx) => Promise<boolean>)
        • (tx): Promise<boolean>

        • Parameters

          • tx: StorageAdapter

          Returns Promise<boolean>

    Returns Promise<boolean>

    True when authorize answered true, the owner then being active; false when it answered false, which changes nothing.

blockOwner

  • blockOwner(scope, mutate): Promise<void>

  • Commit an inactive fence before disconnect, exclusion, grant-loss or deletion purge.

    Marks the owner inactive with a new epoch, runs mutate in the same transaction and records an owner-wide deletion. Nothing of the owner's is committed or delivered again until activateOwner succeeds.

    Parameters

    • scope: SourceOwnerScope
    • mutate: ((tx) => Promise<void>)
        • (tx): Promise<void>

        • Parameters

          • tx: StorageAdapter

          Returns Promise<void>

    Returns Promise<void>

capture

apply

  • apply<T>(ticket, work): Promise<SourceFencedResult<T>>

  • Execute short trusted storage work after the epoch check. This is not a content-delivery API. Source replacement uses invalidate with expected ticket.

    Type Parameters

    • T

    Parameters

    • ticket: SourceFenceTicket
    • work: ((tx) => Promise<T>)
        • (tx): Promise<T>

        • Parameters

          • tx: StorageAdapter

          Returns Promise<T>

    Returns Promise<SourceFencedResult<T>>

    applied with the work's value, or stale, without entering work, when the owner is inactive or its epoch has moved past the ticket's.

commit

  • commit(ticket, id, derivation, payload, context): Promise<boolean>

  • Persist one whole result only if every input remains current and permitted.

    The ticket must be current, context and derivation must name the ticket's tenant and owner, the record must be personal with the earliest expiry of its dependencies, and canDeliverSourceDerivation must allow it for context against the state readCurrent reads in this transaction. The payload is at most 1,048,576 UTF-16 code units long, and an id the owner already holds is not replaced.

    Parameters

    Returns Promise<boolean>

    Whether the result was stored.

deliver

  • deliver(id, context, enqueue): Promise<boolean>

  • Enqueue immediately under the lock; do not retain the argument or return a Promise.

    Reads the stored result and the current state of its sources under the owner lock and, when the owner is active and canDeliverSourceDerivation allows context, passes the payload to enqueue before the lock is released. The payload is never returned.

    Parameters

    • id: string
    • context: SourceDeliveryContext
    • enqueue: ((payload) => boolean)
        • (payload): boolean

        • Parameters

          • payload: string

          Returns boolean

    Returns Promise<boolean>

    What enqueue answered, or false when delivery is refused.

    Throws

    source_delivery_must_be_synchronous when enqueue answers anything but a boolean.

invalidate

  • invalidate<T>(scope, affected, mutate, options?): Promise<SourceFencedResult<T>>

  • Advance the fence, purge affected sources and all whole dependent results, and mutate host state in one transaction. A supplied expected ticket is a CAS.

    With expected, an inactive owner or an epoch past the ticket's answers stale without purging or entering mutate. Without it, the invalidation always applies, also to an inactive owner, which stays inactive. disableOwner leaves the owner inactive and needs an owner-wide invalidation. A thrown binding or mutate rolls back the epoch, the purge and the deletion record together.

    Type Parameters

    • T

    Parameters

    Returns Promise<SourceFencedResult<T>>

    Throws

    invalid_source_invalidation for a malformed affected, and owner_disable_requires_owner_scope for disableOwner with a connection or source.

expireResults

  • expireResults(scope, limit?): Promise<number>

  • Expiry is enforced at read regardless; this removes stored and host-bound copies.

    Parameters

    • scope: SourceOwnerScope
    • limit: number = 100

      At most this many results go in one call, earliest expiry first: an integer from 1 to 1,000.

    Returns Promise<number>

    How many results were removed.

    Throws

    invalid_derivation_batch for another limit.

readTombstones

  • readTombstones(afterSequence, limit?): Promise<readonly SourceDeletionTombstone[]>

  • Operator recovery export only; never expose this across account sessions.

    Parameters

    • afterSequence: number

      Answers the records after this sequence, in sequence order: 0 for the first page, then the last sequence of the page before.

    • limit: number = 100

      Page size, an integer from 1 to 1,000.

    Returns Promise<readonly SourceDeletionTombstone[]>

    Throws

    invalid_tombstone_page for a negative or fractional sequence or another limit.

replayTombstones

  • replayTombstones(records): Promise<void>

  • Restore is conservative: any affected owner is disabled and all of that owner's private sources/results are purged. Fresh authorized reconnect is required.

    Replaying the same records again is harmless: each deletion record is kept once, by its id, and the owner stays inactive. Run it on a restored database before any read or job resumes, with every record newer than the backup.

    Parameters

    Returns Promise<void>

    Throws

    invalid_source_tombstone, invalid_source_owner or invalid_source_invalidation for a malformed record, before that record is applied.

Settings

Member Visibility

Theme

On This Page

constructoractivateOwnerblockOwnercaptureapplycommitdeliverinvalidateexpireResultsreadTombstonesreplayTombstones