@microdelta/history 0.0.0 → 0.2.0

package/README.md

@@ -1,7 +1,33 @@
-# @microdelta/history
+# Result History & Publication
 
-This package reserves the name for microdelta trusted-publishing setup.
+This package owns the scaffold's row Store, memory backend, legacy compatibility
+schema, and backend conformance suite. Its public declarations preserve the
+existing `microdelta` facade contract. `Path` is a row-storage address, not the
+future Value Semantics path. The memory backend proves single-row behavior only;
+it has no durable or cross-row publication guarantee.
 
-This bootstrap version contains no runtime implementation, dependencies, or install scripts. It is not a usable library release.
+It also owns the project-private alpha durable authority, `openDurableHistory`.
+Over injected Machine SQLite, clock and SHA-256 capabilities it owns a versioned
+single-file schema, distinct from the legacy Store, with:
 
-Development: https://github.com/mike-north/microdelta
+- the single logical writer lease, fence and clock high-water;
+- never-reused attempt identities with stable keys and intent digests;
+- staging and one-commit atomic publication with a current pointer per scoped subject;
+- immutable completed results with an exact scoped selected reader generated from their canonical payload;
+- separate acceptance records, namespaced by the explicitly named environment that recorded them;
+- environment namespaces within one store, so a trial run's attempts, heads,
+  candidates, acceptances and journal records never satisfy production;
+- recorded, fenced promotions that admit named exact results of one environment
+  into another of the same analysis, without moving or rewriting either one's history;
+- Run Supervision's operation journal: opaque versioned records per environment,
+  owner-named collection and key, committed atomically by compare-and-set under
+  writer fencing, with undeclared record formats and versions refused.
+
+It stores Resolution's provenance and Supervision's journal records as
+versioned opaque records and never decides reuse eligibility, freshness or
+operation meaning. The durable schema is at version 2. Files at any other
+version, including version 1 files written before environment-scoped
+acceptances, promotions and the journal existed, are rejected by version; stored
+data is never migrated by guessing. See the
+[package map](../../docs/package-map.md) and the
+[durable History evidence record](../../docs/validation/m3-durable-history-2026-09-27.md).

package/dist/api/history.alpha.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { AttemptConflictError, AttemptStateError, DuplicateRowError, FingerprintAlgorithmMismatchError, HistoryClockError, HistoryIntegrityError, HistorySchemaError, InvalidStorePatchError, JournalConflictError, JournalVersionError, MissingRowError, StaleWriterError, createMemoryStore, openDurableHistory } from './history.shared.alpha.js';
+export type { Divergence, FieldRow, Fingerprint, GenerationPatch, GenerationRow, GenerationState, IAbandonRequest, IAcceptanceRecord, IAcceptanceRequest, IAddressSegment, IAttemptRecord, IAttemptRequest, IAttemptState, IClockCapability, ICompletedEnvelope, ICompletedNavigationReader, ICompletedProjectionReader, ICompletedResultReader, ICompletedResultReference, IDurableHistory, IDurableHistoryOptions, IHistoryScope, IJournalAddress, IJournalCommit, IJournalDeclaration, IJournalFormat, IJournalQuery, IJournalRecord, IJournalWrite, IOperation, IOperationJournal, IPromotionQuery, IPromotionRecord, IPromotionRequest, IRecoveryOutcome, IResultVerification, IScopedSubject, ISelectedFact, ISelectedFingerprintRequest, ISelectedFingerprintResolution, ISelectedNode, ISelectedReadRequest, ISha256Capability, ISqliteCapability, ISqliteConnection, ISqliteRow, ISqliteRunResult, ISqliteStatement, ISqliteSynchronousResult, ISqliteValue, IStageRequest, IValueProjectionDescriptor, IValueProjectionFact, IValueProjectionMember, IValueProjectionTraversal, IVersionedRecord, IVersionedSubject, IWriterAcquisition, IWriterAcquisitionRequest, IWriterContention, IWriterLease, IWriterRenewal, Identity, MemoryStoreOptions, Outcome, Path, RecordedRead, ResultKey, Store, StoreMetadata, Subject, SubjectPatch, SubjectRow } from './history.shared.alpha.js';

