@microdelta/history 0.0.0 → 0.1.0

package/dist/src/durable/locator.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Exact completed-result locators of the durable authority (RES-002). A
+ * locator names one immutable result together with the logical store,
+ * analysis and environment that scope it, so resolution never guesses the
+ * current environment and never consults a current pointer. The grammar is
+ * versioned and canonical: `mdh1|` followed by the JSON array
+ * `[logicalStore, analysis, environment, resultId]`. Any other text, including
+ * a noncanonical spelling of the same components, is an integrity failure.
+ * @packageDocumentation
+ */
+import type { ICompletedResultReference } from '../completed-results.js';
+/** The decoded components of one exact locator. */
+export interface ILocatorParts {
+    /** The logical store that issued the result. */
+    readonly logicalStore: string;
+    /** The analysis scoping the result. */
+    readonly analysis: string;
+    /** The environment scoping the result. */
+    readonly environment: string;
+    /** The store-wide result identity, equal to its producing attempt identity. */
+    readonly resultId: number;
+}
+/** Issue the frozen exact reference for one result. */
+export declare function referenceFor(parts: ILocatorParts): ICompletedResultReference;
+/**
+ * Decode an exact reference. The reference must be a completed-result
+ * reference whose locator uses this grammar exactly; the caller then checks
+ * the components against the store and its rows.
+ */
+export declare function parseReference(reference: unknown): ILocatorParts;
+//# sourceMappingURL=locator.d.ts.map

package/dist/src/durable/locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../../src/durable/locator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AAMzE,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,yBAAyB,CAG5E;AAOD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,OAAO,GAAG,aAAa,CA8BhE"}

package/dist/src/durable/locator.js

