@kokuin/records 0.0.0-stage → 0.2.0

package/lib/apply.d.ts

@@ -0,0 +1,211 @@
+import type { MethodRegistry } from '@kokuin/token';
+import type { HLCTimestamp } from '@sozai/hlc';
+import type { RecordDecision } from './decision.js';
+import { type VerifiedRecordOp } from './op.js';
+import { type EqualVersionDecision, type MergePolicy } from './policy.js';
+import { type RecordKey, type SignedRecord } from './record.js';
+import { type RecordLockKey, type RecordStoreAdapter } from './store.js';
+/** The authenticated peer asking for records, and the controller it acts for, if any. */
+export type RecordRequester = {
+    peerDID: string;
+    controllerDID: string | null;
+};
+/**
+ * What a responding peer knows when it decides whether a requester may receive a record.
+ *
+ * - `proofs` are records the requester presented as its own, such as its wrapping of a key.
+ *   They are hostile input: the responder checks them and never stores or forwards them.
+ * - `store` is the responder's own store, read for its holdings and for proof dependencies.
+ * - `authorizeProof` is the authorizer apply would run on the proof, bound to the resolvers
+ *   and to this context's `store`, which it passes as the authorizer's `store`.
+ *   `stored` is the responder's verified row for the proof's record, or `null` when it holds
+ *   none, as apply passes it.
+ * - `currentKeyVersion` is the responder's current version of the key `keyID` of `owner` (a
+ *   normalized DID), `null` when it holds none. A key id names a key only within its owner.
+ * - `holderTypes` are the types whose records show that their recipient holds a key, keyed by
+ *   type; a proof's dependencies come from its definition. A record of any other type is
+ *   never a holding, whatever its `meta` says, so a revocation naming a key and a recipient
+ *   cannot pass for a wrapping. Empty, no one is a key holder.
+ */
+export type VisibilityContext = {
+    requester: RecordRequester;
+    opKind: string;
+    /** Caller-owned transport state, passed unchanged and never signed. */
+    transportContext?: unknown;
+    proofs: ReadonlyArray<SignedRecord>;
+    store: RecordStoreAdapter;
+    authorizeProof: (record: SignedRecord, stored: SignedRecord | null) => Promise<boolean>;
+    currentKeyVersion: (owner: string, keyID: string) => Promise<number | null>;
+    isGroupMember: (groupID: string, did: string) => Promise<boolean>;
+    holderTypes: ReadonlyMap<string, RecordTypeDefinition>;
+    methods?: MethodRegistry;
+};
+/**
+ * What an authorizer reads beside the verified op.
+ *
+ * - `record` is the record being authorized. Its payload has not been checked against the
+ *   signed digest yet: an authorizer that reads the payload must call `recordPayloadMatches`
+ *   first, or it reasons over bytes nobody signed.
+ * - `stored` is the record's current verified row, or `null` on a first write.
+ * - `store` is the store the decision runs against: the chunk's transaction in apply, the
+ *   responder's store for a holder proof. An authorizer reads other records through it,
+ *   never through a store bound outside the transaction.
+ */
+export type RecordReceiveContext = {
+    /** Caller-owned transport state, passed unchanged and never signed. */
+    transportContext?: unknown;
+};
+export type RecordAuthorizeContext = RecordReceiveContext & {
+    record: SignedRecord;
+    stored: SignedRecord | null;
+    store: RecordStoreAdapter;
+    /**
+     * Another record's decision as the chunk has left it, records stored earlier in the chunk
+     * included. Apply serves it from the chunk's batched reads. Absent outside apply: read
+     * `store` instead.
+     */
+    decision?: (key: RecordKey) => Promise<RecordDecision | null>;
+    resolveController: (did: string) => Promise<string | null>;
+    verifyCapability: (tokens: ReadonlyArray<string>, owner: string, issuer: string) => Promise<boolean>;
+};
+/**
+ * A record this one needs before it can be authorized. It is satisfied when the store holds
+ * a verified op for `(type, id)` and, if given, `satisfiedBy` accepts that op — a wrapping for
+ * key version 3 is not satisfied by version 2 of the key. An unsatisfied dependency parks the
+ * record, the same as a missing one, until a later op satisfies it.
+ */
+export type RecordDependency = RecordKey & {
+    satisfiedBy?: (stored: VerifiedRecordOp) => boolean;
+};
+/**
+ * How the apply engine treats one record type.
+ *
+ * - `authorize` decides whether the op's verified issuer may write this record. `stored` is
+ *   the record's current op, or `null` on a first write. The engine itself refuses an owner
+ *   change under `lww` and `monotonic`, whatever `authorize` answers. `immutable` skips this
+ *   owner-continuity check. Owner-qualified keys keep different owners' records separate.
+ *   WARNING: bind `claim.owner` to the owner of the record an immutable record depends on.
+ *   Checking only the issuer against `claim.owner` can admit a dependent under the wrong owner.
+ * - `precheck` is a stateless issuer and signed-shape check before dependencies are read.
+ * - `dependsOn` lists the types whose records this one may need, and orders a chunk.
+ * - `dependencies` names the exact records this one needs before it can be authorized. It
+ *   runs only after the signature has verified, and should read the signed claim in `op`:
+ *   the payload is not checked against its digest until after the merge decision.
+ * - `onEqual` must answer the same for (a, b) as for (b, a).
+ * - `afterApply` runs inside the chunk's transaction, once the record is stored.
+ *
+ * Apply keeps every decision it reads for the rest of the chunk and updates it with its own
+ * writes. Hooks may write other state through the store, never a record decision.
+ */
+export type RecordTypeDefinition = {
+    type: string;
+    policy: MergePolicy;
+    dependsOn: ReadonlyArray<string>;
+    /**
+     * Whether the op's issuer may write this record. For an `immutable` type the engine skips
+     * the owner-continuity check, so this must bind `op.claim.owner` to the owner of the
+     * record it depends on.
+     */
+    authorize(op: VerifiedRecordOp, ctx: RecordAuthorizeContext): Promise<boolean>;
+    precheck?: (op: VerifiedRecordOp, record: SignedRecord) => Promise<boolean>;
+    visibleTo?: (record: SignedRecord, ctx: VisibilityContext) => Promise<boolean>;
+    dependencies(record: SignedRecord, op: VerifiedRecordOp): ReadonlyArray<RecordDependency>;
+    onEqual?: (incoming: VerifiedRecordOp, stored: VerifiedRecordOp) => EqualVersionDecision;
+    afterApply?: (record: SignedRecord, store: RecordStoreAdapter) => Promise<void>;
+    /** Retain authenticated branch evidence even when the merge keeps another current op. */
+    afterAuthorize?: (record: SignedRecord, store: RecordStoreAdapter) => Promise<void>;
+    /** Keys this write can affect; `stored` is a speculative read before the chunk locks. */
+    lockKeys?: (incoming: SignedRecord, stored: RecordDecision | null) => ReadonlyArray<RecordLockKey> | Promise<ReadonlyArray<RecordLockKey>>;
+};
+/**
+ * Two different ops met at one version of a record. `record` is the incoming one; whichever
+ * op won is the one the store now holds. `forked` when the type's `onEqual` hook kept both as
+ * branches: the store still holds only the greater `opHash`, and retaining the other branch
+ * is the type's work.
+ */
+export type RecordConflict = {
+    record: SignedRecord;
+    storedOpHash: string;
+    incomingOpHash: string;
+    forked: boolean;
+};
+/**
+ * - `applied`: records stored by this chunk.
+ * - `parked`: records whose dependencies are not stored, or not yet satisfied. They passed the clock and
+ *   signature and precheck checks; the caller keeps them and passes them to a later
+ *   chunk or session, since another peer may hold the dependency.
+ * - `rejected`: `reason` is the first check that failed — `clock`, `unknown-type`,
+ *   `signature`, `owner`, `unauthorized`, the policy's own reason (such as `version-invalid`),
+ *   or `digest`.
+ * - `conflicts`: every equal-version meeting of two different ops, in either outcome.
+ *
+ * A record that loses the merge, or repeats the stored op, appears in none of them.
+ */
+export type ApplyResult = {
+    applied: number;
+    parked: Array<SignedRecord>;
+    rejected: Array<{
+        record: SignedRecord;
+        reason: string;
+    }>;
+    conflicts: Array<RecordConflict>;
+};
+export type ApplyRecordChunkParams = RecordReceiveContext & {
+    opKind: string;
+    records: ReadonlyArray<SignedRecord>;
+    store: RecordStoreAdapter;
+    types: ReadonlyMap<string, RecordTypeDefinition>;
+    nowMS: number;
+    maxDriftMS: number;
+    receiveClock: (stamp: HLCTimestamp) => void;
+    methods?: MethodRegistry;
+    /** Called for several DIDs at once before the chunk locks; must accept concurrent calls. */
+    resolveController: (did: string) => Promise<string | null>;
+    verifyCapability: (tokens: ReadonlyArray<string>, owner: string, issuer: string) => Promise<boolean>;
+};
+/** Thrown when the registered types' `dependsOn` is cyclic or names an unregistered type. */
+export declare class RecordTypeGraphError extends Error {
+    constructor(message: string);
+}
+/** A speculative lock set changed; an ambient transaction must roll back before retrying. */
+export declare class RecordSourceChangedError extends Error {
+    constructor();
+}
+/** A type hook refused one signed record's content permanently. */
+export declare class RecordContentRefusalError extends Error {
+    constructor(message: string);
+}
+/** Whether the store lacks a dependency, or holds an op for it that does not satisfy it. */
+export declare function isDependencyUnsatisfied(dependency: RecordDependency, tx: RecordStoreAdapter, opKind: string, methods?: MethodRegistry): Promise<boolean>;
+/** As {@link isDependencyUnsatisfied}, against a decision already read. */
+export declare function isDependencyUnsatisfiedBy(dependency: RecordDependency, stored: RecordDecision | null, opKind: string, methods?: MethodRegistry): Promise<boolean>;
+/**
+ * Apply a chunk of records received from a peer, in one transaction.
+ *
+ * Each record passes checks in order, and stops at the first it fails:
+ * 1. its `hlc` is canonical and within `maxDriftMS` of `nowMS`;
+ * 2. its op verifies, and signs exactly the record's `type`, `id`, `owner`, `hlc` and
+ *    `opHash`;
+ * 3. its type's stateless precheck accepts the issuer, before dependency lookup;
+ * 4. dependencies are present and satisfied, or the record parks;
+ * 5. its type's authorizer accepts the issuer after the owner binding;
+ * 6. its type's merge policy prefers it to the stored op, or admits it as a first write;
+ * 7. its payload matches the signed digest.
+ *
+ * Nothing about a record is read before the first check — not the store, not its signature
+ * — and `receiveClock` advances the local clock from stored records after the chunk's
+ * transaction returns. An owned transaction has committed at that point. Inside a
+ * caller-owned transaction, apply advances `receiveClock` before the enclosing transaction
+ * commits. Callers needing commit-only clock effects must defer them until that commit.
+ * Records apply in the types' dependency order; one whose dependencies are not
+ * stored or not yet satisfied is retried after each pass that stored something, and returned
+ * as parked when a pass stores nothing.
+ *
+ * An error from the store, a hook or a resolver rolls the chunk back and propagates. A type
+ * hook may use `RecordContentRefusalError` for a deterministic refusal of one record's content.
+ *
+ * @throws RecordTypeGraphError when the types' dependencies are cyclic or unregistered.
+ * @throws RecordSourceChangedError when a changed lock set requires an ambient transaction
+ * to roll back, or five owned transaction attempts all observe a changed lock set.
+ */
+export declare function applyRecordChunk(params: ApplyRecordChunkParams): Promise<ApplyResult>;