@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/spec/entity-renumber.d.ts

@@ -0,0 +1,32 @@
+import { Spec } from './spec-parser';
+export interface EntityRenumberEntry {
+    entityId: string;
+    documentLocator: string;
+    text: string;
+}
+export interface EntityRenumberChange {
+    entityId: string;
+    newDisplayId: string;
+}
+export interface EntityRenumberProposal {
+    ok: boolean;
+    conflicts: string[];
+    entries: Array<{
+        entityId: string;
+        oldId: string;
+        newId: string;
+        documentLocator: string;
+        newDocumentLocator: string;
+        before: string;
+        beforeVersion: string;
+        after: string;
+    }>;
+    contentChanged: string[];
+    parentSnapshotsChanged: string[];
+    unsealOrder: string[];
+    approveOrder: string[];
+}
+/** Rebuild structured metadata while retaining the exact original body, including CRLF/preamble. */
+export declare function replaceFrontmatter(original: string, candidate: Spec): string;
+/** Pure proposal only. Seal transitions and source publication require the authorized executor. */
+export declare function planEntityRenumber(entries: EntityRenumberEntry[], changes: EntityRenumberChange[]): EntityRenumberProposal;

package/dist/holmes/spec/entity-renumber.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.replaceFrontmatter = replaceFrontmatter;
+exports.planEntityRenumber = planEntityRenumber;
+// @implements A-SPEC-628
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const spec_parser_1 = require("./spec-parser");
+const spec_digest_1 = require("./spec-digest");
+const spec_types_1 = require("./spec-types");
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const HEADER = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/;
+const safeLocator = (value) => value.length > 0 && !/[\\:\x00]/.test(value) && value.split('/').every(p => p !== '' && p !== '.' && p !== '..') && value.endsWith('.md');
+/** Rebuild structured metadata while retaining the exact original body, including CRLF/preamble. */
+function replaceFrontmatter(original, candidate) {
+    const prefix = HEADER.exec(original)[0];
+    const generated = HEADER.exec((0, spec_parser_1.serializeSpec)(candidate))[0];
+    return (prefix.startsWith('---\r\n') ? generated.replace(/\n/g, '\r\n') : generated) + original.slice(prefix.length);
+}
+/** Pure proposal only. Seal transitions and source publication require the authorized executor. */
+function planEntityRenumber(entries, changes) {
+    const empty = (conflicts) => ({ ok: false, conflicts: [...conflicts].sort(), entries: [], contentChanged: [], parentSnapshotsChanged: [], unsealOrder: [], approveOrder: [] });
+    const ordered = [...entries].sort((a, b) => a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0);
+    const byEntity = new Map();
+    const byId = new Map(), locations = new Set();
+    for (const entry of ordered) {
+        if (!UUID.test(entry.entityId) || byEntity.has(entry.entityId) || !safeLocator(entry.documentLocator) || locations.has(entry.documentLocator) || !HEADER.test(entry.text))
+            return empty(['Invalid or duplicate entity identity/document locator: ' + entry.entityId]);
+        let spec;
+        try {
+            spec = (0, spec_parser_1.parseSpec)(entry.text);
+        }
+        catch {
+            return empty(['Unparseable document: ' + entry.documentLocator]);
+        }
+        if (!(0, spec_types_1.specTypeDef)(spec.type)?.idRegex.test(spec.id) || !Array.isArray(spec.dependsOn) || spec.dependsOn.some(p => typeof p !== 'string') || byId.has(spec.id))
+            return empty(['Invalid or duplicate display ID: ' + spec.id]);
+        byEntity.set(entry.entityId, { entry, spec });
+        byId.set(spec.id, entry.entityId);
+        locations.add(entry.documentLocator);
+    }
+    const requested = new Map();
+    for (const change of changes) {
+        const prior = byEntity.get(change.entityId);
+        if (!prior || requested.has(change.entityId) || !(0, spec_types_1.specTypeDef)(prior.spec.type).idRegex.test(change.newDisplayId))
+            return empty(['Invalid or duplicate requested move: ' + change.entityId]);
+        requested.set(change.entityId, change.newDisplayId);
+    }
+    const newIds = new Map(), destinations = new Set();
+    for (const [entityId, { spec }] of byEntity) {
+        const id = requested.get(entityId) ?? spec.id;
+        if (destinations.has(id))
+            return empty(['Occupied destination display ID: ' + id]);
+        destinations.add(id);
+        newIds.set(spec.id, id);
+    }
+    const parents = new Map(), children = new Map();
+    for (const id of byEntity.keys())
+        children.set(id, new Set());
+    for (const [entityId, { spec }] of byEntity) {
+        const deps = new Set();
+        for (const parent of spec.dependsOn) {
+            const parentEntity = byId.get(parent);
+            if (!parentEntity)
+                return empty(['Unresolved dependency: ' + spec.id + ' -> ' + parent]);
+            deps.add(parentEntity);
+            children.get(parentEntity).add(entityId);
+            // Preserve only a proven existing mirror, not a repository-specific numbering convention.
+            if (spec.type === 'T-SPEC' && parent.startsWith('A-SPEC-') && spec.id.slice(7) === parent.slice(7) && newIds.get(spec.id).slice(7) !== newIds.get(parent).slice(7))
+                return empty(['Moving this mirrored A/T pair requires matching final suffixes: ' + spec.id]);
+        }
+        parents.set(entityId, deps);
+    }
+    const degrees = new Map([...parents].map(([id, deps]) => [id, deps.size]));
+    const ready = [...degrees].filter(([, degree]) => degree === 0).map(([id]) => id).sort(), topo = [];
+    while (ready.length) {
+        const id = ready.shift();
+        topo.push(id);
+        for (const child of children.get(id)) {
+            degrees.set(child, degrees.get(child) - 1);
+            if (degrees.get(child) === 0) {
+                ready.push(child);
+                ready.sort();
+            }
+        }
+    }
+    if (topo.length !== byEntity.size)
+        return empty(['Cyclic specification dependencies prevent an approval order.']);
+    const candidates = new Map(), contentChanged = [], parentSnapshotsChanged = [];
+    const changedDigests = new Set();
+    for (const [entityId, { spec }] of byEntity) {
+        const candidate = { ...spec, id: newIds.get(spec.id), dependsOn: spec.dependsOn.map(id => newIds.get(id)), frontmatter: { ...spec.frontmatter } };
+        candidates.set(entityId, candidate);
+        if ((0, spec_digest_1.specDigest)(candidate) !== (0, spec_digest_1.specDigest)(spec)) {
+            contentChanged.push(entityId);
+            changedDigests.add(entityId);
+        }
+    }
+    for (const [entityId, { spec }] of byEntity) {
+        if (spec.dependsOn.some(parent => newIds.get(parent) !== parent || changedDigests.has(byId.get(parent))))
+            parentSnapshotsChanged.push(entityId);
+    }
+    const affected = new Set([...contentChanged, ...parentSnapshotsChanged]);
+    // Any approved descendant can block an official unseal, even when its own digest is unchanged.
+    for (const id of topo)
+        if (affected.has(id))
+            for (const child of children.get(id))
+                affected.add(child);
+    const approvalEntities = topo.filter(id => affected.has(id) && byEntity.get(id).spec.status === 'approved');
+    const proposed = [], finalPaths = new Set();
+    for (const [entityId, { entry, spec }] of byEntity) {
+        const candidate = candidates.get(entityId);
+        const newDocumentLocator = candidate.id === spec.id ? entry.documentLocator : path.posix.join(path.posix.dirname(entry.documentLocator), candidate.id + '.md');
+        if (finalPaths.has(newDocumentLocator))
+            return empty(['Occupied destination document: ' + newDocumentLocator]);
+        finalPaths.add(newDocumentLocator);
+        const structuredChange = candidate.id !== spec.id || candidate.dependsOn.some((id, i) => id !== spec.dependsOn[i]);
+        proposed.push({ entityId, oldId: spec.id, newId: candidate.id, documentLocator: entry.documentLocator, newDocumentLocator,
+            before: entry.text, beforeVersion: 'sha256:' + (0, node_crypto_1.createHash)('sha256').update(entry.text).digest('hex'), after: structuredChange ? replaceFrontmatter(entry.text, candidate) : entry.text });
+    }
+    return { ok: true, conflicts: [], entries: proposed, contentChanged, parentSnapshotsChanged,
+        unsealOrder: [...approvalEntities].reverse().map(id => byEntity.get(id).spec.id), approveOrder: approvalEntities.map(id => candidates.get(id).id) };
+}

