@manifesto-ai/lineage 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Manifesto AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,44 @@
+# @manifesto-ai/lineage
+
+> Split-native lineage protocol for identity, history, and sealing.
+
+`@manifesto-ai/lineage` is the package to use when you need deterministic world identity, branch history, and snapshot sealing directly. It is the lower substrate that `@manifesto-ai/governance` and `@manifesto-ai/world` build on.
+
+> **Current Contract Note:** The current public package contract is documented in [docs/lineage-SPEC-2.0.0v.md](docs/lineage-SPEC-2.0.0v.md). The v1.x lineage docs remain available as historical split-era baselines.
+
+## What This Package Owns
+
+- snapshot and world identity computation
+- branch, head, and epoch reads
+- seal protocol and prepared commits
+- lineage persistence and replay
+- in-memory lineage storage
+
+## When to Use It
+
+Use `@manifesto-ai/lineage` directly when you want:
+
+- world history without governance
+- deterministic identity and resume support
+- custom persistence or replay tooling
+- isolated tests for hashing, branch, and sealing behavior
+
+## Quick Start
+
+```typescript
+import {
+  createInMemoryLineageStore,
+  createLineageService,
+} from "@manifesto-ai/lineage";
+
+const store = createInMemoryLineageStore();
+const lineage = createLineageService(store);
+```
+
+## Docs
+
+- [Docs Landing](docs/README.md)
+- [Lineage Guide](docs/GUIDE.md)
+- [Lineage Specification](docs/lineage-SPEC-2.0.0v.md)
+- [Historical v1 Baseline](docs/lineage-SPEC-1.0.1v.md)
+- [VERSION-INDEX](docs/VERSION-INDEX.md)

package/dist/index.d.ts