@@ -0,0 +1,50 @@
+import { HistoryIntegrityError } from './errors.js';
+/** The only locator grammar version this implementation issues or accepts. */
+const locatorPrefix = 'mdh1|';
+/** Issue the frozen exact reference for one result. */
+export function referenceFor(parts) {
+    const locator = `${locatorPrefix}${JSON.stringify([parts.logicalStore, parts.analysis, parts.environment, parts.resultId])}`;
+    return Object.freeze({ kind: 'completed-result', locator });
+}
+/** Whether a decoded component is a non-empty string. */
+function isName(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Decode an exact reference. The reference must be a completed-result
+ * reference whose locator uses this grammar exactly; the caller then checks
+ * the components against the store and its rows.
+ */
+export function parseReference(reference) {
+    if (typeof reference !== 'object' || reference === null) {
+        throw new HistoryIntegrityError('A completed-result reference must be an object');
+    }
+    const kind = Reflect.get(reference, 'kind');
+    const locator = Reflect.get(reference, 'locator');
+    if (kind !== 'completed-result' || typeof locator !== 'string') {
+        throw new HistoryIntegrityError('A completed-result reference needs kind "completed-result" and a string locator');
+    }
+    if (!locator.startsWith(locatorPrefix)) {
+        throw new HistoryIntegrityError(`Unsupported completed-result locator grammar: ${JSON.stringify(locator.slice(0, 8))}`);
+    }
+    let decoded;
+    try {
+        decoded = JSON.parse(locator.slice(locatorPrefix.length));
+    }
+    catch {
+        throw new HistoryIntegrityError('Malformed completed-result locator');
+    }
+    if (!Array.isArray(decoded) || decoded.length !== 4) {
+        throw new HistoryIntegrityError('Malformed completed-result locator');
+    }
+    const [logicalStore, analysis, environment, resultId] = decoded;
+    if (!isName(logicalStore) || !isName(analysis) || !isName(environment) || typeof resultId !== 'number' || !Number.isSafeInteger(resultId) || resultId <= 0) {
+        throw new HistoryIntegrityError('Malformed completed-result locator components');
+    }
+    const parts = { logicalStore, analysis, environment, resultId };
+    if (referenceFor(parts).locator !== locator) {
+        throw new HistoryIntegrityError('Noncanonical completed-result locator');
+    }
+    return parts;
+}
+//# sourceMappingURL=locator.js.map

package/dist/src/durable/locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.js","sourceRoot":"","sources":["../../../src/durable/locator.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,8EAA8E;AAC9E,MAAM,aAAa,GAAG,OAAO,CAAC;AAc9B,uDAAuD;AACvD,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,MAAM,OAAO,GAAG,GAAG,aAAa,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;IAC7H,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,yDAAyD;AACzD,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAkB;IAC/C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACxD,MAAM,IAAI,qBAAqB,CAAC,gDAAgD,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,IAAI,GAAY,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACrD,MAAM,OAAO,GAAY,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,IAAI,KAAK,kBAAkB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC/D,MAAM,IAAI,qBAAqB,CAAC,iFAAiF,CAAC,CAAC;IACrH,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,qBAAqB,CAAC,iDAAiD,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1H,CAAC;IACD,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAC;IACxE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,qBAAqB,CAAC,oCAAoC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,CAAC,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,CAAC,GAAG,OAA6B,CAAC;IACtF,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC3J,MAAM,IAAI,qBAAqB,CAAC,+CAA+C,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,KAAK,GAAkB,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;IAC/E,IAAI,YAAY,CAAC,KAAK,CAAC,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;QAC5C,MAAM,IAAI,qBAAqB,CAAC,uCAAuC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/durable/schema.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The versioned production schema of History's durable authority. It is
+ * distinct from the legacy row Store's compatibility schema and from the
+ * EXP-3 and nested-read experiment layouts. The schema is defined as an exact
+ * list of SQL objects; a database is usable only when it contains exactly
+ * these objects and one identity row naming this schema, version and logical
+ * store. Anything else (empty aside) is rejected before work: History never
+ * guesses a migration from unknown, incomplete or foreign storage.
+ *
+ * Immutability of completed history is enforced in storage by triggers:
+ * results, their generated index, dependencies, acceptance records and the
+ * identity row cannot be updated or deleted, and attempts, current pointers
+ * and writer/sequence rows cannot be deleted. No reclamation exists (RES-006).
+ * @packageDocumentation
+ */
+import type { ISqliteConnection } from '@microdelta/machine';
+/** The schema identity recorded in every durable History file. */
+export declare const schemaName = "microdelta.history.durable";
+/** The only schema version this implementation reads or writes. */
+export declare const schemaVersion = 1;
+/**
+ * Create the schema in one transaction when the database has no objects,
+ * then validate it. Validation requires exactly the expected objects with
+ * their exact definitions and a single identity row naming this schema,
+ * version and the requested logical store.
+ */
+export declare function initializeSchema(connection: ISqliteConnection, logicalStore: string): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/src/durable/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/durable/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAc,MAAM,qBAAqB,CAAC;AAOzE,kEAAkE;AAClE,eAAO,MAAM,UAAU,+BAA+B,CAAC;AAEvD,mEAAmE;AACnE,eAAO,MAAM,aAAa,IAAI,CAAC;AAiN/B;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAqB1F"}

package/dist/src/durable/schema.js

@@ -0,0 +1,266 @@
+import { HistorySchemaError } from './errors.js';
+/** Identity tag for embedded SQL; the text is passed through unchanged. */
+const sql = String.raw;
+/** The schema identity recorded in every durable History file. */
+export const schemaName = 'microdelta.history.durable';
+/** The only schema version this implementation reads or writes. */
+export const schemaVersion = 1;
+/** Tables whose rows may never be updated or deleted once written. */
+const immutableTables = [
+    'history_identity',
+    'history_results',
+    'history_dependencies',
+    'history_nodes',
+    'history_edges',
+    'history_addresses',
+    'history_acceptances',
+    'history_acceptance_dependencies',
+];
+/** Tables whose rows may change state but are never deleted. */
+const retainedTables = ['history_writer', 'history_sequences', 'history_attempts', 'history_current'];
+/**
+ * Every schema object, one statement each, in creation order. Stored
+ * definitions are compared with these texts after whitespace normalization.
+ */
+const schemaObjects = [
+    // One row naming the schema, its version and the logical store this file holds.
+    sql `CREATE TABLE history_identity (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    schema_name TEXT NOT NULL,
+    schema_version INTEGER NOT NULL,
+    logical_store TEXT NOT NULL CHECK (length(logical_store) > 0)
+  ) STRICT`,
+    // The single logical writer: holder, monotonically increasing fence, lease
+    // expiry and the persisted clock high-water, all in History's clock domain.
+    sql `CREATE TABLE history_writer (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    last_fence INTEGER NOT NULL CHECK (last_fence >= 0),
+    holder TEXT CHECK (holder IS NULL OR length(holder) > 0),
+    expires_at INTEGER NOT NULL CHECK (expires_at >= 0),
+    time_high_water INTEGER NOT NULL CHECK (time_high_water >= 0)
+  ) STRICT`,
+    // Store-wide counters; issued values are never reissued (PUB-003).
+    sql `CREATE TABLE history_sequences (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    last_attempt INTEGER NOT NULL CHECK (last_attempt >= 0),
+    last_publication INTEGER NOT NULL CHECK (last_publication >= 0),
+    last_acceptance INTEGER NOT NULL CHECK (last_acceptance >= 0)
+  ) STRICT`,
+    // Durable attempts with their stable key, intent digest, staged candidate
+    // content and failure evidence. Staged content is never a completed result.
+    sql `CREATE TABLE history_attempts (
+    attempt_id INTEGER PRIMARY KEY CHECK (attempt_id > 0),
+    analysis TEXT NOT NULL CHECK (length(analysis) > 0),
+    environment TEXT NOT NULL CHECK (length(environment) > 0),
+    subject TEXT NOT NULL CHECK (length(subject) > 0),
+    version INTEGER NOT NULL CHECK (version > 0),
+    attempt_key TEXT NOT NULL CHECK (length(attempt_key) > 0),
+    intent_digest TEXT NOT NULL CHECK (length(intent_digest) > 0),
+    state TEXT NOT NULL CHECK (state IN ('allocated', 'staged', 'completed', 'failed', 'interrupted')),
+    allocated_fence INTEGER NOT NULL CHECK (allocated_fence > 0),
+    ended_fence INTEGER CHECK (ended_fence IS NULL OR ended_fence > 0),
+    staged_payload TEXT,
+    staged_provenance_format TEXT,
+    staged_provenance_version INTEGER,
+    staged_provenance TEXT,
+    outcome_format TEXT,
+    outcome_version INTEGER,
+    outcome TEXT,
+    UNIQUE (analysis, environment, subject, attempt_key),
+    UNIQUE (attempt_id, analysis, environment, subject, version),
+    CHECK ((staged_payload IS NULL) = (staged_provenance IS NULL)
+      AND (staged_payload IS NULL) = (staged_provenance_format IS NULL)
+      AND (staged_payload IS NULL) = (staged_provenance_version IS NULL)),
+    CHECK ((outcome IS NULL) = (outcome_format IS NULL) AND (outcome IS NULL) = (outcome_version IS NULL)),
+    CHECK ((state = 'allocated' AND staged_payload IS NULL AND ended_fence IS NULL AND outcome IS NULL)
+      OR (state = 'staged' AND staged_payload IS NOT NULL AND ended_fence IS NULL AND outcome IS NULL)
+      OR (state = 'completed' AND staged_payload IS NULL AND ended_fence IS NOT NULL AND outcome IS NULL)
+      OR (state IN ('failed', 'interrupted') AND ended_fence IS NOT NULL AND outcome IS NOT NULL))
+  ) STRICT`,
+    // Immutable completed results. A result's identity is the attempt that
+    // produced it; its scope and version must equal that attempt's.
+    sql `CREATE TABLE history_results (
+    result_id INTEGER PRIMARY KEY,
+    analysis TEXT NOT NULL,
+    environment TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    publication INTEGER NOT NULL UNIQUE CHECK (publication > 0),
+    published_fence INTEGER NOT NULL CHECK (published_fence > 0),
+    encoding TEXT NOT NULL,
+    index_version INTEGER NOT NULL,
+    payload TEXT NOT NULL,
+    provenance_format TEXT NOT NULL,
+    provenance_version INTEGER NOT NULL,
+    provenance TEXT NOT NULL,
+    UNIQUE (result_id, analysis, environment, subject),
+    FOREIGN KEY (result_id, analysis, environment, subject, version)
+      REFERENCES history_attempts (attempt_id, analysis, environment, subject, version)
+  ) STRICT`,
+    sql `CREATE INDEX history_results_by_subject ON history_results (analysis, environment, subject, version, publication)`,
+    // Explicit exact dependencies recorded with staged content, in caller order.
+    sql `CREATE TABLE history_dependencies (
+    attempt_id INTEGER NOT NULL REFERENCES history_attempts (attempt_id),
+    position INTEGER NOT NULL CHECK (position >= 0),
+    dependency_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    PRIMARY KEY (attempt_id, position)
+  ) STRICT`,
+    // The generated selected index: one row per node of the canonical payload.
+    // Only `scalar` holds author data; everything else is shape or digest.
+    sql `CREATE TABLE history_nodes (
+    result_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    node_id INTEGER NOT NULL CHECK (node_id >= 0),
+    kind TEXT NOT NULL CHECK (kind IN ('scalar', 'record', 'array')),
+    scalar TEXT,
+    array_length INTEGER,
+    own_keys TEXT,
+    prototype TEXT CHECK (prototype IS NULL OR prototype IN ('null', 'object', 'custom')),
+    prototype_node INTEGER,
+    terminal TEXT CHECK (terminal IS NULL OR terminal IN ('null', 'object')),
+    snapshot_fingerprint TEXT NOT NULL,
+    PRIMARY KEY (result_id, node_id),
+    CHECK ((kind = 'scalar' AND scalar IS NOT NULL AND array_length IS NULL AND own_keys IS NULL
+        AND prototype IS NULL AND prototype_node IS NULL AND terminal IS NULL)
+      OR (kind = 'array' AND scalar IS NULL AND array_length IS NOT NULL AND array_length >= 0 AND own_keys IS NULL
+        AND prototype IS NULL AND prototype_node IS NULL AND terminal IS NULL)
+      OR (kind = 'record' AND scalar IS NULL AND array_length IS NULL AND own_keys IS NOT NULL
+        AND prototype IS NOT NULL AND terminal IS NOT NULL AND (prototype = 'custom') = (prototype_node IS NOT NULL)))
+  ) STRICT`,
+    // Structural slots: own record members and present array elements.
+    sql `CREATE TABLE history_edges (
+    result_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    parent_node INTEGER NOT NULL,
+    edge_kind TEXT NOT NULL CHECK (edge_kind IN ('property', 'index')),
+    edge_key TEXT NOT NULL,
+    position INTEGER NOT NULL,
+    child_node INTEGER NOT NULL,
+    PRIMARY KEY (result_id, parent_node, edge_kind, edge_key)
+  ) STRICT`,
+    // Every reachable structured address, with its node and MDO1 value digest.
+    sql `CREATE TABLE history_addresses (
+    result_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    address TEXT NOT NULL,
+    node_id INTEGER NOT NULL,
+    own INTEGER NOT NULL CHECK (own IN (0, 1)),
+    value_fingerprint TEXT,
+    PRIMARY KEY (result_id, address),
+    CHECK ((address = '[]') = (value_fingerprint IS NULL))
+  ) STRICT`,
+    // The latest publication of each scoped subject; acceptance never moves it.
+    sql `CREATE TABLE history_current (
+    analysis TEXT NOT NULL,
+    environment TEXT NOT NULL,
+    subject TEXT NOT NULL,
+    result_id INTEGER NOT NULL,
+    PRIMARY KEY (analysis, environment, subject),
+    FOREIGN KEY (result_id, analysis, environment, subject)
+      REFERENCES history_results (result_id, analysis, environment, subject)
+  ) STRICT`,
+    // Current acceptance evidence, separate from the result's provenance.
+    sql `CREATE TABLE history_acceptances (
+    acceptance_id INTEGER PRIMARY KEY CHECK (acceptance_id > 0),
+    result_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    fence INTEGER NOT NULL CHECK (fence > 0),
+    evidence_format TEXT NOT NULL,
+    evidence_version INTEGER NOT NULL,
+    evidence TEXT NOT NULL
+  ) STRICT`,
+    sql `CREATE INDEX history_acceptances_by_result ON history_acceptances (result_id, acceptance_id)`,
+    sql `CREATE TABLE history_acceptance_dependencies (
+    acceptance_id INTEGER NOT NULL REFERENCES history_acceptances (acceptance_id),
+    position INTEGER NOT NULL CHECK (position >= 0),
+    dependency_id INTEGER NOT NULL REFERENCES history_results (result_id),
+    PRIMARY KEY (acceptance_id, position)
+  ) STRICT`,
+    ...immutableTables.flatMap((table) => [
+        sql `CREATE TRIGGER ${table}_immutable_update BEFORE UPDATE ON ${table}
+    BEGIN SELECT RAISE(ABORT, '${table} rows are immutable history'); END`,
+        sql `CREATE TRIGGER ${table}_immutable_delete BEFORE DELETE ON ${table}
+    BEGIN SELECT RAISE(ABORT, '${table} rows are immutable history'); END`,
+    ]),
+    ...retainedTables.map((table) => sql `CREATE TRIGGER ${table}_immutable_delete BEFORE DELETE ON ${table}
+    BEGIN SELECT RAISE(ABORT, '${table} rows are immutable history and are never deleted'); END`),
+    // An attempt's identity, scope, key, intent and allocating fence never change.
+    sql `CREATE TRIGGER history_attempts_identity_immutable
+    BEFORE UPDATE OF attempt_id, analysis, environment, subject, version, attempt_key, intent_digest, allocated_fence
+    ON history_attempts
+    BEGIN SELECT RAISE(ABORT, 'history_attempts identity is immutable history'); END`,
+];
+/** Collapse whitespace so stored definitions compare by meaning-preserving text. */
+function normalize(text) {
+    return text.replace(/\s+/gu, ' ').trim();
+}
+/** The object name declared by one schema statement. */
+function objectName(statement) {
+    const match = /^CREATE (?:TABLE|INDEX|TRIGGER) (\S+)/u.exec(normalize(statement));
+    if (match?.[1] === undefined) {
+        throw new Error('History schema statement has no object name');
+    }
+    return match[1];
+}
+/** Expected normalized definitions keyed by object name. */
+const expectedObjects = new Map(schemaObjects.map((statement) => [objectName(statement), normalize(statement)]));
+/** Every user-visible object currently in the database, keyed by name. */
+function presentObjects(connection) {
+    const rows = connection.prepare(sql `/* schema */ SELECT name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite\_%' ESCAPE '\'`).all();
+    return new Map(rows.map((row) => [String(row.name), typeof row.sql === 'string' ? normalize(row.sql) : null]));
+}
+/**
+ * Create the schema in one transaction when the database has no objects,
+ * then validate it. Validation requires exactly the expected objects with
+ * their exact definitions and a single identity row naming this schema,
+ * version and the requested logical store.
+ */
+export function initializeSchema(connection, logicalStore) {
+    // An existing store is validated without taking the write lock; only an
+    // apparently empty file enters the IMMEDIATE transaction, which rechecks.
+    if (presentObjects(connection).size > 0) {
+        validateSchema(connection, logicalStore);
+        return;
+    }
+    connection.transaction(() => {
+        if (presentObjects(connection).size > 0) {
+            return undefined;
+        }
+        for (const statement of schemaObjects) {
+            connection.exec(statement);
+        }
+        connection.prepare(sql `/* schema */ INSERT INTO history_identity (singleton, schema_name, schema_version, logical_store) VALUES (1, ?, ?, ?)`)
+            .run(schemaName, schemaVersion, logicalStore);
+        connection.prepare(sql `/* schema */ INSERT INTO history_writer (singleton, last_fence, holder, expires_at, time_high_water) VALUES (1, 0, NULL, 0, 0)`).run();
+        connection.prepare(sql `/* schema */ INSERT INTO history_sequences (singleton, last_attempt, last_publication, last_acceptance) VALUES (1, 0, 0, 0)`).run();
+        return undefined;
+    });
+    validateSchema(connection, logicalStore);
+}
+/** Reject any database that is not exactly this schema for this logical store. */
+function validateSchema(connection, logicalStore) {
+    const present = presentObjects(connection);
+    const missing = [...expectedObjects.keys()].filter((name) => !present.has(name));
+    const unexpected = [...present.keys()].filter((name) => !expectedObjects.has(name));
+    if (missing.length > 0 || unexpected.length > 0) {
+        throw new HistorySchemaError(`Unsupported or incomplete History schema: missing [${missing.join(', ')}], unexpected [${unexpected.join(', ')}]`);
+    }
+    const altered = [...expectedObjects].filter(([name, definition]) => present.get(name) !== definition).map(([name]) => name);
+    if (altered.length > 0) {
+        throw new HistorySchemaError(`History schema objects differ from version ${String(schemaVersion)}: ${altered.join(', ')}`);
+    }
+    const identities = connection.prepare(sql `/* schema */ SELECT schema_name, schema_version, logical_store FROM history_identity`).all();
+    const identity = identities[0];
+    if (identities.length !== 1 || identity === undefined) {
+        throw new HistorySchemaError('History schema has no single identity row');
+    }
+    if (identity.schema_name !== schemaName || identity.schema_version !== schemaVersion) {
+        throw new HistorySchemaError(`Unsupported History schema ${String(identity.schema_name)} version ${String(identity.schema_version)}`);
+    }
+    if (identity.logical_store !== logicalStore) {
+        throw new HistorySchemaError('The SQLite file holds a different logical History store');
+    }
+    for (const table of ['history_writer', 'history_sequences']) {
+        const count = connection.prepare(sql `/* schema */ SELECT count(*) AS n FROM ${table}`).get();
+        if (count?.n !== 1) {
+            throw new HistorySchemaError(`History schema table ${table} does not have exactly one row`);
+        }
+    }
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/durable/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/durable/schema.ts"],"names":[],"mappings":"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"}

package/dist/src/durable/selected-index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * History's generated selected index over one immutable completed result,
+ * adopted from the accepted nested selected-read gate (issue #54, index
+ * requirements 1–7). History alone generates the index, inside the publish
+ * transaction, from the canonical MDS1 payload it stores; callers never supply
+ * index metadata. The index answers navigation, selected leaves and
+ * fingerprint metadata without decoding the root payload:
+ *
+ * - one node row per payload node (kind, MDV1 scalar leaf, array length, own
+ *   keys in snapshot order, prototype link and chain terminal, MDS1 digest);
+ * - one edge row per own record member or present array element;
+ * - one address row per reachable structured address (including members
+ *   inherited through supported prototypes) with its MDO1 `value` digest.
+ *
+ * Absent members are answered by evaluating Value on a payload-free stand-in of
+ * the longest indexed prefix. Reads verify what they return: a scalar leaf must
+ * match its address's `value` digest and a subtree its node's MDS1 digest, so
+ * corrupted storage fails as an integrity error instead of returning different
+ * data. Storage-shape failures never surface as `TypeError`, which is reserved
+ * for Value rejecting a selection's shape.
+ * @packageDocumentation
+ */
+import type { ISha256Capability, ISqliteConnection } from '@microdelta/machine';
+import type { ICompletedNavigationReader, ICompletedResultReader, ICompletedResultReference } from '../completed-results.js';
+import type { IResultVerification } from './contracts.js';
+/** The index layout version recorded with every result. */
+export declare const indexVersion = 1;
+/** One indexed node; only `scalar` holds author payload. */
+interface INodeRow {
+    readonly nodeId: number;
+    readonly kind: 'scalar' | 'record' | 'array';
+    /** MDV1 encoding of a scalar leaf. */
+    readonly scalar: string | null;
+    readonly arrayLength: number | null;
+    /** A record's own enumerable keys in snapshot order, as JSON. */
+    readonly ownKeys: string | null;
+    readonly prototype: 'null' | 'object' | 'custom' | null;
+    readonly prototypeNode: number | null;
+    /** Where a record's lookup chain ends; decides intrinsic-member semantics for absent keys. */
+    readonly terminal: 'null' | 'object' | null;
+    /** SHA-256 of the node's MDS1 snapshot. */
+    readonly snapshotFingerprint: string;
+}
+/** One structural slot: an own record member or a present array element. */
+interface IEdgeRow {
+    readonly parentNode: number;
+    readonly edgeKind: 'property' | 'index';
+    readonly edgeKey: string;
+    /** Own enumeration position for records; the index for arrays. */
+    readonly position: number;
+    readonly childNode: number;
+}
+/** One reachable structured address. */
+interface IAddressRow {
+    readonly address: string;
+    readonly nodeId: number;
+    /** Whether the final Property segment names an own member rather than an inherited one. */
+    readonly own: 0 | 1;
+    /** SHA-256 of the MDO1 `value` fact here; null for the root, which has no member address. */
+    readonly valueFingerprint: string | null;
+}
+/** The complete generated index for one result. */
+export interface IIndexRows {
+    readonly nodes: readonly INodeRow[];
+    readonly edges: readonly IEdgeRow[];
+    readonly addresses: readonly IAddressRow[];
+}
+/**
+ * Generate the index for one decoded canonical snapshot with a record or
+ * array root. Every container has exactly one structural parent because Value
+ * rejects shared references. Reachable addresses follow Value's lookup order:
+ * own members first, then members inherited through each custom prototype
+ * that an earlier level does not shadow.
+ */
+export declare function buildIndex(root: object, host: ISha256Capability): IIndexRows;
+/** Resolves an exact reference to a verified result identity in this store and scope. */
+export type IResultResolver = (reference: ICompletedResultReference) => number;
+/** The generated index's write, read and verification operations for one connection. */
+export interface ISelectedIndex {
+    /** Insert a result's generated index rows inside the caller's publish transaction. */
+    insert(resultId: number, rows: IIndexRows): void;
+    /** Exact scalar and navigation reader over completed results. */
+    readonly reader: ICompletedResultReader & ICompletedNavigationReader;
+    /** Regenerate a result's index from its stored canonical payload and compare. */
+    verify(resultId: number): IResultVerification;
+}
+/**
+ * Create the index operations over an owned connection. Exact references
+ * are resolved by the authority's `resolve`, which validates locator, store,
+ * scope, completion and stored encoding before any index row is read.
+ */
+export declare function createSelectedIndex(connection: ISqliteConnection, host: ISha256Capability, resolve: IResultResolver): ISelectedIndex;
+export {};
+//# sourceMappingURL=selected-index.d.ts.map

package/dist/src/durable/selected-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selected-index.d.ts","sourceRoot":"","sources":["../../../src/durable/selected-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAA4B,MAAM,qBAAqB,CAAC;AAc1G,OAAO,KAAK,EACV,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EAI1B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAM1D,2DAA2D;AAC3D,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,4DAA4D;AAC5D,UAAU,QAAQ;IAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC7C,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED,4EAA4E;AAC5E,UAAU,QAAQ;IAChB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,wCAAwC;AACxC,UAAU,WAAW;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;IACpB,6FAA6F;IAC7F,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1C;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAC;CAC5C;AAwBD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,UAAU,CA+F5E;AAgGD,yFAAyF;AACzF,MAAM,MAAM,eAAe,GAAG,CAAC,SAAS,EAAE,yBAAyB,KAAK,MAAM,CAAC;AAE/E,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,0BAA0B,CAAC;IACrE,iFAAiF;IACjF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAAC;CAC/C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAqYpI"}