silvermoon 0.3.0-rc.2 → 0.4.0

package/dist/src/foundation/event-cursor/cursor.js

@@ -0,0 +1,42 @@
+import { gitContentDigest, snapshotEventFileHead, validateEventRecordSizes, } from "../event-store/index.js";
+import { parseIdeaEvents } from "../event-codec/index.js";
+export async function readEventDelta(root, paths, options, filesystem, cursor) {
+    if (!Number.isSafeInteger(cursor?.length) || cursor.length < 0
+        || !new RegExp(`^[0-9a-f]{${options.objectIdLength}}$`).test(cursor.digest ?? "")) {
+        throw new Error("Incremental replay requires an exact prior length and file digest.");
+    }
+    const head = await snapshotEventFileHead(root, paths, options, filesystem);
+    const bytes = await filesystem.snapshotFile(paths.eventsPath);
+    validateEventRecordSizes(bytes);
+    if (cursor.length > bytes.length) {
+        throw new Error("Stale cursor length; reobserve without replaying the old intent.");
+    }
+    const prefix = bytes.subarray(0, cursor.length);
+    let prefixEvents;
+    try {
+        prefixEvents = parseIdeaEvents(prefix, options);
+    }
+    catch (cause) {
+        throw new Error("Cursor length is not an event boundary.", { cause });
+    }
+    const prefixDigest = gitContentDigest("blob", prefix, options);
+    if (prefixDigest !== cursor.digest) {
+        throw new Error("Stale cursor digest; historical content changed. Reobserve before deciding a new intent.");
+    }
+    const events = parseIdeaEvents(bytes.subarray(cursor.length), options);
+    for (const [index, event] of [...prefixEvents, ...events].entries()) {
+        if (event.sequence !== index + 1) {
+            throw new Error(`Event sequence is not continuous at record ${index + 1}.`);
+        }
+    }
+    const cursorSequence = prefixEvents.at(-1)?.sequence ?? 0;
+    return {
+        outcome: "delta-observed",
+        length: bytes.length,
+        digest: head,
+        after: { length: cursor.length, digest: cursor.digest },
+        events,
+        sequence: events.at(-1)?.sequence ?? cursorSequence,
+    };
+}
+//# sourceMappingURL=cursor.js.map

package/dist/src/foundation/event-cursor/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../../../src/foundation/event-cursor/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAuB1D,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAY,EACZ,KAA6B,EAC7B,OAAqD,EACrD,UAA8B,EAC9B,MAA0C;IAE1C,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;WACzD,CAAC,IAAI,MAAM,CAAC,aAAa,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,qBAAqB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;IAC3E,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,YAAY,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC9D,wBAAwB,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAChD,IAAI,YAAgD,CAAC;IACrD,IAAI,CAAC;QACH,YAAY,GAAG,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,yCAAyC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,YAAY,GAAG,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,IAAI,YAAY,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IACvE,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,YAAY,EAAE,GAAG,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;QACpE,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,GAAG,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CACb,8CAA8C,KAAK,GAAG,CAAC,GAAG,CAC3D,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,cAAc,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,CAAC,CAAC;IAC1D,OAAO;QACL,OAAO,EAAE,gBAAgB;QACzB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QACvD,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,cAAc;KACpD,CAAC;AACJ,CAAC"}

package/dist/src/foundation/event-cursor/index.d.ts

@@ -0,0 +1,2 @@
+export { readEventDelta, } from "./cursor.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/foundation/event-cursor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/foundation/event-cursor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/src/foundation/event-cursor/index.js

@@ -0,0 +1,2 @@
+export { readEventDelta, } from "./cursor.js";
+//# sourceMappingURL=index.js.map

package/dist/src/foundation/event-cursor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/foundation/event-cursor/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GACf,MAAM,aAAa,CAAC"}

package/dist/src/foundation/event-history/digest.d.ts

@@ -0,0 +1,2 @@
+export { MAX_EVENT_BYTES, algorithm, gitContentDigest, validateEventRecordSizes, } from "../event-store/index.ts";
+//# sourceMappingURL=digest.d.ts.map

