Skip to main content

Class: ForgottenLedger

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:337

The forgotten subjects of one store.

Example​

const ledger = await ForgottenLedger.open({ primary: storeAdapter, copy: copyAdapter, key: { current: secret } });
await ledger.markForgotten({ kind: 'user', id: userId });
await ledger.isForgotten({ kind: 'user', id: userId }); // true

Properties​

keyed​

readonly keyed: boolean

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:341

Whether writes are keyed.


namespaces​

readonly namespaces: readonly string[]

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:339

The namespaces a check reads, '' first, each once.

Methods​

countNotOf()​

countNotOf(subject): Promise<number>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:754

How many tombstones of either ledger, markers aside, are none of this subject's forms.

Parameters​

subject​

SuppressionSubject

Returns​

Promise<number>

Throws​

For a subject with another kind or no id.


isForgotten()​

isForgotten(subject): Promise<boolean>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:699

Whether either ledger holds a tombstone of the subject: every form, every namespace.

Parameters​

subject​

SuppressionSubject

Returns​

Promise<boolean>

Throws​

For a subject with another kind or no id.


markForgotten()​

markForgotten(subject): Promise<{ form: "keyed" | "unkeyed"; written: boolean; }>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:682

Writes the tombstone to the copy, then to the primary, each with its key's marker and a new state mark in one transaction, after uniting the two sides' rows. written is false when both held it; the mark rises either way. Rejects when either side's transaction fails: a caller deletes nothing without the tombstone in both.

Parameters​

subject​

SuppressionSubject

Returns​

Promise<{ form: "keyed" | "unkeyed"; written: boolean; }>

Throws​

For a subject with another kind or no id.

Throws​

LEDGER_IDENTITY_MISMATCH when a side no longer holds the ledger's identity, LEDGER_STATE_INVALID when a side's identity or state row is damaged, KEY_REQUIRED for a key marker of a key the handle was not given; nothing is written.


readState()​

readState(): Promise<Readonly<{ identity: string; mark: string; }>>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:733

Brings both sides up to date, as reconcile() does, and returns the ledger's identity and the state mark the store holds after it: two strings, and nothing else. Read fresh from storage on every call.

Returns​

Promise<Readonly<{ identity: string; mark: string; }>>

Throws​

LEDGER_IDENTITY_MISMATCH when a side no longer holds the identity the open found (its database was replaced under the open handle), LEDGER_STATE_INVALID when a side's rows are damaged.

Example​

const { identity, mark } = await ledger.readState();
// Two marks of one identity: equal means no tombstone was written between the two reads.

reconcile()​

reconcile(): Promise<{ added: string[]; }>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:713

Fills missing rows in both directions and leaves both sides at the higher state mark; it never lowers one. A tombstone one side holds without holding the higher mark was written outside the ledger, and raises the mark once. added lists the tombstones brought back into the primary since the last reconcile() on this handle, its own and those of an open, a deletion or a state read on the way, markers and a deletion's own tombstone left out. With no copy there is nothing to bring back.

Returns​

Promise<{ added: string[]; }>


size()​

size(): Promise<number>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:741

How many tombstones either ledger holds, markers aside: 0 for a store that has forgotten nobody.

Returns​

Promise<number>


hash()​

static hash(namespace, subject, key?): Promise<string>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:662

SHA-256, or HMAC-SHA-256 with a key, over the canonical JSON [namespace, kind, id], as lowercase hex.

Parameters​

namespace​

string

subject​

SuppressionSubject

key?​

TombstoneKey

Returns​

Promise<string>


keyMarker()​

static keyMarker(key): Promise<string>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:668

k1: and the first 16 hex characters of SHA-256 over the key's bytes.

Parameters​

key​

TombstoneKey

Returns​

Promise<string>


open()​

static open(options): Promise<ForgottenLedger>

Defined in: packages/agentos/src/cognition/memory/suppression/ForgottenLedger.ts:388

Creates the table where missing on each adapter, then checks the copy marker, the key markers and the two rows that name the ledger: i1:identity and s1:state.

A store that never had a copy and is given one has both marked as a pair. An existing copy is repaired from the primary too, after marker validation, so replacing the copy with an older backup cannot lose tombstones. The tombstones stay where they are on the store until reconcile().

A new ledger gets one identity, 16 random bytes, and one state mark, the same on both sides. A ledger made before these rows existed gains them and keeps every row it held. A store without them beside a copy that has them takes the copy's identity, state and tombstones, and a copy without them is repaired from its store, when the side without them holds no tombstone or key marker the other lacks.

Parameters​

options​

ForgottenLedgerOptions

Returns​

Promise<ForgottenLedger>

Throws​

When any current or previous key is empty.

Throws​

COPY_UNAVAILABLE when the copy is the primary database (the same adapter, the same native SQLite file, or on Postgres the same table: one database and schema, through any pool; two adapters of another kind on one file, sql.js among them, are not told apart), cannot be read, or when the store had a copy and the copy given does not know it (or none is given); KEY_REQUIRED when either ledger holds the marker of a key that was not passed; LEDGER_IDENTITY_MISMATCH when the store and the copy hold different identities, or the side without an identity holds a tombstone or key marker the other lacks; LEDGER_STATE_INVALID when a side holds one of the two rows without the other, a malformed one, or a tombstone the other side holds with another namespace or time; LEDGER_UNAVAILABLE when an adapter has no transactions, the runtime has no secure random source, or a side's write lock is held by another connection past the driver's wait. Nothing is copied or marked by an open that is refused, and each refusal writes one memory.ledger_refused line.