@@ -0,0 +1,411 @@
+import { Snapshot, Patch, ErrorValue, Requirement } from '@manifesto-ai/core';
+export { Patch, Snapshot } from '@manifesto-ai/core';
+
+type WorldId = string;
+type BranchId = string;
+type SchemaHash = string;
+type ProvenanceRef = string;
+type AttemptId = string;
+interface ArtifactRef {
+    readonly uri: string;
+    readonly hash: string;
+}
+type TerminalStatus = "completed" | "failed";
+interface CurrentErrorSignature {
+    readonly code: string;
+    readonly source: {
+        readonly actionId: string;
+        readonly nodePath: string;
+    };
+}
+interface SnapshotHashInput {
+    readonly data: Record<string, unknown>;
+    readonly system: {
+        readonly terminalStatus: TerminalStatus;
+        readonly currentError: CurrentErrorSignature | null;
+        readonly pendingDigest: string;
+    };
+}
+interface World {
+    readonly worldId: WorldId;
+    readonly schemaHash: SchemaHash;
+    readonly snapshotHash: string;
+    readonly parentWorldId: WorldId | null;
+    readonly terminalStatus: TerminalStatus;
+}
+interface WorldEdge {
+    readonly edgeId: string;
+    readonly from: WorldId;
+    readonly to: WorldId;
+}
+interface WorldLineage {
+    readonly genesis: WorldId;
+    readonly worlds: ReadonlyMap<WorldId, World>;
+    readonly edges: ReadonlyMap<string, WorldEdge>;
+}
+interface PersistedPatchDeltaV2 {
+    readonly _patchFormat: 2;
+    readonly patches: readonly Patch[];
+}
+interface SealGenesisInput {
+    readonly schemaHash: SchemaHash;
+    readonly terminalSnapshot: Snapshot;
+    readonly createdAt: number;
+    readonly branchName?: string;
+    readonly proposalRef?: ProvenanceRef;
+    readonly traceRef?: ArtifactRef;
+}
+interface SealNextInput {
+    readonly schemaHash: SchemaHash;
+    readonly baseWorldId: WorldId;
+    readonly branchId: BranchId;
+    readonly terminalSnapshot: Snapshot;
+    readonly createdAt: number;
+    readonly patchDelta?: PersistedPatchDeltaV2;
+    readonly proposalRef?: ProvenanceRef;
+    readonly decisionRef?: ProvenanceRef;
+    readonly traceRef?: ArtifactRef;
+}
+interface BranchInfo {
+    readonly id: BranchId;
+    readonly name: string;
+    readonly head: WorldId;
+    readonly tip: WorldId;
+    readonly headAdvancedAt: number;
+    readonly epoch: number;
+    readonly schemaHash: SchemaHash;
+    readonly createdAt: number;
+}
+interface PersistedBranchEntry {
+    readonly id: BranchId;
+    readonly name: string;
+    readonly head: WorldId;
+    readonly tip: WorldId;
+    readonly headAdvancedAt: number;
+    readonly epoch: number;
+    readonly schemaHash: SchemaHash;
+    readonly createdAt: number;
+}
+interface PersistedBranchState {
+    readonly branches: readonly PersistedBranchEntry[];
+    readonly activeBranchId: BranchId;
+}
+interface WorldHead {
+    readonly worldId: WorldId;
+    readonly branchId: BranchId;
+    readonly branchName: string;
+    readonly createdAt: number;
+    readonly schemaHash: SchemaHash;
+}
+interface BranchSwitchResult {
+    readonly previousBranchId: BranchId;
+    readonly targetBranchId: BranchId;
+    readonly sourceBranchEpochAfter: number;
+}
+interface PreparedBranchMutation {
+    readonly kind: "advance";
+    readonly branchId: BranchId;
+    readonly expectedHead: WorldId;
+    readonly nextHead: WorldId;
+    readonly headAdvanced: boolean;
+    readonly expectedTip: WorldId;
+    readonly nextTip: WorldId;
+    readonly headAdvancedAt: number | null;
+    readonly expectedEpoch: number;
+    readonly nextEpoch: number;
+}
+interface PreparedBranchBootstrap {
+    readonly kind: "bootstrap";
+    readonly branch: PersistedBranchEntry;
+    readonly activeBranchId: BranchId;
+}
+type PreparedBranchChange = PreparedBranchMutation | PreparedBranchBootstrap;
+interface SealAttempt {
+    readonly attemptId: AttemptId;
+    readonly worldId: WorldId;
+    readonly branchId: BranchId;
+    readonly baseWorldId: WorldId | null;
+    readonly parentWorldId: WorldId | null;
+    readonly proposalRef?: ProvenanceRef;
+    readonly decisionRef?: ProvenanceRef;
+    readonly createdAt: number;
+    readonly traceRef?: ArtifactRef;
+    readonly patchDelta?: PersistedPatchDeltaV2;
+    readonly reused: boolean;
+}
+interface PreparedLineageRecords {
+    readonly worldId: WorldId;
+    readonly world: World;
+    readonly terminalSnapshot: Snapshot;
+    readonly hashInput: SnapshotHashInput;
+    readonly attempt: SealAttempt;
+}
+interface PreparedGenesisCommit extends PreparedLineageRecords {
+    readonly kind: "genesis";
+    readonly branchId: BranchId;
+    readonly terminalStatus: "completed";
+    readonly edge: null;
+    readonly branchChange: PreparedBranchBootstrap;
+}
+interface PreparedNextCommit extends PreparedLineageRecords {
+    readonly kind: "next";
+    readonly branchId: BranchId;
+    readonly terminalStatus: TerminalStatus;
+    readonly edge: WorldEdge;
+    readonly forkCreated: boolean;
+    readonly branchChange: PreparedBranchMutation;
+}
+type PreparedLineageCommit = PreparedGenesisCommit | PreparedNextCommit;
+interface LineageStore {
+    putWorld(world: World): Promise<void>;
+    getWorld(worldId: WorldId): Promise<World | null>;
+    putSnapshot(worldId: WorldId, snapshot: Snapshot): Promise<void>;
+    getSnapshot(worldId: WorldId): Promise<Snapshot | null>;
+    putAttempt(attempt: SealAttempt): Promise<void>;
+    getAttempts(worldId: WorldId): Promise<readonly SealAttempt[]>;
+    getAttemptsByBranch(branchId: BranchId): Promise<readonly SealAttempt[]>;
+    putHashInput?(snapshotHash: string, input: SnapshotHashInput): Promise<void>;
+    getHashInput?(snapshotHash: string): Promise<SnapshotHashInput | null>;
+    putEdge(edge: WorldEdge): Promise<void>;
+    getEdges(worldId: WorldId): Promise<readonly WorldEdge[]>;
+    getBranchHead(branchId: BranchId): Promise<WorldId | null>;
+    getBranchTip(branchId: BranchId): Promise<WorldId | null>;
+    getBranchEpoch(branchId: BranchId): Promise<number>;
+    mutateBranch(mutation: PreparedBranchMutation): Promise<void>;
+    putBranch(branch: PersistedBranchEntry): Promise<void>;
+    getBranches(): Promise<readonly PersistedBranchEntry[]>;
+    getActiveBranchId(): Promise<BranchId | null>;
+    switchActiveBranch(sourceBranchId: BranchId, targetBranchId: BranchId): Promise<void>;
+    commitPrepared(prepared: PreparedLineageCommit): Promise<void>;
+}
+interface LineageService {
+    prepareSealGenesis(input: SealGenesisInput): Promise<PreparedGenesisCommit>;
+    prepareSealNext(input: SealNextInput): Promise<PreparedNextCommit>;
+    commitPrepared(prepared: PreparedLineageCommit): Promise<void>;
+    createBranch(name: string, headWorldId: WorldId): Promise<BranchId>;
+    getBranch(branchId: BranchId): Promise<BranchInfo | null>;
+    getBranches(): Promise<readonly BranchInfo[]>;
+    getActiveBranch(): Promise<BranchInfo>;
+    switchActiveBranch(targetBranchId: BranchId): Promise<BranchSwitchResult>;
+    getWorld(worldId: WorldId): Promise<World | null>;
+    getSnapshot(worldId: WorldId): Promise<Snapshot | null>;
+    getAttempts(worldId: WorldId): Promise<readonly SealAttempt[]>;
+    getAttemptsByBranch(branchId: BranchId): Promise<readonly SealAttempt[]>;
+    getLineage(): Promise<WorldLineage>;
+    getHeads(): Promise<readonly WorldHead[]>;
+    getLatestHead(): Promise<WorldHead | null>;
+    restore(worldId: WorldId): Promise<Snapshot>;
+}
+
+declare function computeHash(value: unknown): string;
+declare function isPlatformNamespace(key: string): boolean;
+declare function stripPlatformNamespaces(data: Record<string, unknown> | null | undefined): Record<string, unknown>;
+declare function deriveTerminalStatus(snapshot: Snapshot): TerminalStatus;
+declare function normalizeContext(ctx: Record<string, unknown>): Record<string, unknown> | undefined;
+declare function toCurrentErrorSignature(error: ErrorValue): CurrentErrorSignature;
+declare function computePendingDigest(pendingRequirements: readonly Requirement[]): string;
+declare function createSnapshotHashInput(snapshot: Snapshot): SnapshotHashInput;
+declare function computeSnapshotHash(snapshot: Snapshot): string;
+declare function computeWorldId(schemaHash: string, snapshotHash: string, parentWorldId: WorldId | null): WorldId;
+
+interface WorldRecordResult {
+    readonly world: World;
+    readonly hashInput: SnapshotHashInput;
+    readonly worldId: WorldId;
+}
+declare function createWorldRecord(schemaHash: string, terminalSnapshot: Snapshot, parentWorldId: WorldId | null): WorldRecordResult;
+declare function createWorldEdge(from: WorldId, to: WorldId): WorldEdge;
+declare function createGenesisBranchEntry(input: SealGenesisInput, worldId: WorldId): PersistedBranchEntry;
+declare function createSealGenesisAttempt(branchId: BranchId, worldId: WorldId, input: SealGenesisInput): SealAttempt;
+declare function createSealNextAttempt(branchId: BranchId, worldId: WorldId, parentWorldId: WorldId, input: SealNextInput): SealAttempt;
+
+declare function toBranchInfo(entry: PersistedBranchEntry): BranchInfo;
+declare function toWorldHead(branch: PersistedBranchEntry, world: World): WorldHead;
+declare function getHeadsFromStore(store: LineageStore): Promise<readonly WorldHead[]>;
+declare function selectLatestHead(heads: readonly WorldHead[]): WorldHead | null;
+declare function restoreSnapshot(store: LineageStore, worldId: WorldId): Promise<Snapshot>;
+declare function buildWorldLineage(store: LineageStore): Promise<WorldLineage>;
+
+type InMemoryLineageStoreState = {
+    worlds: Map<WorldId, World>;
+    snapshots: Map<WorldId, Snapshot>;
+    hashInputs: Map<string, SnapshotHashInput>;
+    edges: Map<string, WorldEdge>;
+    edgesByWorld: Map<WorldId, Set<string>>;
+    attempts: Map<string, SealAttempt>;
+    attemptsByWorld: Map<WorldId, string[]>;
+    attemptsByBranch: Map<BranchId, string[]>;
+    branches: Map<BranchId, PersistedBranchEntry>;
+    activeBranchId: BranchId | null;
+};
+declare class InMemoryLineageStore implements LineageStore {
+    private readonly worlds;
+    private readonly snapshots;
+    private readonly hashInputs;
+    private readonly edges;
+    private readonly edgesByWorld;
+    private readonly attempts;
+    private readonly attemptsByWorld;
+    private readonly attemptsByBranch;
+    private readonly branches;
+    private activeBranchId;
+    putWorld(world: World): Promise<void>;
+    getWorld(worldId: WorldId): Promise<World | null>;
+    putSnapshot(worldId: WorldId, snapshot: Snapshot): Promise<void>;
+    getSnapshot(worldId: WorldId): Promise<Snapshot | null>;
+    putAttempt(attempt: SealAttempt): Promise<void>;
+    getAttempts(worldId: WorldId): Promise<readonly SealAttempt[]>;
+    getAttemptsByBranch(branchId: BranchId): Promise<readonly SealAttempt[]>;
+    putHashInput(snapshotHash: string, input: SnapshotHashInput): Promise<void>;
+    getHashInput(snapshotHash: string): Promise<SnapshotHashInput | null>;
+    putEdge(edge: WorldEdge): Promise<void>;
+    getEdges(worldId: WorldId): Promise<readonly WorldEdge[]>;
+    getBranchHead(branchId: BranchId): Promise<WorldId | null>;
+    getBranchTip(branchId: BranchId): Promise<WorldId | null>;
+    getBranchEpoch(branchId: BranchId): Promise<number>;
+    mutateBranch(mutation: PreparedBranchMutation): Promise<void>;
+    putBranch(branch: PersistedBranchEntry): Promise<void>;
+    getBranches(): Promise<readonly PersistedBranchEntry[]>;
+    getActiveBranchId(): Promise<BranchId | null>;
+    switchActiveBranch(sourceBranchId: BranchId, targetBranchId: BranchId): Promise<void>;
+    commitPrepared(prepared: PreparedLineageCommit): Promise<void>;
+    listWorlds(): readonly World[];
+    listEdges(): readonly WorldEdge[];
+    snapshotState(): InMemoryLineageStoreState;
+    restoreState(state: InMemoryLineageStoreState): void;
+    private indexEdge;
+    private indexAttempt;
+}
+declare function createInMemoryLineageStore(): InMemoryLineageStore;
+
+declare class DefaultLineageService implements LineageService {
+    private readonly store;
+    constructor(store: LineageStore);
+    prepareSealGenesis(input: SealGenesisInput): Promise<{
+        kind: "genesis";
+        branchId: string;
+        worldId: string;
+        world: World;
+        terminalSnapshot: {
+            data: unknown;
+            computed: Record<string, unknown>;
+            system: {
+                status: "error" | "idle" | "computing" | "pending";
+                lastError: {
+                    code: string;
+                    message: string;
+                    source: {
+                        actionId: string;
+                        nodePath: string;
+                    };
+                    timestamp: number;
+                    context?: Record<string, unknown> | undefined;
+                } | null;
+                pendingRequirements: {
+                    id: string;
+                    type: string;
+                    params: Record<string, unknown>;
+                    actionId: string;
+                    flowPosition: {
+                        nodePath: string;
+                        snapshotVersion: number;
+                    };
+                    createdAt: number;
+                }[];
+                currentAction: string | null;
+            };
+            input: unknown;
+            meta: {
+                version: number;
+                timestamp: number;
+                randomSeed: string;
+                schemaHash: string;
+            };
+        };
+        hashInput: SnapshotHashInput;
+        attempt: SealAttempt;
+        terminalStatus: "completed";
+        edge: null;
+        branchChange: {
+            kind: "bootstrap";
+            branch: PersistedBranchEntry;
+            activeBranchId: string;
+        };
+    }>;
+    prepareSealNext(input: SealNextInput): Promise<{
+        kind: "next";
+        branchId: string;
+        worldId: string;
+        world: World;
+        terminalSnapshot: {
+            data: unknown;
+            computed: Record<string, unknown>;
+            system: {
+                status: "error" | "idle" | "computing" | "pending";
+                lastError: {
+                    code: string;
+                    message: string;
+                    source: {
+                        actionId: string;
+                        nodePath: string;
+                    };
+                    timestamp: number;
+                    context?: Record<string, unknown> | undefined;
+                } | null;
+                pendingRequirements: {
+                    id: string;
+                    type: string;
+                    params: Record<string, unknown>;
+                    actionId: string;
+                    flowPosition: {
+                        nodePath: string;
+                        snapshotVersion: number;
+                    };
+                    createdAt: number;
+                }[];
+                currentAction: string | null;
+            };
+            input: unknown;
+            meta: {
+                version: number;
+                timestamp: number;
+                randomSeed: string;
+                schemaHash: string;
+            };
+        };
+        hashInput: SnapshotHashInput;
+        attempt: SealAttempt;
+        terminalStatus: TerminalStatus;
+        edge: WorldEdge;
+        forkCreated: boolean;
+        branchChange: {
+            kind: "advance";
+            branchId: string;
+            expectedHead: string;
+            nextHead: string;
+            headAdvanced: boolean;
+            expectedTip: string;
+            nextTip: string;
+            headAdvancedAt: number | null;
+            expectedEpoch: number;
+            nextEpoch: number;
+        };
+    }>;
+    commitPrepared(prepared: Parameters<LineageService["commitPrepared"]>[0]): Promise<void>;
+    createBranch(name: string, headWorldId: WorldId): Promise<BranchId>;
+    getBranch(branchId: BranchId): Promise<BranchInfo | null>;
+    getBranches(): Promise<readonly BranchInfo[]>;
+    getActiveBranch(): Promise<BranchInfo>;
+    switchActiveBranch(targetBranchId: BranchId): Promise<BranchSwitchResult>;
+    getWorld(worldId: WorldId): Promise<World | null>;
+    getSnapshot(worldId: WorldId): Promise<Snapshot | null>;
+    getAttempts(worldId: WorldId): Promise<readonly SealAttempt[]>;
+    getAttemptsByBranch(branchId: BranchId): Promise<readonly SealAttempt[]>;
+    getLineage(): Promise<WorldLineage>;
+    getHeads(): Promise<readonly WorldHead[]>;
+    getLatestHead(): Promise<WorldHead | null>;
+    restore(worldId: WorldId): Promise<Snapshot>;
+}
+declare function createLineageService(store: LineageStore): LineageService;
+
+export { type ArtifactRef, type AttemptId, type BranchId, type BranchInfo, type BranchSwitchResult, type CurrentErrorSignature, DefaultLineageService, InMemoryLineageStore, type LineageService, type LineageStore, type PersistedBranchEntry, type PersistedBranchState, type PersistedPatchDeltaV2, type PreparedBranchBootstrap, type PreparedBranchChange, type PreparedBranchMutation, type PreparedGenesisCommit, type PreparedLineageCommit, type PreparedLineageRecords, type PreparedNextCommit, type ProvenanceRef, type SchemaHash, type SealAttempt, type SealGenesisInput, type SealNextInput, type SnapshotHashInput, type TerminalStatus, type World, type WorldEdge, type WorldHead, type WorldId, type WorldLineage, type WorldRecordResult, buildWorldLineage, computeHash, computePendingDigest, computeSnapshotHash, computeWorldId, createGenesisBranchEntry, createInMemoryLineageStore, createLineageService, createSealGenesisAttempt, createSealNextAttempt, createSnapshotHashInput, createWorldEdge, createWorldRecord, deriveTerminalStatus, getHeadsFromStore, isPlatformNamespace, normalizeContext, restoreSnapshot, selectLatestHead, stripPlatformNamespaces, toBranchInfo, toCurrentErrorSignature, toWorldHead };