@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/relationship-history.js

@@ -1,520 +1,5 @@
-/**
- * @module sdk/relationship-history
- *
- * Provides an append-only, storage-independent relationship event ledger with
- * optimistic concurrency, deterministic replay, snapshots, and cursor pages.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bb5dfa6f-b60f-55f2-ae17-3dbcaaff1b47")}catch(e){}}();
-import { createQueryFingerprint, decodeQueryCursorState, paginateQueryRows, } from "./pagination.js";
-import { constants } from "node:fs";
-import { lstat, mkdir, open } from "node:fs/promises";
-import path from "node:path";
-import { acquireLock } from "../core/lock/lock.js";
-import { isFileMissingError, writeFileAtomic } from "../core/fs/fs-utils.js";
-import { stableStringify } from "../core/shared/serialization.js";
-import { RelationshipGraph, createRelationshipKindRegistry, } from "./relationships.js";
-function requiredText(value, field) {
-    if (typeof value !== "string" || value.trim().length === 0)
-        throw new TypeError(`Relationship event ${field} must be non-empty`);
-    return value.trim();
-}
-function edgeIdentity(edge, registry) {
-    const definition = registry.require(edge.kind);
-    const endpoints = definition.direction === "undirected"
-        ? [edge.source, edge.target].sort().join("\u0000")
-        : `${edge.source}\u0000${edge.target}`;
-    return `${definition.kind}\u0000${endpoints}`;
-}
-function freezeEdge(edge) {
-    return Object.freeze({
-        ...edge,
-        ...(edge.payload === undefined
-            ? {}
-            : { payload: Object.freeze(structuredClone(edge.payload)) }),
-    });
-}
-function assertCardinality(candidate, excludeRelationshipId, registry, indexes) {
-    const definition = registry.require(candidate.kind);
-    const outgoingOwner = indexes.outgoingOne.get(`${definition.kind}\u0000${candidate.source}`);
-    if (outgoingOwner !== undefined && outgoingOwner !== excludeRelationshipId)
-        throw new TypeError(`Relationship outgoing cardinality exceeded for ${definition.kind}`);
-    const incomingOwner = indexes.incomingOne.get(`${definition.kind}\u0000${candidate.target}`);
-    if (incomingOwner !== undefined && incomingOwner !== excludeRelationshipId)
-        throw new TypeError(`Relationship incoming cardinality exceeded for ${definition.kind}`);
-    const identity = edgeIdentity(candidate, registry);
-    const identityOwner = indexes.identities.get(identity);
-    if (identityOwner !== undefined && identityOwner !== excludeRelationshipId)
-        throw new TypeError(`Relationship edge already active: ${identity}`);
-}
-function replayEvents(events) {
-    const active = new Map();
-    for (const event of events) {
-        if (event.action === "remove")
-            active.delete(event.relationshipId);
-        else
-            active.set(event.relationshipId, event.edge);
-    }
-    return active;
-}
-function normalizeEventHeader(input, currentVersion, eventIds) {
-    if (input.expectedVersion !== undefined &&
-        input.expectedVersion !== currentVersion)
-        throw new TypeError(`Relationship event version conflict: expected ${input.expectedVersion}, current ${currentVersion}`);
-    const eventId = requiredText(input.eventId, "eventId");
-    if (eventIds.has(eventId))
-        throw new TypeError(`Relationship event already exists: ${eventId}`);
-    if (input.action !== "add" &&
-        input.action !== "remove" &&
-        input.action !== "supersede")
-        throw new TypeError(`Unknown relationship event action: ${input.action}`);
-    if (!Number.isFinite(Date.parse(input.timestamp)))
-        throw new TypeError("Relationship event timestamp must be valid");
-    return {
-        eventId,
-        relationshipId: requiredText(input.relationshipId, "relationshipId"),
-        author: requiredText(input.author, "author"),
-        timestamp: new Date(input.timestamp).toISOString(),
-    };
-}
-function resolveMutationEdge(input, relationshipId, active, nodes, registry, indexes) {
-    const isActive = active.has(relationshipId);
-    if (input.action === "add" && isActive)
-        throw new TypeError(`Relationship is already active: ${relationshipId}`);
-    if (input.action !== "add" && !isActive)
-        throw new TypeError(`Relationship is not active: ${relationshipId}`);
-    if (input.action === "remove")
-        return undefined;
-    if (!input.edge)
-        throw new TypeError(`Relationship ${input.action} event requires an edge`);
-    const source = typeof input.edge.source === "string" ? input.edge.source.trim() : "";
-    const target = typeof input.edge.target === "string" ? input.edge.target.trim() : "";
-    if (!nodes.has(source) || !nodes.has(target))
-        throw new TypeError(`Relationship endpoint not found: ${source} -> ${target}`);
-    const canonical = new RelationshipGraph([source, target], [input.edge], registry).edges()[0];
-    assertCardinality(canonical, relationshipId, registry, indexes);
-    return freezeEdge(canonical);
-}
-/**
- * Append-only in-memory reference ledger. Durable adapters can persist the
- * returned immutable events while reusing the same replay and validation model.
- */
-export class RelationshipEventLog {
-    #nodes;
-    #registry;
-    #events = [];
-    #eventIds = new Set();
-    #active = new Map();
-    #cardinalityIndexes = {
-        identities: new Map(),
-        outgoingOne: new Map(),
-        incomingOne: new Map(),
-    };
-    /** Create an empty relationship ledger for a fixed node universe. */
-    constructor(nodes, options = {}) {
-        this.#nodes = new Set([...nodes]
-            .filter((node) => typeof node === "string")
-            .map((node) => node.trim())
-            .filter(Boolean));
-        this.#registry = options.registry ?? createRelationshipKindRegistry();
-    }
-    /** Current append sequence. */
-    get version() {
-        return this.#events.length;
-    }
-    /** Return an immutable copy of the full event stream. */
-    events() {
-        return Object.freeze([...this.#events]);
-    }
-    /**
-     * Iterate a stable event prefix in immutable, bounded batches. Consumers can
-     * build streaming projections without copying or exposing the mutable ledger.
-     * `fromVersion === toVersion + 1` is the intentional empty checkpoint range;
-     * larger watermarks are rejected as invalid for the selected prefix.
-     */
-    *stream(options = {}) {
-        const fromVersion = options.fromVersion ?? 1;
-        const toVersion = options.toVersion ?? this.version;
-        const batchSize = options.batchSize ?? 100;
-        if (!Number.isInteger(fromVersion) || fromVersion < 1)
-            throw new TypeError("Relationship event stream fromVersion must be positive");
-        if (!Number.isInteger(toVersion) ||
-            toVersion < 0 ||
-            toVersion > this.version)
-            throw new TypeError(`Relationship event stream toVersion out of range: ${toVersion}`);
-        if (!Number.isInteger(batchSize) || batchSize < 1)
-            throw new TypeError("Relationship event stream batchSize must be positive");
-        if (fromVersion > toVersion + 1)
-            throw new TypeError("Relationship event stream fromVersion exceeds the selected prefix");
-        for (let offset = fromVersion - 1; offset < toVersion; offset += batchSize) {
-            yield Object.freeze(this.#events.slice(offset, Math.min(offset + batchSize, toVersion)));
-        }
-    }
-    /** Fold a selected immutable event prefix into caller-owned domain state. */
-    project(initialState, reducer, options = {}) {
-        if (typeof reducer !== "function")
-            throw new TypeError("Relationship event projection requires a reducer");
-        let state = initialState;
-        let processed = 0;
-        let finalEvent;
-        for (const batch of this.stream({ ...options, batchSize: 256 })) {
-            for (const event of batch) {
-                state = reducer(state, event);
-                processed += 1;
-                finalEvent = event;
-            }
-        }
-        return Object.freeze({
-            state,
-            version: finalEvent?.sequence ?? Math.max(0, (options.fromVersion ?? 1) - 1),
-            processed,
-            ...(finalEvent === undefined ? {} : { asOf: finalEvent.timestamp }),
-        });
-    }
-    /** Add one active relationship to constant-time validation indexes. */
-    #indexActive(relationshipId, edge) {
-        const definition = this.#registry.require(edge.kind);
-        this.#cardinalityIndexes.identities.set(edgeIdentity(edge, this.#registry), relationshipId);
-        if (definition.outgoing === "one")
-            this.#cardinalityIndexes.outgoingOne.set(`${definition.kind}\u0000${edge.source}`, relationshipId);
-        if (definition.incoming === "one")
-            this.#cardinalityIndexes.incomingOne.set(`${definition.kind}\u0000${edge.target}`, relationshipId);
-    }
-    /** Remove one superseded or deleted relationship from validation indexes. */
-    #unindexActive(edge) {
-        const definition = this.#registry.require(edge.kind);
-        this.#cardinalityIndexes.identities.delete(edgeIdentity(edge, this.#registry));
-        if (definition.outgoing === "one")
-            this.#cardinalityIndexes.outgoingOne.delete(`${definition.kind}\u0000${edge.source}`);
-        if (definition.incoming === "one")
-            this.#cardinalityIndexes.incomingOne.delete(`${definition.kind}\u0000${edge.target}`);
-    }
-    /** Validate and append one attributable relationship mutation. */
-    append(input) {
-        const header = normalizeEventHeader(input, this.version, this.#eventIds);
-        const previous = this.#active.get(header.relationshipId);
-        const edge = resolveMutationEdge(input, header.relationshipId, this.#active, this.#nodes, this.#registry, this.#cardinalityIndexes);
-        const event = Object.freeze({
-            eventId: header.eventId,
-            relationshipId: header.relationshipId,
-            action: input.action,
-            ...(edge === undefined ? {} : { edge }),
-            author: header.author,
-            timestamp: header.timestamp,
-            ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),
-            sequence: this.version + 1,
-        });
-        this.#events.push(event);
-        this.#eventIds.add(header.eventId);
-        if (previous)
-            this.#unindexActive(previous);
-        if (input.action === "remove")
-            this.#active.delete(header.relationshipId);
-        else {
-            this.#active.set(header.relationshipId, edge);
-            this.#indexActive(header.relationshipId, edge);
-        }
-        return event;
-    }
-    /** Materialize an exact point-in-time graph without mutating the ledger. */
-    snapshot(options = {}) {
-        if (options.atVersion !== undefined && options.atTimestamp !== undefined)
-            throw new TypeError("Relationship snapshot accepts one target");
-        let included;
-        if (options.atTimestamp !== undefined) {
-            const timestamp = Date.parse(options.atTimestamp);
-            if (!Number.isFinite(timestamp))
-                throw new TypeError("Relationship snapshot timestamp must be valid");
-            included = this.#events.filter((event) => Date.parse(event.timestamp) <= timestamp);
-        }
-        else {
-            const version = options.atVersion ?? this.version;
-            if (!Number.isInteger(version) || version < 0 || version > this.version)
-                throw new TypeError(`Relationship snapshot version out of range: ${version}`);
-            included = this.#events.slice(0, version);
-        }
-        const active = replayEvents(included);
-        const graph = new RelationshipGraph(this.#nodes, active.values(), this.#registry);
-        return Object.freeze({
-            version: included.at(-1)?.sequence ?? 0,
-            ...(included.at(-1) ? { asOf: included.at(-1).timestamp } : {}),
-            edges: graph.edges(),
-            graph,
-        });
-    }
-    /** Page the immutable event stream with a cursor bound to this log version. */
-    page(options) {
-        if (!Number.isInteger(options.limit) || options.limit < 1)
-            throw new TypeError("Relationship event page limit must be positive");
-        const fingerprint = createQueryFingerprint("relationship-events", {
-            order: "append-sequence",
-        });
-        const snapshot = options.cursor === undefined
-            ? this.version
-            : Number(decodeQueryCursorState(options.cursor, fingerprint).snapshot);
-        if (!Number.isSafeInteger(snapshot) ||
-            snapshot < 0 ||
-            snapshot > this.version)
-            throw new TypeError("Relationship event cursor snapshot version is invalid");
-        const page = paginateQueryRows(this.#events.slice(0, snapshot), {
-            cursor: options.cursor,
-            fingerprint,
-            limit: options.limit,
-            readId: (event) => event.eventId,
-            snapshot: String(snapshot),
-        });
-        return {
-            version: snapshot,
-            events: page.rows,
-            hasMore: page.has_more,
-            ...(page.next_cursor ? { nextCursor: page.next_cursor } : {}),
-        };
-    }
-}
-const RELATIONSHIP_STORE_LOCK_ID = "relationship-event-store";
-const RELATIONSHIP_NOFOLLOW_FLAG = constants.O_NOFOLLOW;
-function acquireRelationshipStoreLock(pmRoot) {
-    return acquireLock(pmRoot, RELATIONSHIP_STORE_LOCK_ID, 30, `relationship-store:${process.pid}`, false, false, 3_000);
-}
-async function resolveRelationshipEventStorePath(pmRoot, relativePath = "relationships/events.jsonl") {
-    const root = path.resolve(pmRoot);
-    const target = path.resolve(root, relativePath);
-    const relative = path.relative(root, target);
-    if (relative.length === 0)
-        throw new TypeError("Relationship event path must name a file within the tracker root");
-    if (relative === ".." ||
-        relative.startsWith(`..${path.sep}`) ||
-        path.isAbsolute(relative))
-        throw new TypeError("Relationship event path must stay within the tracker root");
-    await mkdir(root, { recursive: true });
-    const rootStats = await lstat(root);
-    if (rootStats.isSymbolicLink())
-        throw new TypeError("Relationship event tracker root must not be a symbolic link");
-    let current = root;
-    for (const segment of relative.split(path.sep)) {
-        current = path.join(current, segment);
-        try {
-            if ((await lstat(current)).isSymbolicLink())
-                throw new TypeError("Relationship event path must not contain symbolic links");
-        }
-        catch (error) {
-            if (isFileMissingError(error))
-                break;
-            throw error;
-        }
-    }
-    return target;
-}
-async function loadRelationshipEventLog(target, nodes, registry) {
-    const log = new RelationshipEventLog(nodes, { registry });
-    let raw;
-    let handle;
-    try {
-        handle = await open(target, constants.O_RDONLY | RELATIONSHIP_NOFOLLOW_FLAG);
-        raw = await handle.readFile("utf8");
-    }
-    catch (error) {
-        if (isFileMissingError(error))
-            return { log, raw: "" };
-        throw error;
-    }
-    finally {
-        await handle?.close();
-    }
-    const lines = raw.split("\n");
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index].trim();
-        if (!line)
-            continue;
-        let stored;
-        try {
-            stored = JSON.parse(line);
-        }
-        catch {
-            throw new TypeError(`Invalid relationship event JSONL at line ${index + 1}`);
-        }
-        if (stored.sequence !== log.version + 1)
-            throw new TypeError(`Invalid relationship event sequence at line ${index + 1}`);
-        log.append({
-            eventId: stored.eventId,
-            relationshipId: stored.relationshipId,
-            action: stored.action,
-            ...(stored.edge === undefined ? {} : { edge: stored.edge }),
-            author: stored.author,
-            timestamp: stored.timestamp,
-            ...(stored.reason === undefined ? {} : { reason: stored.reason }),
-            expectedVersion: log.version,
-        });
-    }
-    return { log, raw };
-}
-/** Return whether an existing immutable event exactly represents one input. */
-function relationshipEventMatchesInput(event, input, nodes, registry) {
-    const timestamp = Date.parse(input.timestamp);
-    let edge;
-    if (input.action !== "remove" && input.edge !== undefined)
-        edge = new RelationshipGraph(nodes, [input.edge], registry).edges()[0];
-    return (event.eventId === input.eventId.trim() &&
-        event.relationshipId === input.relationshipId.trim() &&
-        event.action === input.action &&
-        event.author === input.author.trim() &&
-        Number.isFinite(timestamp) &&
-        event.timestamp === new Date(timestamp).toISOString() &&
-        event.reason === (input.reason?.trim() || undefined) &&
-        stableStringify(event.edge) === stableStringify(edge));
-}
-/**
- * Lock-serialized durable JSONL adapter for {@link RelationshipEventLog}.
- * Every append replays the current stream while holding the workspace lock, so
- * independent processes share optimistic versions without lost updates.
- */
-export class RelationshipEventStore {
-    #pmRoot;
-    #nodes;
-    #registry;
-    #path;
-    #log;
-    constructor(options, nodes, target, log) {
-        this.#pmRoot = options.pmRoot;
-        this.#nodes = nodes;
-        this.#registry = options.registry;
-        this.#path = target;
-        this.#log = log;
-    }
-    /** Open and validate an existing stream or create an empty store view. */
-    static async open(options) {
-        const nodes = Object.freeze([...options.nodes]);
-        const target = await resolveRelationshipEventStorePath(options.pmRoot, options.relativePath);
-        const release = await acquireRelationshipStoreLock(options.pmRoot);
-        try {
-            await resolveRelationshipEventStorePath(options.pmRoot, target);
-            const { log } = await loadRelationshipEventLog(target, nodes, options.registry);
-            return new RelationshipEventStore(options, nodes, target, log);
-        }
-        finally {
-            await release();
-        }
-    }
-    /** Absolute JSONL path, exposed for diagnostics and backup tooling. */
-    get path() {
-        return this.#path;
-    }
-    /** Refresh from durable history and return the current validated append sequence. */
-    async currentVersion() {
-        this.#log = await this.#refreshFromDurableHistory();
-        return this.#log.version;
-    }
-    /** Append one event after refreshing under the shared workspace lock. */
-    async append(input) {
-        const release = await acquireRelationshipStoreLock(this.#pmRoot);
-        try {
-            const target = await resolveRelationshipEventStorePath(this.#pmRoot, this.#path);
-            const { log: refreshed } = await loadRelationshipEventLog(target, this.#nodes, this.#registry);
-            const event = refreshed.append(input);
-            await mkdir(path.dirname(target), { recursive: true });
-            await resolveRelationshipEventStorePath(this.#pmRoot, target);
-            const handle = await open(target, constants.O_APPEND |
-                constants.O_CREAT |
-                constants.O_WRONLY |
-                RELATIONSHIP_NOFOLLOW_FLAG);
-            try {
-                await handle.appendFile(`${JSON.stringify(event)}\n`, "utf8");
-            }
-            finally {
-                await handle.close();
-            }
-            this.#log = refreshed;
-            return event;
-        }
-        finally {
-            await release();
-        }
-    }
-    /**
-     * Validate and publish a relationship-event batch as one durable replacement.
-     * The shared writer lock covers refresh, collision checks, full in-memory
-     * validation, and atomic rename. A validation or filesystem failure therefore
-     * leaves the previous JSONL stream byte-for-byte unchanged. This path is
-     * intended for migrations and bulk imports; latency-sensitive single events
-     * should continue to use {@link append} and its O_APPEND write.
-     */
-    async appendBatch(inputs, options = {}) {
-        const release = await acquireRelationshipStoreLock(this.#pmRoot);
-        try {
-            const target = await resolveRelationshipEventStorePath(this.#pmRoot, this.#path);
-            const { log: refreshed, raw } = await loadRelationshipEventLog(target, this.#nodes, this.#registry);
-            const versionBefore = refreshed.version;
-            const existing = new Map(refreshed.events().map((event) => [event.eventId, event]));
-            const appended = [];
-            const skippedEventIds = [];
-            for (const input of inputs) {
-                const eventId = input.eventId.trim();
-                const stored = existing.get(eventId);
-                if (stored !== undefined) {
-                    if (options.existingEventPolicy === "skip_identical" &&
-                        relationshipEventMatchesInput(stored, input, this.#nodes, this.#registry)) {
-                        skippedEventIds.push(stored.eventId);
-                        continue;
-                    }
-                    if (options.existingEventPolicy === "skip_identical")
-                        throw new TypeError(`Relationship event id collision with different content: ${eventId}`);
-                }
-                const event = refreshed.append(input);
-                existing.set(event.eventId, event);
-                appended.push(event);
-            }
-            if (appended.length > 0) {
-                const prefix = raw.length === 0 || raw.endsWith("\n") ? raw : `${raw}\n`;
-                await mkdir(path.dirname(target), { recursive: true });
-                await resolveRelationshipEventStorePath(this.#pmRoot, target);
-                await writeFileAtomic(target, `${prefix}${appended.map((event) => JSON.stringify(event)).join("\n")}\n`);
-            }
-            this.#log = refreshed;
-            return Object.freeze({
-                version_before: versionBefore,
-                version_after: refreshed.version,
-                appended: Object.freeze(appended),
-                skipped_event_ids: Object.freeze(skippedEventIds),
-            });
-        }
-        finally {
-            await release();
-        }
-    }
-    /** Refresh from durable history and materialize an exact validated snapshot. */
-    async snapshot(options = {}) {
-        this.#log = await this.#refreshFromDurableHistory();
-        return this.#log.snapshot(options);
-    }
-    /** Refresh from durable history and page immutable events. */
-    async page(options) {
-        this.#log = await this.#refreshFromDurableHistory();
-        return this.#log.page(options);
-    }
-    /**
-     * Refresh once under the shared store lock, then stream a coherent immutable
-     * prefix without holding the writer lock while the consumer processes batches.
-     */
-    async *stream(options = {}) {
-        this.#log = await this.#refreshFromDurableHistory();
-        yield* this.#log.stream(options);
-    }
-    /** Refresh once and fold a coherent durable prefix into application state. */
-    async project(initialState, reducer, options = {}) {
-        this.#log = await this.#refreshFromDurableHistory();
-        return this.#log.project(initialState, reducer, options);
-    }
-    /** Serialize a durable refresh with writers so readers never observe a torn JSONL tail. */
-    async #refreshFromDurableHistory() {
-        const release = await acquireRelationshipStoreLock(this.#pmRoot);
-        try {
-            const target = await resolveRelationshipEventStorePath(this.#pmRoot, this.#path);
-            return (await loadRelationshipEventLog(target, this.#nodes, this.#registry)).log;
-        }
-        finally {
-            await release();
-        }
-    }
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e57a9bca-1190-5ffd-bb7d-d76a22fc9e57")}catch(e2){}})();import{createQueryFingerprint,decodeQueryCursorState,paginateQueryRows}from"./pagination.js";import{constants}from"node:fs";import{lstat,mkdir,open}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{stableStringify}from"../core/shared/serialization.js";import{RelationshipGraph,createRelationshipKindRegistry}from"./relationships.js";function requiredText(value,field){if(typeof value!=="string"||value.trim().length===0)throw new TypeError(`Relationship event ${field} must be non-empty`);return value.trim()}function edgeIdentity(edge,registry){const definition=registry.require(edge.kind);const endpoints=definition.direction==="undirected"?[edge.source,edge.target].sort().join("\0"):`${edge.source}\0${edge.target}`;return`${definition.kind}\0${endpoints}`}function freezeEdge(edge){return Object.freeze({...edge,...edge.payload===void 0?{}:{payload:Object.freeze(structuredClone(edge.payload))}})}function assertCardinality(candidate,excludeRelationshipId,registry,indexes){const definition=registry.require(candidate.kind);const outgoingOwner=indexes.outgoingOne.get(`${definition.kind}\0${candidate.source}`);if(outgoingOwner!==void 0&&outgoingOwner!==excludeRelationshipId)throw new TypeError(`Relationship outgoing cardinality exceeded for ${definition.kind}`);const incomingOwner=indexes.incomingOne.get(`${definition.kind}\0${candidate.target}`);if(incomingOwner!==void 0&&incomingOwner!==excludeRelationshipId)throw new TypeError(`Relationship incoming cardinality exceeded for ${definition.kind}`);const identity=edgeIdentity(candidate,registry);const identityOwner=indexes.identities.get(identity);if(identityOwner!==void 0&&identityOwner!==excludeRelationshipId)throw new TypeError(`Relationship edge already active: ${identity}`)}function replayEvents(events){const active=new Map;for(const event of events){if(event.action==="remove")active.delete(event.relationshipId);else active.set(event.relationshipId,event.edge)}return active}function normalizeEventHeader(input,currentVersion,eventIds){if(input.expectedVersion!==void 0&&input.expectedVersion!==currentVersion)throw new TypeError(`Relationship event version conflict: expected ${input.expectedVersion}, current ${currentVersion}`);const eventId=requiredText(input.eventId,"eventId");if(eventIds.has(eventId))throw new TypeError(`Relationship event already exists: ${eventId}`);if(input.action!=="add"&&input.action!=="remove"&&input.action!=="supersede")throw new TypeError(`Unknown relationship event action: ${input.action}`);if(!Number.isFinite(Date.parse(input.timestamp)))throw new TypeError("Relationship event timestamp must be valid");return{eventId,relationshipId:requiredText(input.relationshipId,"relationshipId"),author:requiredText(input.author,"author"),timestamp:new Date(input.timestamp).toISOString()}}function resolveMutationEdge(input,relationshipId,active,nodes,registry,indexes){const isActive=active.has(relationshipId);if(input.action==="add"&&isActive)throw new TypeError(`Relationship is already active: ${relationshipId}`);if(input.action!=="add"&&!isActive)throw new TypeError(`Relationship is not active: ${relationshipId}`);if(input.action==="remove")return void 0;if(!input.edge)throw new TypeError(`Relationship ${input.action} event requires an edge`);const source=typeof input.edge.source==="string"?input.edge.source.trim():"";const target=typeof input.edge.target==="string"?input.edge.target.trim():"";if(!nodes.has(source)||!nodes.has(target))throw new TypeError(`Relationship endpoint not found: ${source} -> ${target}`);const canonical=new RelationshipGraph([source,target],[input.edge],registry).edges()[0];assertCardinality(canonical,relationshipId,registry,indexes);return freezeEdge(canonical)}class RelationshipEventLog{#nodes;#registry;#events=[];#eventIds=new Set;#active=new Map;#cardinalityIndexes={identities:new Map,outgoingOne:new Map,incomingOne:new Map};constructor(nodes,options={}){this.#nodes=new Set([...nodes].filter(node=>typeof node==="string").map(node=>node.trim()).filter(Boolean));this.#registry=options.registry??createRelationshipKindRegistry()}get version(){return this.#events.length}events(){return Object.freeze([...this.#events])}*stream(options={}){const fromVersion=options.fromVersion??1;const toVersion=options.toVersion??this.version;const batchSize=options.batchSize??100;if(!Number.isInteger(fromVersion)||fromVersion<1)throw new TypeError("Relationship event stream fromVersion must be positive");if(!Number.isInteger(toVersion)||toVersion<0||toVersion>this.version)throw new TypeError(`Relationship event stream toVersion out of range: ${toVersion}`);if(!Number.isInteger(batchSize)||batchSize<1)throw new TypeError("Relationship event stream batchSize must be positive");if(fromVersion>toVersion+1)throw new TypeError("Relationship event stream fromVersion exceeds the selected prefix");for(let offset=fromVersion-1;offset<toVersion;offset+=batchSize){yield Object.freeze(this.#events.slice(offset,Math.min(offset+batchSize,toVersion)))}}project(initialState,reducer,options={}){if(typeof reducer!=="function")throw new TypeError("Relationship event projection requires a reducer");let state=initialState;let processed=0;let finalEvent;for(const batch of this.stream({...options,batchSize:256})){for(const event of batch){state=reducer(state,event);processed+=1;finalEvent=event}}return Object.freeze({state,version:finalEvent?.sequence??Math.max(0,(options.fromVersion??1)-1),processed,...finalEvent===void 0?{}:{asOf:finalEvent.timestamp}})}#indexActive(relationshipId,edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.set(edgeIdentity(edge,this.#registry),relationshipId);if(definition.outgoing==="one")this.#cardinalityIndexes.outgoingOne.set(`${definition.kind}\0${edge.source}`,relationshipId);if(definition.incoming==="one")this.#cardinalityIndexes.incomingOne.set(`${definition.kind}\0${edge.target}`,relationshipId)}#unindexActive(edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.delete(edgeIdentity(edge,this.#registry));if(definition.outgoing==="one")this.#cardinalityIndexes.outgoingOne.delete(`${definition.kind}\0${edge.source}`);if(definition.incoming==="one")this.#cardinalityIndexes.incomingOne.delete(`${definition.kind}\0${edge.target}`)}append(input){const header=normalizeEventHeader(input,this.version,this.#eventIds);const previous=this.#active.get(header.relationshipId);const edge=resolveMutationEdge(input,header.relationshipId,this.#active,this.#nodes,this.#registry,this.#cardinalityIndexes);const event=Object.freeze({eventId:header.eventId,relationshipId:header.relationshipId,action:input.action,...edge===void 0?{}:{edge},author:header.author,timestamp:header.timestamp,...input.reason?.trim()?{reason:input.reason.trim()}:{},sequence:this.version+1});this.#events.push(event);this.#eventIds.add(header.eventId);if(previous)this.#unindexActive(previous);if(input.action==="remove")this.#active.delete(header.relationshipId);else{this.#active.set(header.relationshipId,edge);this.#indexActive(header.relationshipId,edge)}return event}snapshot(options={}){if(options.atVersion!==void 0&&options.atTimestamp!==void 0)throw new TypeError("Relationship snapshot accepts one target");let included;if(options.atTimestamp!==void 0){const timestamp=Date.parse(options.atTimestamp);if(!Number.isFinite(timestamp))throw new TypeError("Relationship snapshot timestamp must be valid");included=this.#events.filter(event=>Date.parse(event.timestamp)<=timestamp)}else{const version=options.atVersion??this.version;if(!Number.isInteger(version)||version<0||version>this.version)throw new TypeError(`Relationship snapshot version out of range: ${version}`);included=this.#events.slice(0,version)}const active=replayEvents(included);const graph=new RelationshipGraph(this.#nodes,active.values(),this.#registry);return Object.freeze({version:included.at(-1)?.sequence??0,...included.at(-1)?{asOf:included.at(-1).timestamp}:{},edges:graph.edges(),graph})}page(options){if(!Number.isInteger(options.limit)||options.limit<1)throw new TypeError("Relationship event page limit must be positive");const fingerprint=createQueryFingerprint("relationship-events",{order:"append-sequence"});const snapshot=options.cursor===void 0?this.version:Number(decodeQueryCursorState(options.cursor,fingerprint).snapshot);if(!Number.isSafeInteger(snapshot)||snapshot<0||snapshot>this.version)throw new TypeError("Relationship event cursor snapshot version is invalid");const page=paginateQueryRows(this.#events.slice(0,snapshot),{cursor:options.cursor,fingerprint,limit:options.limit,readId:event=>event.eventId,snapshot:String(snapshot)});return{version:snapshot,events:page.rows,hasMore:page.has_more,...page.next_cursor?{nextCursor:page.next_cursor}:{}}}}const RELATIONSHIP_STORE_LOCK_ID="relationship-event-store";const RELATIONSHIP_NOFOLLOW_FLAG=constants.O_NOFOLLOW;function acquireRelationshipStoreLock(pmRoot){return acquireLock(pmRoot,RELATIONSHIP_STORE_LOCK_ID,30,`relationship-store:${process.pid}`,false,false,3e3)}async function resolveRelationshipEventStorePath(pmRoot,relativePath="relationships/events.jsonl"){const root=path.resolve(pmRoot);const target=path.resolve(root,relativePath);const relative=path.relative(root,target);if(relative.length===0)throw new TypeError("Relationship event path must name a file within the tracker root");if(relative===".."||relative.startsWith(`..${path.sep}`)||path.isAbsolute(relative))throw new TypeError("Relationship event path must stay within the tracker root");await mkdir(root,{recursive:true});const rootStats=await lstat(root);if(rootStats.isSymbolicLink())throw new TypeError("Relationship event tracker root must not be a symbolic link");let current=root;for(const segment of relative.split(path.sep)){current=path.join(current,segment);try{if((await lstat(current)).isSymbolicLink())throw new TypeError("Relationship event path must not contain symbolic links")}catch(error){if(isFileMissingError(error))break;throw error}}return target}async function loadRelationshipEventLog(target,nodes,registry){const log=new RelationshipEventLog(nodes,{registry});let raw;let handle;try{handle=await open(target,constants.O_RDONLY|RELATIONSHIP_NOFOLLOW_FLAG);raw=await handle.readFile("utf8")}catch(error){if(isFileMissingError(error))return{log,raw:""};throw error}finally{await handle?.close()}const lines=raw.split("\n");for(let index=0;index<lines.length;index+=1){const line=lines[index].trim();if(!line)continue;let stored;try{stored=JSON.parse(line)}catch{throw new TypeError(`Invalid relationship event JSONL at line ${index+1}`)}if(stored.sequence!==log.version+1)throw new TypeError(`Invalid relationship event sequence at line ${index+1}`);log.append({eventId:stored.eventId,relationshipId:stored.relationshipId,action:stored.action,...stored.edge===void 0?{}:{edge:stored.edge},author:stored.author,timestamp:stored.timestamp,...stored.reason===void 0?{}:{reason:stored.reason},expectedVersion:log.version})}return{log,raw}}function relationshipEventMatchesInput(event,input,nodes,registry){const timestamp=Date.parse(input.timestamp);let edge;if(input.action!=="remove"&&input.edge!==void 0)edge=new RelationshipGraph(nodes,[input.edge],registry).edges()[0];return event.eventId===input.eventId.trim()&&event.relationshipId===input.relationshipId.trim()&&event.action===input.action&&event.author===input.author.trim()&&Number.isFinite(timestamp)&&event.timestamp===new Date(timestamp).toISOString()&&event.reason===(input.reason?.trim()||void 0)&&stableStringify(event.edge)===stableStringify(edge)}class RelationshipEventStore{#pmRoot;#nodes;#registry;#path;#log;constructor(options,nodes,target,log){this.#pmRoot=options.pmRoot;this.#nodes=nodes;this.#registry=options.registry;this.#path=target;this.#log=log}static async open(options){const nodes=Object.freeze([...options.nodes]);const target=await resolveRelationshipEventStorePath(options.pmRoot,options.relativePath);const release=await acquireRelationshipStoreLock(options.pmRoot);try{await resolveRelationshipEventStorePath(options.pmRoot,target);const{log}=await loadRelationshipEventLog(target,nodes,options.registry);return new RelationshipEventStore(options,nodes,target,log)}finally{await release()}}get path(){return this.#path}async currentVersion(){this.#log=await this.#refreshFromDurableHistory();return this.#log.version}async append(input){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);const{log:refreshed}=await loadRelationshipEventLog(target,this.#nodes,this.#registry);const event=refreshed.append(input);await mkdir(path.dirname(target),{recursive:true});await resolveRelationshipEventStorePath(this.#pmRoot,target);const handle=await open(target,constants.O_APPEND|constants.O_CREAT|constants.O_WRONLY|RELATIONSHIP_NOFOLLOW_FLAG);try{await handle.appendFile(`${JSON.stringify(event)}
+`,"utf8")}finally{await handle.close()}this.#log=refreshed;return event}finally{await release()}}async appendBatch(inputs,options={}){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);const{log:refreshed,raw}=await loadRelationshipEventLog(target,this.#nodes,this.#registry);const versionBefore=refreshed.version;const existing=new Map(refreshed.events().map(event=>[event.eventId,event]));const appended=[];const skippedEventIds=[];for(const input of inputs){const eventId=input.eventId.trim();const stored=existing.get(eventId);if(stored!==void 0){if(options.existingEventPolicy==="skip_identical"&&relationshipEventMatchesInput(stored,input,this.#nodes,this.#registry)){skippedEventIds.push(stored.eventId);continue}if(options.existingEventPolicy==="skip_identical")throw new TypeError(`Relationship event id collision with different content: ${eventId}`)}const event=refreshed.append(input);existing.set(event.eventId,event);appended.push(event)}if(appended.length>0){const prefix=raw.length===0||raw.endsWith("\n")?raw:`${raw}
+`;await mkdir(path.dirname(target),{recursive:true});await resolveRelationshipEventStorePath(this.#pmRoot,target);await writeFileAtomic(target,`${prefix}${appended.map(event=>JSON.stringify(event)).join("\n")}
+`)}this.#log=refreshed;return Object.freeze({version_before:versionBefore,version_after:refreshed.version,appended:Object.freeze(appended),skipped_event_ids:Object.freeze(skippedEventIds)})}finally{await release()}}async snapshot(options={}){this.#log=await this.#refreshFromDurableHistory();return this.#log.snapshot(options)}async page(options){this.#log=await this.#refreshFromDurableHistory();return this.#log.page(options)}async*stream(options={}){this.#log=await this.#refreshFromDurableHistory();yield*this.#log.stream(options)}async project(initialState,reducer,options={}){this.#log=await this.#refreshFromDurableHistory();return this.#log.project(initialState,reducer,options)}async#refreshFromDurableHistory(){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);return(await loadRelationshipEventLog(target,this.#nodes,this.#registry)).log}finally{await release()}}}export{RelationshipEventLog,RelationshipEventStore};
 //# sourceMappingURL=relationship-history.js.map
-//# debugId=bb5dfa6f-b60f-55f2-ae17-3dbcaaff1b47

package/dist/sdk/relationship-kinds/contract.js

@@ -1,23 +1,2 @@
-/**
- * @module sdk/relationship-kinds/contract
- *
- * Dependency-free relationship ontology shared by contracts and graph runtime.
- */
-/** Stable built-in relationship ontology without graph or storage dependencies. */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="aa7d04c7-b057-569c-816a-f53322c74261")}catch(e){}}();
-export const BUILTIN_RELATIONSHIP_KINDS = [
-    { kind: "blocked_by", direction: "directed", traversal: "ordering", inverse: "blocks", ordering: true, precedence: "target_before_source", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["depends_on"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "blocks", direction: "directed", traversal: "ordering", inverse: "blocked_by", ordering: true, precedence: "source_before_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "parent", direction: "directed", traversal: "hierarchy", outcomeTraversal: "source_to_target", inverse: "child", ordering: false, hierarchy: true, hierarchyDirection: "target_parent", outgoing: "one", incoming: "many", lifecycle: "supersedable", aliases: ["child_of", "epic"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "child", direction: "directed", traversal: "hierarchy", outcomeTraversal: "target_to_source", inverse: "parent", ordering: false, hierarchy: true, hierarchyDirection: "source_parent", outgoing: "many", incoming: "one", lifecycle: "supersedable", aliases: ["parent_child", "task"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "related", direction: "undirected", traversal: "association", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", aliases: ["related_to"], compatibilityVersion: 1, allowSelf: false },
-    { kind: "discovered_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "incident_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "implements", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "recurs_from", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, temporalOrder: "source_after_target", hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "verifies", direction: "directed", traversal: "semantic", outcomeTraversal: "source_to_target", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "persistent", compatibilityVersion: 1, allowSelf: false },
-    { kind: "supersedes", direction: "directed", traversal: "semantic", outcomeTraversal: "both", ordering: false, hierarchy: false, outgoing: "many", incoming: "many", lifecycle: "supersedable", compatibilityVersion: 1, allowSelf: false },
-];
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4c00e38a-27df-5315-91e8-d35c03ed6bf3")}catch(e2){}})();const BUILTIN_RELATIONSHIP_KINDS=[{kind:"blocked_by",direction:"directed",traversal:"ordering",inverse:"blocks",ordering:true,precedence:"target_before_source",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["depends_on"],compatibilityVersion:1,allowSelf:false},{kind:"blocks",direction:"directed",traversal:"ordering",inverse:"blocked_by",ordering:true,precedence:"source_before_target",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"parent",direction:"directed",traversal:"hierarchy",outcomeTraversal:"source_to_target",inverse:"child",ordering:false,hierarchy:true,hierarchyDirection:"target_parent",outgoing:"one",incoming:"many",lifecycle:"supersedable",aliases:["child_of","epic"],compatibilityVersion:1,allowSelf:false},{kind:"child",direction:"directed",traversal:"hierarchy",outcomeTraversal:"target_to_source",inverse:"parent",ordering:false,hierarchy:true,hierarchyDirection:"source_parent",outgoing:"many",incoming:"one",lifecycle:"supersedable",aliases:["parent_child","task"],compatibilityVersion:1,allowSelf:false},{kind:"related",direction:"undirected",traversal:"association",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["related_to"],compatibilityVersion:1,allowSelf:false},{kind:"discovered_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"incident_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"implements",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"recurs_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,temporalOrder:"source_after_target",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"verifies",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"supersedes",direction:"directed",traversal:"semantic",outcomeTraversal:"both",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"supersedable",compatibilityVersion:1,allowSelf:false}];export{BUILTIN_RELATIONSHIP_KINDS};
 //# sourceMappingURL=contract.js.map
-//# debugId=aa7d04c7-b057-569c-816a-f53322c74261