@openlfcp/client 0.1.1 → 0.1.2

package/README.md

@@ -12,9 +12,9 @@ ESM only; Node.js 24 or later (browsers and Electron for every package except `@
 
 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.8`, not every deferred WIRE-01 feature. It does not
+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.1`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.2`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Links
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/client",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "LFCP client: session, Control Plane and Data Plane synchronization.",
   "keywords": [
     "openlfcp",
@@ -42,9 +42,9 @@
     "tag": "latest"
   },
   "dependencies": {
-    "@openlfcp/core": "^0.1.1",
-    "@openlfcp/storage": "^0.1.1",
-    "@openlfcp/crypto": "^0.1.1",
-    "@openlfcp/wire": "^0.1.1"
+    "@openlfcp/core": "^0.1.2",
+    "@openlfcp/crypto": "^0.1.2",
+    "@openlfcp/storage": "^0.1.2",
+    "@openlfcp/wire": "^0.1.2"
   }
 }

package/dist/apply.d.ts

@@ -1,299 +0,0 @@
-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;
-}
-/** 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 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[];
-}
-/** 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, 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