package/dist/src/foundation/event-history/digest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.d.ts","sourceRoot":"","sources":["../../../../src/foundation/event-history/digest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC"}

package/dist/src/foundation/event-history/digest.js

@@ -0,0 +1,2 @@
+export { MAX_EVENT_BYTES, algorithm, gitContentDigest, validateEventRecordSizes, } from "../event-store/index.js";
+//# sourceMappingURL=digest.js.map

package/dist/src/foundation/event-history/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../../src/foundation/event-history/digest.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,SAAS,EACT,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC"}

package/dist/src/foundation/event-history/history.d.ts

@@ -0,0 +1,86 @@
+export declare const SOURCE_REPOSITORY = "https://github.com/shazhou-ww/silvermoon.git";
+type EventFormat = "legacy" | "final";
+interface ProjectConfig {
+    version: 1 | 2;
+    primaryRepository: string;
+    primaryBranch: string;
+}
+export interface HistoryBaseline {
+    commit: string;
+    source: string;
+    ref: string | null;
+}
+interface InspectHistoryOptions {
+    root: string;
+    tree: string;
+    config: ProjectConfig;
+    commit?: string;
+    primary?: string;
+    overrides?: ReadonlyMap<string, Buffer>;
+}
+export declare function localPrimary(root: string, config: ProjectConfig): HistoryBaseline;
+export declare function detectEventFormat({ root, tree, overrides, }: Pick<InspectHistoryOptions, "root" | "tree" | "overrides">): Promise<EventFormat>;
+export declare function inspectEventHistory(options: InspectHistoryOptions): Promise<{
+    results: ({
+        id: string;
+        mode: string;
+        candidate: {
+            ok: true;
+            state: import("../event-codec/grammar.ts").IdeaEventState;
+        };
+    } | {
+        ok: unknown;
+        mode: unknown;
+        id: string;
+        candidate?: never;
+    })[];
+    parent?: string | null;
+    valid: boolean;
+    baseline: HistoryBaseline;
+    target: string;
+}>;
+export declare function inspectProjectedEventHistory({ root, tree, primary, }: {
+    root: string;
+    tree: string;
+    primary: string;
+}): Promise<{
+    supported: boolean;
+    reason: string;
+    id?: never;
+    reduction?: never;
+    valid?: never;
+    detail?: never;
+    target?: never;
+    baseline?: never;
+    results?: never;
+} | {
+    supported: boolean;
+    reason: string;
+    id: string;
+    reduction: {
+        ok: false;
+        code: string;
+        sequence: number;
+    } | undefined;
+    valid?: never;
+    detail?: never;
+    target?: never;
+    baseline?: never;
+    results?: never;
+} | {
+    supported: boolean;
+    valid: boolean;
+    detail: string;
+    target: string;
+    baseline: {
+        commit: string;
+        source: string;
+        ref: null;
+    };
+    results: Record<string, unknown>[];
+    reason?: never;
+    id?: never;
+    reduction?: never;
+}>;
+export {};
+//# sourceMappingURL=history.d.ts.map

package/dist/src/foundation/event-history/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../../src/foundation/event-history/history.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,iBAAiB,iDAAiD,CAAC;AAEhF,KAAK,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEtC,UAAU,aAAa;IACrB,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AA0BD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,UAAU,qBAAqB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAgED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,eAAe,CAkBjF;AAyFD,wBAAsB,iBAAiB,CAAC,EACtC,IAAI,EACJ,IAAI,EACJ,SAAS,GACV,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC,wBAY5D;AA8LD,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,qBAAqB;;;;;;;;;;;;;;;;;;GAUvE;AA2DD,wBAAsB,4BAA4B,CAAC,EACjD,IAAI,EACJ,IAAI,EACJ,OAAO,GACR,EAAE;IACD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EA"}

package/dist/src/foundation/event-history/history.js

