Class: SqlSourceDerivationStore
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:147
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
new SqlSourceDerivationStore(
db,options):SqlSourceDerivationStore
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:162
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
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>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:205
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
authorize
(tx) => Promise<boolean>
Returns
Promise<boolean>
True when authorize answered true, the owner then being active; false when it answered false,
which changes nothing.
apply()
apply<
T>(ticket,work):Promise<SourceFencedResult<T>>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:248
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
T
Parameters
ticket
work
(tx) => 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.
blockOwner()
blockOwner(
scope,mutate):Promise<void>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:224
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
mutate
(tx) => Promise<void>
Returns
Promise<void>
capture()
capture(
scope):Promise<SourceFenceTicket|null>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:238
Captures a ticket at the owner's current epoch, before work outside the store begins.
Parameters
scope
Returns
Promise<SourceFenceTicket | null>
The ticket, or null while the owner is not active.
commit()
commit(
ticket,id,derivation,payload,context):Promise<boolean>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:276
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
ticket
id
string
derivation
payload
string
context
Returns
Promise<boolean>
Whether the result was stored.
deliver()
deliver(
id,context,enqueue):Promise<boolean>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:319
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
enqueue
(payload) => 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.
expireResults()
expireResults(
scope,limit?):Promise<number>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:414
Expiry is enforced at read regardless; this removes stored and host-bound copies.
Parameters
scope
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.
invalidate()
invalidate<
T>(scope,affected,mutate,options?):Promise<SourceFencedResult<T>>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:382
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
T
Parameters
scope
affected
mutate
(tx) => Promise<T>
options?
disableOwner?
boolean
expected?
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.
readTombstones()
readTombstones(
afterSequence,limit?):Promise<readonlySourceDeletionTombstone[]>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:433
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>
Defined in: packages/agentos/src/cognition/library/SqlSourceDerivationStore.ts:456
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
records
readonly SourceDeletionTombstone[]
Returns
Promise<void>
Throws
invalid_source_tombstone, invalid_source_owner or invalid_source_invalidation for a
malformed record, before that record is applied.