@openlfcp/client 0.1.2 → 0.1.3

package/README.md

@@ -14,7 +14,7 @@ Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
 at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.2`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.3`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Links
 

package/dist/apply.d.ts

@@ -0,0 +1,319 @@
+import { type ActorSequence, type DataEpoch, type DataUnitId, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type ResourceDEK } from "@openlfcp/crypto";
+import type { LfcpStorage } from "@openlfcp/storage";
+import { type ControlView, type DataProfileCodec, type DataUnitCheckOptions, type DataUnitEquivocation, type DataUnitQuarantined, type ReceivedDataUnit } from "@openlfcp/wire";
+/**
+ * Applying received Data Units to the Resource's Data Profile (LFCP-033).
+ *
+ * This is where LFCP security ends and application semantics begin. The
+ * LFCP side is receiveDataUnit (LFCP-025), unchanged and in its order:
+ * structure → actor → signature → equivocation → referenced head →
+ * data/write at that head → epoch and cutoff → DEK → AEAD → profile
+ * decode → actor hash chain (accepted or held). Only an accepted unit
+ * reaches the profile, and only once: the Data Unit ID is the idempotency
+ * boundary.
+ *
+ * The profile side is a DataProfileHandler, selected by the Resource's
+ * Genesis data_profile. The applier knows no profile: the Shared Objects
+ * handler lives in @openlfcp/shared-objects. A Resource whose profile has
+ * no handler is PROFILE_UNSUPPORTED: its units are verified without a DEK
+ * and kept, and their plaintext is never decrypted or applied.
+ *
+ * Three ways a valid unit can wait, kept apart:
+ * - held (§26.2, G-DP1): its actor chain does not link yet; retried here
+ *   when the actor's previous unit is accepted;
+ * - profile-pending: LFCP-accepted, but the profile cannot merge it until
+ *   other units' content arrives (Automerge dependencies); the handler
+ *   buffers it and merges it when they do;
+ * - quarantined (STALE_DATA_EPOCH): never merged automatically.
+ *
+ * Crash-loop breaker (EngineGuard): every engine call on received units
+ * (decode and apply, also when replaying) runs with a durable record of
+ * the units it covers. After a crash those units are suspects, received
+ * and replayed alone; a unit that crashes the engine again by itself is
+ * quarantined locally (status local-failure, INVALID_AUTOMERGE_BYTES) and
+ * never given to the engine again. Exclusion and rebuild (G-EP7) work on
+ * units already merged once and are not guarded.
+ */
+/** An LFCP-accepted unit as the profile sees it. */
+export interface ProfileUnit {
+    readonly unitId: DataUnitId;
+    readonly resourceId: ResourceId;
+    readonly actor: PrincipalId;
+    readonly seq: ActorSequence;
+    readonly epoch: DataEpoch;
+}
+/** A profile-level finding about the state after a merge (e.g. a PROFILE_INVALID object). */
+export interface ProfileDiagnostic {
+    readonly objectId?: string;
+    readonly code: string;
+    readonly diagnostic?: string;
+    readonly pointer?: string;
+    readonly message: string;
+}
+export interface ProfileApplyResult {
+    /** Units merged by this call: the unit itself when it merged now, and buffered units it unblocked. */
+    readonly merged: readonly DataUnitId[];
+    /** Objects whose state changed. */
+    readonly objects: readonly string[];
+    /** Findings about the merged state; they never undo the merge (profile §77 isolation). */
+    readonly diagnostics: readonly ProfileDiagnostic[];
+    /** Why the unit is buffered by the profile when it did not merge now. */
+    readonly pending?: string;
+    /**
+     * Why the profile holds the unit (SHARED-OBJECTS-PROFILE-01 §14.1): a
+     * different change has its actor and sequence number. Never merged until
+     * a rebuild frees them.
+     */
+    readonly held?: string;
+}
+/** What a handler's applyBatch reports: per unit merged, pending or rejected, and the objects once. */
+export interface ProfileBatchResult {
+    /** Units merged now: the batch's and buffered units it unblocked. */
+    readonly merged: readonly DataUnitId[];
+    /** Units buffered by the profile (the batch's, and earlier ones still waiting). */
+    readonly pending: readonly DataUnitId[];
+    /** Units the profile holds (§14.1): a different change has their actor and sequence number. */
+    readonly held?: readonly DataUnitId[];
+    /** Units the profile refused, with the code and message apply would have thrown. */
+    readonly rejected: readonly {
+        readonly unitId: DataUnitId;
+        readonly code: string;
+        readonly message: string;
+    }[];
+    readonly objects: readonly string[];
+    readonly diagnostics: readonly ProfileDiagnostic[];
+}
+export interface ProfileExcludeResult {
+    /** Objects whose state changed. */
+    readonly objects: readonly string[];
+    /** Merged units that now wait for an excluded unit's content (profile-pending). */
+    readonly pending: readonly DataUnitId[];
+    /** Held units (§14.1) that merged after the rebuild freed their actor sequence. */
+    readonly released?: readonly DataUnitId[];
+}
+/** The application side of one Data Profile. Implemented by profile packages. */
+export interface DataProfileHandler<T> {
+    /** The Genesis data_profile it implements (§15, §27). */
+    readonly dataProfile: string;
+    /**
+     * The codec for one unit's plaintext. The unit's Resource and signing
+     * actor are known before its plaintext is decoded, so the codec can bind
+     * the content to them; decode throws to reject (local-failure, never
+     * merged, never marked accepted).
+     */
+    codecFor(unit: {
+        readonly resourceId: ResourceId;
+        readonly actor: PrincipalId;
+    }): DataProfileCodec<T>;
+    /** Merges one accepted unit's decoded value. Throws when the profile refuses it. */
+    apply(unit: ProfileUnit, value: T): ProfileApplyResult;
+    /**
+     * Merges many accepted units at once, as apply would one by one (a
+     * refusal rejects only its unit). Optional: with it, receiveBatch and
+     * replayStored hand the profile a whole catch-up at once, which an engine
+     * such as Automerge applies far faster than unit by unit.
+     */
+    applyBatch?(units: readonly {
+        readonly unit: ProfileUnit;
+        readonly value: T;
+    }[]): ProfileBatchResult;
+    /**
+     * LFCP-WIRE-01 §19.1 (G-EP7): takes merged or buffered units out again, so that
+     * the state equals the state built from the remaining accepted units.
+     */
+    exclude(unitIds: readonly DataUnitId[]): ProfileExcludeResult;
+    /**
+     * Whether the profile state holds this unit's content. With it, units
+     * merged after the last persisted checkpoint can be replayed from storage
+     * after a restart (DataUnitApplier.replayStored).
+     */
+    has?(unitId: DataUnitId): boolean;
+    /** Forgets the whole profile state, to rebuild it from accepted units (SNAP-EP). */
+    reset?(): void;
+}
+interface Applied {
+    readonly unitId: DataUnitId;
+    readonly dataProfile: string;
+    readonly actor: PrincipalId;
+    readonly seq: ActorSequence;
+    readonly epoch: DataEpoch;
+    /**
+     * Whether the unit may be advertised in Haves. Always false here: a unit
+     * is advertised only once the sync layer knows its storage is durable
+     * (LFCP-036).
+     */
+    readonly haveEligible: false;
+    /** Buffered units this one unblocked, merged now. */
+    readonly alsoMerged: readonly DataUnitId[];
+    /** Held units of the same actor that were retried after this one, with their outcomes. */
+    readonly released: readonly ApplyOutcome[];
+}
+/**
+ * Two or more signature-valid units for one (resource, actor, seq).
+ * LFCP-WIRE-01 §26.2 (G-DP5): no unit of the set stays merged, since keeping the
+ * first one would choose by arrival order (§26.2 forbids choosing). Every
+ * unit is marked "equivocation" and un-accepted; merged ones were taken out
+ * of the profile state.
+ */
+export type EquivocationOutcome = DataUnitEquivocation & {
+    /** Units of the set that were merged and are now excluded from the profile state. */
+    readonly excluded: readonly DataUnitId[];
+    /** Objects whose state changed through the exclusion. */
+    readonly objects: readonly string[];
+    /** Merged units that now wait in the profile for an excluded unit's content. */
+    readonly pending: readonly DataUnitId[];
+    /** Held units of the actor retried after the exclusion (§26.2, G-DP1-GAP). */
+    readonly released: readonly ApplyOutcome[];
+};
+/** The outcome of one received Data Unit. */
+export type ApplyOutcome = 
+/** Accepted by LFCP and merged into the profile state. */
+(Applied & {
+    readonly kind: "applied";
+    readonly objects: readonly string[];
+    readonly diagnostics: readonly ProfileDiagnostic[];
+})
+/** Accepted by LFCP; the profile buffers it until the content it builds on arrives. */
+ | (Applied & {
+    readonly kind: "profile-pending";
+    readonly detail: string;
+})
+/**
+ * Accepted by LFCP and kept (a holding: advertised and relayed); the
+ * profile holds it because a different change has its actor and sequence
+ * number (SHARED-OBJECTS-PROFILE-01 §14.1, POST-001). It is retried after
+ * every rebuild that removes changes, and reported as applied then.
+ */
+ | (Applied & {
+    readonly kind: "profile-held";
+    readonly detail: string;
+})
+/** Accepted by LFCP, refused by the profile when merging: never merged. */
+ | {
+    readonly kind: "profile-rejected";
+    readonly unitId: DataUnitId;
+    readonly dataProfile: string;
+    readonly code: string;
+    readonly message: string;
+}
+/** The Resource's Data Profile has no handler (§62 PROFILE_UNSUPPORTED): verified and kept, never decrypted. */
+ | {
+    readonly kind: "profile-unsupported";
+    readonly code: "PROFILE_UNSUPPORTED";
+    readonly unitId: DataUnitId;
+    readonly dataProfile: string;
+}
+/**
+ * A unit whose content a loaded Snapshot already holds: verified without
+ * a DEK and accepted, never decrypted or merged again (acceptCovered).
+ */
+ | {
+    readonly kind: "covered";
+    readonly unitId: DataUnitId;
+    readonly dataProfile: string;
+    /** Held units of the same actor that were retried after this one, with their outcomes. */
+    readonly released: readonly ApplyOutcome[];
+}
+/**
+ * The unit crashed the profile engine twice by itself (EngineGuard): it
+ * is quarantined on this device and never applied again. Local only: no
+ * wire code; the unit may be valid elsewhere.
+ */
+ | {
+    readonly kind: "engine-crash";
+    readonly code: "INVALID_AUTOMERGE_BYTES";
+    readonly unitId: DataUnitId;
+    readonly message: string;
+} | EquivocationOutcome | Exclude<ReceivedDataUnit<unknown>, {
+    readonly kind: "accepted" | "equivocation";
+}>;
+/** A merged unit that a newly known Key Epoch puts beyond its cutoff (G-EP7). */
+export interface ExcludedUnit {
+    readonly unitId: DataUnitId;
+    readonly quarantine: Omit<DataUnitQuarantined, "kind" | "unitId">;
+}
+export interface EpochReconciliation {
+    /** Units taken out of the profile state and now quarantined. */
+    readonly excluded: readonly ExcludedUnit[];
+    /** Objects whose state changed. */
+    readonly objects: readonly string[];
+    /** Merged units that now wait in the profile for an excluded unit's content. */
+    readonly pending: readonly DataUnitId[];
+    /**
+     * The Key Epoch cut off units a loaded Snapshot covered: the Snapshot
+     * state was dropped and rebuilt from accepted units (SNAP-EP); the units
+     * it covered must be fetched again.
+     */
+    readonly snapshotDropped: boolean;
+    /**
+     * Held units retried once the excluded units stopped being their actors'
+     * latest accepted ones (§26.2, G-DP1-GAP), with their outcomes.
+     */
+    readonly released: readonly ApplyOutcome[];
+}
+export interface DataUnitApplierOptions extends DataUnitCheckOptions {
+    /**
+     * Where verified units, their exact bytes, statuses and the accepted
+     * marks live (the wire SeenUnits runs on it). InMemoryLfcpStorage for
+     * tests and development only.
+     */
+    readonly storage: Pick<LfcpStorage, "dataUnits" | "snapshots" | "commit" | "localMarks">;
+    /** The DEK of a Data Epoch, if this client holds it (e.g. dekResolver). */
+    readonly dek: (epoch: DataEpoch) => ResourceDEK | undefined | Promise<ResourceDEK | undefined>;
+    /** The profiles this client implements. */
+    readonly handlers: readonly DataProfileHandler<unknown>[];
+}
+export declare class DataUnitApplier {
+    #private;
+    constructor(options: DataUnitApplierOptions);
+    /**
+     * Receives one Data Unit of the Resource `view` describes. Never creates
+     * a Data Unit: received content is applied, not re-sent as local work.
+     */
+    receive(view: ControlView, bytes: Uint8Array): Promise<ApplyOutcome>;
+    /**
+     * Receives the units of one DATA_BATCH (or any run of units) of the
+     * Resource `view` describes: each passes the LFCP checks of receive in
+     * order, unchanged, and the accepted ones reach the profile together
+     * through the handler's applyBatch, when it has one. Outcomes come in the
+     * order of `units`. An applied unit's objects and diagnostics are those
+     * of the whole batch, reported on the last unit merged; the units
+     * buffered before that the batch unblocked count as merged by the first.
+     * Before an equivocation is handled, the units accepted so far are
+     * applied, so its exclusion sees them.
+     */
+    receiveBatch(view: ControlView, units: readonly Uint8Array[]): Promise<ApplyOutcome[]>;
+    /**
+     * After a restart: the stored, LFCP-accepted units (merged or buffered by
+     * the profile) whose content the restored profile state does not hold
+     * (merged after its last checkpoint), decrypted again from their exact
+     * stored bytes and applied, in (actor, seq) order. Units covered by a
+     * Snapshot are not replayed (their content came with it). Needs the
+     * handler's has(); returns what was replayed and what could not be (no
+     * DEK, refused). LFCP checks are not repeated: the units passed them when
+     * they were accepted.
+     */
+    replayStored(view: ControlView): Promise<{
+        readonly replayed: readonly DataUnitId[];
+        readonly skipped: readonly {
+            readonly unitId: DataUnitId;
+            readonly reason: string;
+        }[];
+        /** Units quarantined at this start: they crashed the engine twice by themselves. */
+        readonly crashed: readonly DataUnitId[];
+    }>;
+    /**
+     * A unit inside the frontier of a Snapshot this client loaded (§29, §66
+     * step 3): its content is in the Snapshot, so it is not decrypted or
+     * merged again. It gets the DEK-free LFCP checks (structure, signature,
+     * equivocation, data/write at its head, epoch cutoff) and is then marked
+     * accepted, so the actor's next unit links to it (§26.2). Its own link to
+     * the previous unit is not checked: that unit is attested by the signed,
+     * authorized Snapshot and was never received. A replay is a duplicate.
+     */
+    acceptCovered(view: ControlView, bytes: Uint8Array): Promise<ApplyOutcome>;
+    reconcileEpochs(view: ControlView): Promise<EpochReconciliation>;
+}
+export {};
+//# sourceMappingURL=apply.d.ts.map