@@ -0,0 +1,481 @@
+import { isDeepStrictEqual } from "node:util";
+import { loadConfigSnapshot } from "../project-config/index.js";
+import { EVENT_RENAMES, checkEventChange, eventsFromStatus, parseIdeaEvents, renameLegacyEvents, replayIdeaEvents, serializeIdeaEvents, } from "../event-codec/index.js";
+import { isValidUlid, parseIdeaStatus } from "../idea-model/index.js";
+import { inspectTreeLineage, readGitBlob, readGitBlobs, resolveCommit, runGit, } from "../git/index.js";
+import { CONFIG_PATH, IDEAS_ROOT, ideaPaths } from "../coordinates/index.js";
+import { snapshotEventPrefix, validateEventRecordSizes } from "../event-store/index.js";
+import { createGitSnapshotFileSystem } from "../snapshot/index.js";
+import { projectEventSnapshot, ProjectedReductionError } from "../projection-cache/index.js";
+export const SOURCE_REPOSITORY = "https://github.com/shazhou-ww/silvermoon.git";
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function requireBuffer(value, label) {
+    if (!Buffer.isBuffer(value))
+        throw new TypeError(`${label} must provide raw bytes.`);
+    return value;
+}
+function requireTreeEntries(value) {
+    if (!Array.isArray(value))
+        throw new TypeError("Git tree inspection must return entries.");
+    return value.map((entry) => {
+        if (entry === null || typeof entry !== "object"
+            || !("mode" in entry) || typeof entry.mode !== "string"
+            || !("type" in entry) || typeof entry.type !== "string"
+            || !("object" in entry) || typeof entry.object !== "string"
+            || !("name" in entry) || typeof entry.name !== "string"
+            || !("size" in entry)
+            || (entry.size !== null && typeof entry.size !== "number")) {
+            throw new TypeError("Git tree inspection returned an invalid entry.");
+        }
+        return {
+            mode: entry.mode,
+            type: entry.type,
+            object: entry.object,
+            size: entry.size,
+            name: entry.name,
+        };
+    });
+}
+function treeEntries(root, tree, path) {
+    return requireTreeEntries(inspectTreeLineage(root, tree, path));
+}
+function parsedEventType(bytes, id) {
+    let first;
+    try {
+        first = JSON.parse(bytes.toString("utf8").split("\n", 1)[0] ?? "");
+    }
+    catch (cause) {
+        throw new Error(`${id}: cannot identify historical event format: ${errorMessage(cause)}`, { cause });
+    }
+    if (first === null || typeof first !== "object"
+        || !("type" in first) || typeof first.type !== "string") {
+        throw new Error(`${id}: cannot identify historical event format: first event type is invalid`);
+    }
+    return first.type;
+}
+function git(root, args) {
+    const result = runGit(root, args);
+    if (!result.ok)
+        throw new Error(`Event history unavailable: ${result.stderr}`);
+    return result.stdout;
+}
+export function localPrimary(root, config) {
+    const refs = [];
+    for (const remote of git(root, ["remote"]).split("\n").filter(Boolean)) {
+        const url = git(root, ["config", "--get", `remote.${remote}.url`]);
+        if (url !== config.primaryRepository)
+            continue;
+        const ref = `refs/remotes/${remote}/${config.primaryBranch}`;
+        const result = runGit(root, ["rev-parse", "--verify", `${ref}^{commit}`]);
+        if (result.ok)
+            refs.push({ ref, commit: result.stdout });
+    }
+    if (!refs.length) {
+        throw new Error("Primary tracking ref unavailable; fetch the configured primary into its named remote.");
+    }
+    if (new Set(refs.map(({ commit }) => commit)).size !== 1) {
+        throw new Error("Primary tracking refs disagree; refresh them before checking.");
+    }
+    const first = refs[0];
+    if (!first)
+        throw new Error("Primary tracking ref unavailable.");
+    return { ...first, source: "local-tracking-ref-not-fetched" };
+}
+async function snapshot(root, tree, overrides, commit, blobs) {
+    const configEntry = treeEntries(root, tree, CONFIG_PATH)
+        .find(({ name }) => name === CONFIG_PATH);
+    const entries = treeEntries(root, tree, IDEAS_ROOT);
+    const stateBlobs = blobs ?? new Map();
+    if (!configEntry) {
+        if (entries.length)
+            throw new Error("Historical ideas exist without project configuration.");
+        return {
+            version: null,
+            entries,
+            ids: [],
+            sourceProject: false,
+            overrides,
+            commit,
+            blobs: stateBlobs,
+            format: null,
+        };
+    }
+    const loaded = await loadConfigSnapshot({ gitRoot: root, tree });
+    if (!loaded.config) {
+        throw new Error(`Invalid historical configuration: ${loaded.diagnostics.map((diagnostic) => diagnostic.message).join("; ")}`);
+    }
+    if (loaded.config.version !== 1 && loaded.config.version !== 2) {
+        throw new Error("Invalid historical configuration version.");
+    }
+    const config = loaded.config;
+    const ids = entries
+        .filter(({ type, name }) => type === "tree" && name.split("/").length === 3)
+        .map(({ name }) => name.split("/")[2])
+        .filter((id) => id !== undefined);
+    if (ids.some((id) => !isValidUlid(id))) {
+        throw new Error("Historical idea identity is invalid.");
+    }
+    const sourceProject = config.primaryRepository === SOURCE_REPOSITORY;
+    const stateFile = config.version === 2 ? "events.jsonl" : "status.yaml";
+    const stateObjects = entries
+        .filter(({ name, object, type }) => type === "blob"
+        && name.endsWith(`/${stateFile}`)
+        && !overrides?.has(name)
+        && !stateBlobs.has(object))
+        .map(({ object }) => object);
+    for (const [object, contents] of readGitBlobs(root, stateObjects)) {
+        if (typeof object !== "string")
+            throw new TypeError("Git batch returned an invalid object ID.");
+        stateBlobs.set(object, requireBuffer(contents, `Git object ${object}`));
+    }
+    const state = {
+        version: config.version,
+        entries,
+        ids,
+        sourceProject,
+        overrides,
+        commit,
+        blobs: stateBlobs,
+        format: null,
+    };
+    if (state.version !== 2)
+        return state;
+    const formats = new Set();
+    for (const id of ids) {
+        const bytes = source(root, state, id, "events.jsonl");
+        if (!bytes.length)
+            continue;
+        const format = Object.hasOwn(EVENT_RENAMES, parsedEventType(bytes, id))
+            ? "legacy"
+            : "final";
+        if (format === "legacy" && !sourceProject) {
+            throw new Error(`${id}: legacy dotted event history is only supported in the Silvermoon source repository`);
+        }
+        parseIdeaEvents(bytes, { legacy: format === "legacy", objectIdLength: tree.length });
+        formats.add(format);
+    }
+    if (formats.size > 1) {
+        throw new Error("Mixed legacy and final idea logs in one snapshot; migrate every idea together.");
+    }
+    state.format = formats.values().next().value ?? null;
+    return state;
+}
+export async function detectEventFormat({ root, tree, overrides, }) {
+    const state = await snapshot(root, tree, overrides);
+    if (state.format)
+        return state.format;
+    if (!state.sourceProject || state.version !== 2)
+        return "final";
+    let commit = resolveCommit(root, "HEAD");
+    while (commit) {
+        const previous = await snapshot(root, commit);
+        if (previous.version !== 2)
+            break;
+        if (previous.format)
+            return previous.format;
+        commit = firstParent(root, commit);
+    }
+    return "legacy";
+}
+function source(root, state, id, name) {
+    const paths = ideaPaths(id);
+    const path = `${paths.ideaPath}/${name}`;
+    const override = state.overrides?.get(path);
+    if (override !== undefined) {
+        const bytes = requireBuffer(override, `Historical override ${path}`);
+        if (name === "events.jsonl")
+            validateEventRecordSizes(bytes);
+        return bytes;
+    }
+    const entry = state.entries.find(({ name: entryName }) => entryName === path);
+    if (!entry || entry.type !== "blob" || !["100644", "100755"].includes(entry.mode)) {
+        throw new Error(`Historical state file missing or irregular: ${path}`);
+    }
+    const cached = state.blobs.get(entry.object);
+    if (cached !== undefined) {
+        if (name === "events.jsonl")
+            validateEventRecordSizes(cached);
+        return cached;
+    }
+    const bytes = requireBuffer(readGitBlob(root, entry.object), `Git object ${entry.object}`);
+    state.blobs.set(entry.object, bytes);
+    if (name === "events.jsonl")
+        validateEventRecordSizes(bytes);
+    return bytes;
+}
+function reductionFailure(result) {
+    return {
+        code: "code" in result ? result.code : "missing-code",
+        sequence: "sequence" in result ? result.sequence : "unknown",
+    };
+}
+function transition(root, base, candidate, id, options) {
+    const next = source(root, candidate, id, "events.jsonl");
+    const candidateOptions = { ...options, legacy: candidate.format === "legacy" };
+    if (!base.ids.includes(id)) {
+        const result = replayIdeaEvents(id, parseIdeaEvents(next, candidateOptions), candidateOptions);
+        if (!result.ok || !("state" in result)) {
+            const failure = reductionFailure(result);
+            throw new Error(`${id}: candidate ${String(failure.code)} at ${String(failure.sequence)}`);
+        }
+        return { id, mode: "initialization", candidate: result };
+    }
+    if (base.version === 1) {
+        const legacy = parseIdeaStatus(source(root, base, id, "status.yaml").toString("utf8"), options);
+        const result = replayIdeaEvents(id, parseIdeaEvents(next, candidateOptions), candidateOptions);
+        const { version: _version, ...facts } = legacy;
+        const migrationEvents = Reflect.apply(eventsFromStatus, undefined, [legacy, candidateOptions]);
+        if (!Array.isArray(migrationEvents)) {
+            throw new TypeError("Status migration did not produce an event list.");
+        }
+        if (legacy.id !== id || !result.ok || !("state" in result)
+            || !isDeepStrictEqual(facts, result.state.status)
+            || (!candidateOptions.legacy
+                && !isDeepStrictEqual(result.state.interaction, { messages: [] }))
+            || !next.equals(Buffer.from(serializeIdeaEvents(migrationEvents, candidateOptions)))) {
+            throw new Error(`${id}: migration must preserve every primary v1 fact exactly`);
+        }
+        return { id, mode: "migration", candidate: result };
+    }
+    const previous = source(root, base, id, "events.jsonl");
+    if (base.format === "legacy" && candidate.format === "final") {
+        if (base.ids.length !== candidate.ids.length) {
+            throw new Error("Legacy event migration must convert every existing idea without changing inventory.");
+        }
+        const legacyOptions = { ...options, legacy: true };
+        const oldEvents = parseIdeaEvents(previous, legacyOptions);
+        const old = replayIdeaEvents(id, oldEvents, legacyOptions);
+        if (!old.ok || !("state" in old)) {
+            const failure = reductionFailure(old);
+            throw new Error(`${id}: cannot migrate invalid legacy event ${String(failure.sequence)}: ${String(failure.code)}`);
+        }
+        const newEvents = parseIdeaEvents(next, candidateOptions);
+        if (!isDeepStrictEqual(newEvents, renameLegacyEvents(oldEvents))) {
+            throw new Error(`${id}: internal migration must preserve every legacy record, sequence and payload with only the exact type rename`);
+        }
+        const result = replayIdeaEvents(id, newEvents, candidateOptions);
+        if (!result.ok || !("state" in result) || !isDeepStrictEqual({ status: result.state.status, sequence: result.state.sequence }, old.state) || !isDeepStrictEqual(result.state.interaction, { messages: [] })) {
+            throw new Error(`${id}: internal migration changes historical facts or contains an invalid abandoned window`);
+        }
+        return { id, mode: "migration-final", candidate: result };
+    }
+    if (base.format === "final" && candidate.format === "legacy") {
+        throw new Error(`${id}: final event history cannot return to legacy dotted events`);
+    }
+    const checked = Reflect.apply(checkEventChange, undefined, [
+        id,
+        previous,
+        next,
+        { ...options, legacy: (candidate.format ?? base.format) === "legacy" },
+    ]);
+    if (checked === null || typeof checked !== "object"
+        || !("ok" in checked) || typeof checked.ok !== "boolean"
+        || !("mode" in checked) || typeof checked.mode !== "string") {
+        throw new TypeError("Event change inspection returned an invalid result.");
+    }
+    if (base.sourceProject && base.format === "final" && checked.mode === "repair"
+        && hasLegacyAncestor(root, base.commit ?? null)) {
+        throw new Error(`${id}: final event history must remain append-only after the migration boundary`);
+    }
+    if (!checked.ok) {
+        const failure = reductionFailure(checked);
+        throw Object.assign(new Error(`${id}: ${String(failure.code)} (${checked.mode})`), { eventCheck: { id, ...checked } });
+    }
+    return { id, ...checked };
+}
+function noDeletion(base, candidate) {
+    for (const id of base.ids) {
+        if (!candidate.ids.includes(id)) {
+            throw new Error(`${id}: removing an integrated idea is not an event repair`);
+        }
+    }
+    if (base.version !== null && candidate.version !== null
+        && base.version >= 2 && candidate.version < base.version) {
+        throw new Error("An event project cannot be downgraded to an earlier version.");
+    }
+    if (base.format === "legacy" && candidate.format === "final"
+        && (base.ids.length !== candidate.ids.length
+            || base.ids.some((id) => !candidate.ids.includes(id)))) {
+        throw new Error("Legacy event migration must convert every existing idea without changing inventory.");
+    }
+}
+function firstParent(root, commit) {
+    const body = git(root, ["cat-file", "-p", commit]);
+    return /^parent ([0-9a-f]+)$/m.exec(body.split("\n\n")[0] ?? "")?.[1] ?? null;
+}
+function hasLegacyAncestor(root, initialCommit) {
+    let commit = initialCommit;
+    while (commit) {
+        const state = snapshotFormat(root, commit);
+        if (state === "legacy")
+            return true;
+        if (state !== "final")
+            return false;
+        commit = firstParent(root, commit);
+    }
+    return false;
+}
+function snapshotFormat(root, commit) {
+    const entries = treeEntries(root, commit, IDEAS_ROOT);
+    for (const { name, type, object } of entries) {
+        if (type !== "blob" || !name.endsWith("/events.jsonl"))
+            continue;
+        const bytes = requireBuffer(readGitBlob(root, object), `Git object ${object}`);
+        if (!bytes.length)
+            continue;
+        return Object.hasOwn(EVENT_RENAMES, parsedEventType(bytes, name)) ? "legacy" : "final";
+    }
+    return treeEntries(root, commit, CONFIG_PATH).some(({ name }) => name === CONFIG_PATH)
+        ? "final"
+        : null;
+}
+export async function inspectEventHistory(options) {
+    const baseline = options.primary
+        ? { commit: options.primary, source: "fetched-primary", ref: null }
+        : localPrimary(options.root, options.config);
+    try {
+        return await inspectBoundHistory({ ...options, baseline });
+    }
+    catch (cause) {
+        if (cause instanceof Error)
+            throw Object.assign(cause, { eventBaseline: baseline });
+        throw Object.assign(new Error(errorMessage(cause), { cause }), { eventBaseline: baseline });
+    }
+}
+function snapshotInventory(filesystem) {
+    const entries = requireTreeEntries(filesystem.snapshotEntries(IDEAS_ROOT));
+    return entries
+        .filter(({ type }) => type === "tree")
+        .map(({ name }) => name.slice(IDEAS_ROOT.length + 1));
+}
+function withPreciseReaddir(filesystem) {
+    async function readdir(path, options) {
+        if (options?.withFileTypes === true) {
+            const entries = await filesystem.readdir(path, options);
+            if (entries.every((entry) => typeof entry !== "string")) {
+                return entries;
+            }
+            throw new TypeError("Snapshot directory entry metadata is invalid.");
+        }
+        const entries = await filesystem.readdir(path);
+        if (entries.every((entry) => typeof entry === "string")) {
+            return entries;
+        }
+        throw new TypeError("Snapshot directory names are invalid.");
+    }
+    return { ...filesystem, readdir };
+}
+function projectedSummary(projected) {
+    if (projected === null || typeof projected !== "object"
+        || !("digest" in projected) || typeof projected.digest !== "string"
+        || !("length" in projected) || typeof projected.length !== "number"
+        || !("state" in projected) || projected.state === null
+        || typeof projected.state !== "object" || !("sequence" in projected.state)) {
+        throw new TypeError("Projected event snapshot returned an invalid summary.");
+    }
+    return {
+        length: projected.length,
+        digest: projected.digest,
+        sequence: projected.state.sequence,
+    };
+}
+export async function inspectProjectedEventHistory({ root, tree, primary, }) {
+    const loaded = await loadConfigSnapshot({ gitRoot: root, tree: primary });
+    if (!loaded.config) {
+        throw new Error(`Invalid primary configuration: ${loaded.diagnostics.map((item) => item.message).join("; ")}`);
+    }
+    if (loaded.config.version !== 2) {
+        return { supported: false, reason: "version-transition" };
+    }
+    const baseline = withPreciseReaddir(createGitSnapshotFileSystem({ gitRoot: root, tree: primary }));
+    const candidate = withPreciseReaddir(createGitSnapshotFileSystem({ gitRoot: root, tree }));
+    const previousIds = snapshotInventory(baseline);
+    const ids = snapshotInventory(candidate);
+    if ([...previousIds, ...ids].some((id) => !isValidUlid(id))) {
+        throw new Error("Historical idea identity is invalid.");
+    }
+    if (previousIds.some((id) => !ids.includes(id))) {
+        throw new Error("Removing an integrated idea is not an event repair.");
+    }
+    if (previousIds.some((id) => baseline.snapshotEntry(ideaPaths(id).eventsPath)?.type !== "blob")
+        || ids.some((id) => candidate.snapshotEntry(ideaPaths(id).eventsPath)?.type !== "blob")) {
+        return { supported: false, reason: "storage-transition" };
+    }
+    const options = { objectIdLength: primary.length };
+    const results = [];
+    for (const id of ids) {
+        const paths = ideaPaths(id);
+        const next = await projectEventSnapshot(root, id, paths, options, candidate);
+        if (!previousIds.includes(id)) {
+            results.push({ id, mode: "initialization", candidate: projectedSummary(next) });
+            continue;
+        }
+        let previous;
+        try {
+            previous = await projectEventSnapshot(root, id, paths, options, baseline);
+        }
+        catch (cause) {
+            if (!(cause instanceof ProjectedReductionError))
+                throw cause;
+            const reduction = "result" in cause ? cause.result : undefined;
+            return {
+                supported: false,
+                reason: "primary-reduction-failed",
+                id,
+                reduction,
+            };
+        }
+        if (await snapshotEventPrefix(root, paths, options, candidate, previous.length) !== previous.digest) {
+            throw new Error(`${id}: not-append-only (append)`);
+        }
+        results.push({
+            id,
+            mode: "append",
+            base: projectedSummary(previous),
+            candidate: projectedSummary(next),
+        });
+    }
+    return {
+        supported: true,
+        valid: true,
+        detail: "summary",
+        target: "candidate",
+        baseline: { commit: primary, source: "fetched-primary", ref: null },
+        results,
+    };
+}
+async function inspectBoundHistory({ root, tree, commit, overrides, baseline, }) {
+    const blobs = new Map();
+    const primaryCommit = resolveCommit(root, baseline.commit);
+    const target = await snapshot(root, tree, overrides, commit, blobs);
+    const options = { objectIdLength: primaryCommit.length };
+    const results = [];
+    const targetCommit = commit === undefined ? null : resolveCommit(root, commit);
+    const parent = targetCommit ? firstParent(root, targetCommit) : null;
+    const baseCommit = targetCommit ? parent : primaryCommit;
+    const base = baseCommit
+        ? await snapshot(root, baseCommit, undefined, baseCommit, blobs)
+        : await snapshot(root, tree, undefined, undefined, blobs);
+    if (!baseCommit) {
+        base.version = null;
+        base.ids = [];
+        base.entries = [];
+        base.format = null;
+    }
+    noDeletion(base, target);
+    if (target.version === 2) {
+        for (const id of target.ids) {
+            results.push(transition(root, base, target, id, options));
+        }
+    }
+    return {
+        valid: true,
+        baseline,
+        target: targetCommit ? "commit" : "candidate",
+        ...(targetCommit ? { parent: baseCommit } : {}),
+        results,
+    };
+}
+//# sourceMappingURL=history.js.map