package/dist/api/history.beta.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { DuplicateRowError, FingerprintAlgorithmMismatchError, InvalidStorePatchError, MissingRowError, createMemoryStore } from './history.shared.beta.js';
+export type { Divergence, FieldRow, Fingerprint, GenerationPatch, GenerationRow, GenerationState, Identity, MemoryStoreOptions, Outcome, Path, RecordedRead, ResultKey, Store, StoreMetadata, Subject, SubjectPatch, SubjectRow } from './history.shared.beta.js';

package/dist/api/history.conformance.store.alpha.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { storeConformance } from './history.shared.alpha.js';
+export type { StoreConformanceOptions, ValueReadProbe } from './history.shared.alpha.js';

package/dist/api/history.conformance.store.beta.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { storeConformance } from './history.shared.beta.js';
+export type { StoreConformanceOptions, ValueReadProbe } from './history.shared.beta.js';

package/dist/api/history.conformance.store.public.d.ts

@@ -0,0 +1,3 @@
+/** Entry-specific exports preserve one History type identity per release tier. */
+export { storeConformance } from './history.shared.public.js';
+export type { StoreConformanceOptions, ValueReadProbe } from './history.shared.public.js';

package/dist/api/history.conformance.store.raw.alpha.d.ts

@@ -0,0 +1,215 @@
+/** An immutable value node and its caller-computed fingerprint. @public */
+declare interface FieldRow {
+    key: ResultKey;
+    generation: number;
+    path: Path;
+    fingerprint: Fingerprint;
+    value: unknown;
+}
+
+/**
+ * Compatibility shapes for the scaffold row Store. Their names and string paths
+ * describe that storage port, not the target Value Semantics or identity model.
+ */
+/** Opaque, stable, hex-encoded content digest; equality is string equality. @public */
+declare type Fingerprint = string & {
+    readonly __fp: unique symbol;
+};
+
+/** Writable generation columns; tuple identity cannot change after insertion. @public */
+declare type GenerationPatch = Partial<Omit<GenerationRow, 'key' | 'generation'>>;
+
+/** A retained attempt, with lifecycle and numbering supplied by its caller. @public */
+declare interface GenerationRow {
+    key: ResultKey;
+    generation: number;
+    state: GenerationState;
+    reads: RecordedRead[];
+    identity: Identity | undefined;
+    startedAt: number;
+    endedAt: number | null;
+    cost: Record<string, number>;
+    arrival: string;
+    abandonReason?: 'error' | 'lease-expired' | 'refused';
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+
+/** Retained lifecycle states interpreted by repository and claim, not by storage. @public */
+declare type GenerationState = 'claimed' | 'current' | 'superseded' | 'abandoned';
+
+/**
+ * Compatibility identity shape stored in scaffold rows. It does not establish
+ * target subject identity, binding correspondence, or collection semantics.
+ * @public
+ */
+declare type Identity = {
+    kind: 'type';
+    type: string;
+    key: string;
+} | {
+    kind: 'step';
+    name: string;
+    inputs: readonly Identity[];
+} | {
+    kind: 'member';
+    of: Identity;
+    path: Path;
+} | {
+    kind: 'collection';
+    step: string;
+    source: Identity;
+};
+
+/** A legacy row-storage address, not the future structured semantic path. @public */
+declare type Path = string;
+
+/** Legacy persisted read rows; target observation encoding remains undecided. @public */
+declare type RecordedRead = {
+    kind: 'field';
+    arg: number;
+    path: Path;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'whole';
+    arg: number;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'memo';
+    key: ResultKey;
+    generation: number;
+};
+
+/** Complete storage tuple. Backends must preserve boundaries between all three parts. @public */
+declare type ResultKey = {
+    step: string;
+    revision: number;
+    subjectHash: string;
+};
+
+/**
+ * Storage mechanism for independent rows, with linearizable subject CAS.
+ * All inputs and returned rows are detached snapshots: caller mutation cannot
+ * alter persisted data. Values may only change by inserting another generation.
+ * There is no transaction spanning these methods; callers must not infer atomic
+ * claim/generation publication from the per-row CAS guarantee.
+ * @public
+ */
+declare interface Store {
+    /** Return detached format metadata; opening code must reject algorithm mismatches. */
+    meta(): Promise<StoreMetadata>;
+    /** Read a detached subject snapshot, or undefined for an absent tuple. */
+    getSubject(key: ResultKey): Promise<SubjectRow | undefined>;
+    /** Insert only; duplicate tuples reject, as do versions outside safe integers. */
+    putSubject(row: SubjectRow): Promise<void>;
+    /**
+     * Atomically apply a shallow column patch only when the stored version matches.
+     * Success increments that version once, even for an empty patch; a missing or
+     * stale row returns false without changes. Key/version properties reject at
+     * runtime, including extras passed from untyped JavaScript callers.
+     * An exhausted MAX_SAFE_INTEGER version rejects rather than reporting success
+     * without advancing the token. Neither rejection changes the stored row.
+     */
+    casSubject(key: ResultKey, expectedVersion: number, patch: SubjectPatch): Promise<boolean>;
+    /** Read a detached generation, or undefined for an absent tuple. */
+    getGeneration(key: ResultKey, generation: number): Promise<GenerationRow | undefined>;
+    /** Return detached rows for exactly this complete key; ordering is unspecified. */
+    listGenerations(key: ResultKey): Promise<GenerationRow[]>;
+    /** Insert only; generation numbers are supplied, never allocated by storage. */
+    putGeneration(row: GenerationRow): Promise<void>;
+    /** Patch an existing row; missing tuples and attempts to change its key reject. */
+    updateGeneration(key: ResultKey, generation: number, patch: GenerationPatch): Promise<void>;
+    /**
+     * Insert an atomic batch of immutable fields. Duplicate addresses, within the
+     * batch or already stored, reject the whole batch without inserting anything.
+     * This proposed storage refinement enforces retained-value immutability.
+     */
+    putFields(rows: FieldRow[]): Promise<void>;
+    /** Return requested field snapshots; absent paths are omitted. */
+    getFields(key: ResultKey, generation: number, paths: Path[]): Promise<FieldRow[]>;
+    /** Return requested fingerprints without reading/deserializing any field value. */
+    getFingerprints(key: ResultKey, generation: number, paths: Path[]): Promise<Map<Path, Fingerprint>>;
+    /**
+     * Query leases strictly less than now, oldest first, with at most limit rows.
+     * Zero limit returns no rows. This query never sweeps or changes a claim.
+     */
+    expiredClaims(now: number, limit: number): Promise<SubjectRow[]>;
+    /** Release resources owned by this store. */
+    close(): Promise<void>;
+}
+
+/**
+ * Register reusable backend qualification tests for SA-1 through SA-7.
+ * Register this from a Jest test module; the suite imports no concrete backend.
+ * Mutation tests enforce rev 9's retained-value isolation at the storage seam.
+ * This suite does not assert atomicity across subject, generation, and field rows:
+ * the supplied Store contract does not provide that operation.
+ * @public
+ */
+export declare function storeConformance(name: string, options: StoreConformanceOptions): void;
+
+/**
+ * Opens a fresh store for each test. The optional algorithm models persisted metadata
+ * at open time; factories must reject a mismatch with their runtime algorithm.
+ * Instrumentation is optional for third-party backends, but both shipped backends
+ * must provide it to qualify SA-3 without relying on wall-clock timing.
+ * @public
+ */
+export declare interface StoreConformanceOptions {
+    create(options?: {
+        fingerprintAlgorithm?: string;
+    }): Store | Promise<Store>;
+    fingerprintAlgorithm: string;
+    probeValueReads?(store: Store): ValueReadProbe;
+}
+
+/** Persisted format identifiers, checked before using a store's fingerprints. @public */
+declare interface StoreMetadata {
+    schemaVersion: number;
+    fingerprintAlgorithm: string;
+}
+
+/** Legacy row subject shape; future author-supplied subject identity is separate. @public */
+declare type Subject = Extract<Identity, {
+    kind: 'step';
+}>;
+
+/** Writable subject columns; the complete key and CAS token cannot be patched. @public */
+declare type SubjectPatch = Partial<Omit<SubjectRow, 'key' | 'version'>>;
+
+/**
+ * One compare-and-set row per complete result key. Repository owns generation
+ * meaning; claim owns lease meaning. Storage only preserves and patches columns.
+ * @public
+ */
+declare interface SubjectRow {
+    key: ResultKey;
+    subject: Subject;
+    /** Nonnegative safe-integer CAS token, incremented once per successful CAS. */
+    version: number;
+    currentGeneration: number | null;
+    claim: null | {
+        generation: number;
+        holder: string;
+        leaseUntil: number;
+        progress: {
+            fingerprint: Fingerprint;
+            value: unknown;
+        } | null;
+    };
+    durations: number[];
+}
+
+/**
+ * A backend's test-only counter at its actual value-read/deserialization boundary.
+ * The suite resets it after insertion and verifies a positive control with getFields.
+ * @public
+ */
+export declare interface ValueReadProbe {
+    reset(): void;
+    count(): number;
+}
+
+export { }

package/dist/api/history.conformance.store.raw.beta.d.ts

@@ -0,0 +1,215 @@
+/** An immutable value node and its caller-computed fingerprint. @public */
+declare interface FieldRow {
+    key: ResultKey;
+    generation: number;
+    path: Path;
+    fingerprint: Fingerprint;
+    value: unknown;
+}
+
+/**
+ * Compatibility shapes for the scaffold row Store. Their names and string paths
+ * describe that storage port, not the target Value Semantics or identity model.
+ */
+/** Opaque, stable, hex-encoded content digest; equality is string equality. @public */
+declare type Fingerprint = string & {
+    readonly __fp: unique symbol;
+};
+
+/** Writable generation columns; tuple identity cannot change after insertion. @public */
+declare type GenerationPatch = Partial<Omit<GenerationRow, 'key' | 'generation'>>;
+
+/** A retained attempt, with lifecycle and numbering supplied by its caller. @public */
+declare interface GenerationRow {
+    key: ResultKey;
+    generation: number;
+    state: GenerationState;
+    reads: RecordedRead[];
+    identity: Identity | undefined;
+    startedAt: number;
+    endedAt: number | null;
+    cost: Record<string, number>;
+    arrival: string;
+    abandonReason?: 'error' | 'lease-expired' | 'refused';
+    error?: {
+        message: string;
+        stack?: string;
+    };
+}
+
+/** Retained lifecycle states interpreted by repository and claim, not by storage. @public */
+declare type GenerationState = 'claimed' | 'current' | 'superseded' | 'abandoned';
+
+/**
+ * Compatibility identity shape stored in scaffold rows. It does not establish
+ * target subject identity, binding correspondence, or collection semantics.
+ * @public
+ */
+declare type Identity = {
+    kind: 'type';
+    type: string;
+    key: string;
+} | {
+    kind: 'step';
+    name: string;
+    inputs: readonly Identity[];
+} | {
+    kind: 'member';
+    of: Identity;
+    path: Path;
+} | {
+    kind: 'collection';
+    step: string;
+    source: Identity;
+};
+
+/** A legacy row-storage address, not the future structured semantic path. @public */
+declare type Path = string;
+
+/** Legacy persisted read rows; target observation encoding remains undecided. @public */
+declare type RecordedRead = {
+    kind: 'field';
+    arg: number;
+    path: Path;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'whole';
+    arg: number;
+    fingerprint: Fingerprint;
+} | {
+    kind: 'memo';
+    key: ResultKey;
+    generation: number;
+};
+
+/** Complete storage tuple. Backends must preserve boundaries between all three parts. @public */
+declare type ResultKey = {
+    step: string;
+    revision: number;
+    subjectHash: string;
+};
+
+/**
+ * Storage mechanism for independent rows, with linearizable subject CAS.
+ * All inputs and returned rows are detached snapshots: caller mutation cannot
+ * alter persisted data. Values may only change by inserting another generation.
+ * There is no transaction spanning these methods; callers must not infer atomic
+ * claim/generation publication from the per-row CAS guarantee.
+ * @public
+ */
+declare interface Store {
+    /** Return detached format metadata; opening code must reject algorithm mismatches. */
+    meta(): Promise<StoreMetadata>;
+    /** Read a detached subject snapshot, or undefined for an absent tuple. */
+    getSubject(key: ResultKey): Promise<SubjectRow | undefined>;
+    /** Insert only; duplicate tuples reject, as do versions outside safe integers. */
+    putSubject(row: SubjectRow): Promise<void>;
+    /**
+     * Atomically apply a shallow column patch only when the stored version matches.
+     * Success increments that version once, even for an empty patch; a missing or
+     * stale row returns false without changes. Key/version properties reject at
+     * runtime, including extras passed from untyped JavaScript callers.
+     * An exhausted MAX_SAFE_INTEGER version rejects rather than reporting success
+     * without advancing the token. Neither rejection changes the stored row.
+     */
+    casSubject(key: ResultKey, expectedVersion: number, patch: SubjectPatch): Promise<boolean>;
+    /** Read a detached generation, or undefined for an absent tuple. */
+    getGeneration(key: ResultKey, generation: number): Promise<GenerationRow | undefined>;
+    /** Return detached rows for exactly this complete key; ordering is unspecified. */
+    listGenerations(key: ResultKey): Promise<GenerationRow[]>;
+    /** Insert only; generation numbers are supplied, never allocated by storage. */
+    putGeneration(row: GenerationRow): Promise<void>;
+    /** Patch an existing row; missing tuples and attempts to change its key reject. */
+    updateGeneration(key: ResultKey, generation: number, patch: GenerationPatch): Promise<void>;
+    /**
+     * Insert an atomic batch of immutable fields. Duplicate addresses, within the
+     * batch or already stored, reject the whole batch without inserting anything.
+     * This proposed storage refinement enforces retained-value immutability.
+     */
+    putFields(rows: FieldRow[]): Promise<void>;
+    /** Return requested field snapshots; absent paths are omitted. */
+    getFields(key: ResultKey, generation: number, paths: Path[]): Promise<FieldRow[]>;
+    /** Return requested fingerprints without reading/deserializing any field value. */
+    getFingerprints(key: ResultKey, generation: number, paths: Path[]): Promise<Map<Path, Fingerprint>>;
+    /**
+     * Query leases strictly less than now, oldest first, with at most limit rows.
+     * Zero limit returns no rows. This query never sweeps or changes a claim.
+     */
+    expiredClaims(now: number, limit: number): Promise<SubjectRow[]>;
+    /** Release resources owned by this store. */
+    close(): Promise<void>;
+}
+
+/**
+ * Register reusable backend qualification tests for SA-1 through SA-7.
+ * Register this from a Jest test module; the suite imports no concrete backend.
+ * Mutation tests enforce rev 9's retained-value isolation at the storage seam.
+ * This suite does not assert atomicity across subject, generation, and field rows:
+ * the supplied Store contract does not provide that operation.
+ * @public
+ */
+export declare function storeConformance(name: string, options: StoreConformanceOptions): void;
+
+/**
+ * Opens a fresh store for each test. The optional algorithm models persisted metadata
+ * at open time; factories must reject a mismatch with their runtime algorithm.
+ * Instrumentation is optional for third-party backends, but both shipped backends
+ * must provide it to qualify SA-3 without relying on wall-clock timing.
+ * @public
+ */
+export declare interface StoreConformanceOptions {
+    create(options?: {
+        fingerprintAlgorithm?: string;
+    }): Store | Promise<Store>;
+    fingerprintAlgorithm: string;
+    probeValueReads?(store: Store): ValueReadProbe;
+}
+
+/** Persisted format identifiers, checked before using a store's fingerprints. @public */
+declare interface StoreMetadata {
+    schemaVersion: number;
+    fingerprintAlgorithm: string;
+}
+
+/** Legacy row subject shape; future author-supplied subject identity is separate. @public */
+declare type Subject = Extract<Identity, {
+    kind: 'step';
+}>;
+
+/** Writable subject columns; the complete key and CAS token cannot be patched. @public */
+declare type SubjectPatch = Partial<Omit<SubjectRow, 'key' | 'version'>>;
+
+/**
+ * One compare-and-set row per complete result key. Repository owns generation
+ * meaning; claim owns lease meaning. Storage only preserves and patches columns.
+ * @public
+ */
+declare interface SubjectRow {
+    key: ResultKey;
+    subject: Subject;
+    /** Nonnegative safe-integer CAS token, incremented once per successful CAS. */
+    version: number;
+    currentGeneration: number | null;
+    claim: null | {
+        generation: number;
+        holder: string;
+        leaseUntil: number;
+        progress: {
+            fingerprint: Fingerprint;
+            value: unknown;
+        } | null;
+    };
+    durations: number[];
+}
+
+/**
+ * A backend's test-only counter at its actual value-read/deserialization boundary.
+ * The suite resets it after insertion and verifies a positive control with getFields.
+ * @public
+ */
+export declare interface ValueReadProbe {
+    reset(): void;
+    count(): number;
+}
+
+export { }