package/dist/holmes/spec/entity-store.d.ts

@@ -0,0 +1,135 @@
+import { Spec } from './spec-parser';
+export { EntityStoreError, entityContentVersion } from './entity-transaction';
+export interface EntityAdoptionPlan {
+    schema: 'holmes-entity-adoption/1';
+    operationId: string;
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    entries: Array<{
+        entityId: string;
+        displayId: string;
+        documentLocator: string;
+        version: string;
+    }>;
+}
+export declare function entityStoreBinding(storeRoot: string): {
+    root: string;
+    store: string;
+    locator: string;
+};
+export declare function validateEntityAdoptionPlan(value: unknown): EntityAdoptionPlan;
+export declare function entityAdoptionTarget(plan: EntityAdoptionPlan): string;
+/** @implements A-SPEC-638 — the raw legacy renumber's rollback journal: the original bytes of every file it touches. */
+export declare const LEGACY_RENUMBER_JOURNAL_SCHEMA = "holmes-legacy-renumber-journal/1";
+export interface LegacyRenumberJournal {
+    schema: typeof LEGACY_RENUMBER_JOURNAL_SCHEMA;
+    operationId: string;
+    workspaceId: string;
+    storeLocator: string;
+    oldBase: string;
+    newBase: string;
+    changes: Array<{
+        locator: string;
+        before: string | null;
+    }>;
+}
+/** Inspection may use committed identity before local replica registration; pending writes still block it. */
+export declare function assertNoPendingEntityPublication(storeRoot: string): void;
+export declare function inspectEntityStore(storeRoot: string): {
+    ok: true;
+    state: "active";
+    storeLocator: string;
+    storeId: string;
+} | {
+    ok: true;
+    state: "legacy";
+    storeLocator: string;
+    storeId?: undefined;
+};
+export declare function planEntityAdoption(storeRoot: string): EntityAdoptionPlan;
+/** Read barrier for the real repository. Legacy stores without an entity subsystem remain untouched. */
+export declare function assertEntityRepositoryReadable(storeRoot: string): void;
+export declare function readEntityRepositorySnapshot(storeRoot: string): Array<{
+    spec: Spec;
+    version: string;
+}> | undefined;
+/** A raw, UUID-bound snapshot for renumber planning; no identity allocation or canonical writes. */
+export declare function readEntityRenumberSnapshot(storeRoot: string): {
+    workspaceId: string;
+    storeId: string;
+    storeLocator: string;
+    registrationVersion: string;
+    entries: {
+        entityId: string;
+        documentLocator: string;
+        text: string;
+        mapping: string;
+        mappingVersion: string;
+    }[];
+    referenceNamespaces: {
+        entityId: string;
+        displayId: string;
+        storeId: string;
+        workspaceId: string;
+    }[];
+};
+/** Supply a validated snapshot while retaining the same store ownership through publication. */
+export declare function withEntityRenumberSnapshot<T>(storeRoot: string, act: (snapshot: ReturnType<typeof readEntityRenumberSnapshot>, assertCurrent: () => void) => T | Promise<T>): Promise<T>;
+export declare function writeEntityRepository(storeRoot: string, spec: Spec, targetPath: string, expectedVersion: string | undefined, legacyWrite: () => Promise<{
+    version: string;
+}>): Promise<{
+    version: string;
+}>;
+/** Inspection is not authorization to execute a journal or remove its lock. */
+export declare function planEntityRecovery(storeRoot: string): {
+    sourceOwner?: {
+        token: string;
+        version: string;
+    } | undefined;
+    lockOwner?: {
+        token: string;
+        version: string;
+    } | undefined;
+    schema: "holmes-entity-recovery/1";
+    workspaceId: string;
+    storeLocator: string;
+    operations: ({
+        operationId: string;
+        kind: "aborted";
+        storeId: string;
+        journalVersion: null;
+        state: "empty";
+        targets: Array<{
+            locator: string;
+            beforeVersion: string | null;
+            afterVersion: string | null;
+            currentVersion: string | null;
+            state: "unchanged" | "applied" | "unapplied" | "conflict";
+        }>;
+        inventoryConflicts: string[];
+        leftovers: string[];
+    } | {
+        retired?: true | undefined;
+        operationId: string;
+        kind: "adoption" | "write" | "legacy-renumber";
+        storeId: string | null;
+        journalVersion: string;
+        state: string;
+        targets: {
+            locator: string;
+            beforeVersion: string | null;
+            afterVersion: string | null;
+            currentVersion: string | null;
+            state: string;
+        }[];
+        inventoryConflicts: string[];
+        leftovers?: undefined;
+    })[];
+};
+type EntityRecoveryPlan = ReturnType<typeof planEntityRecovery>;
+export type RecoverySpecPolicy = (before: Spec | null, after: Spec, inventory: Spec[]) => () => void;
+export declare function validateEntityRecoveryPlan(value: unknown): EntityRecoveryPlan;
+export declare function entityRecoveryTarget(plan: EntityRecoveryPlan): string;
+export declare function recoverEntityStore(storeRoot: string, plan: EntityRecoveryPlan, policy?: RecoverySpecPolicy, onComplete?: () => void): ReturnType<typeof inspectEntityStore>;
+export declare function adoptEntityStore(storeRoot: string, plan: EntityAdoptionPlan): ReturnType<typeof inspectEntityStore>;