@unbrained/pm-cli 2026.7.14 → 2026.7.15

package/dist/sdk/relationship-history.js

@@ -0,0 +1,401 @@
+/**
+ * @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]="787e8f44-80d5-554f-9232-9675cf6a8637")}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 { 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]);
+    }
+    /** 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");
+            let lastIndex = -1;
+            for (let index = this.#events.length - 1; index >= 0; index -= 1) {
+                if (Date.parse(this.#events[index].timestamp) > timestamp)
+                    continue;
+                lastIndex = index;
+                break;
+            }
+            included = lastIndex === -1 ? [] : this.#events.slice(0, lastIndex + 1);
+        }
+        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.length,
+            ...(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 (error.code === "ENOENT")
+                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 (error.code === "ENOENT")
+            return log;
+        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;
+}
+/**
+ * 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 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();
+        }
+    }
+    /** 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);
+    }
+    /** 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);
+        }
+        finally {
+            await release();
+        }
+    }
+}
+//# sourceMappingURL=relationship-history.js.map
+//# debugId=787e8f44-80d5-554f-9232-9675cf6a8637

package/dist/sdk/relationship-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-history.js","sources":["sdk/relationship-history.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/relationship-history\n *\n * Provides an append-only, storage-independent relationship event ledger with\n * optimistic concurrency, deterministic replay, snapshots, and cursor pages.\n */\nimport {\n  createQueryFingerprint,\n  decodeQueryCursorState,\n  paginateQueryRows,\n} from \"./pagination.js\";\nimport { constants } from \"node:fs\";\nimport { lstat, mkdir, open, type FileHandle } from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { acquireLock } from \"../core/lock/lock.js\";\nimport {\n  RelationshipGraph,\n  RelationshipKindRegistry,\n  createRelationshipKindRegistry,\n  type RelationshipEdge,\n} from \"./relationships.js\";\n\n/** Mutation kinds retained in the immutable relationship event stream. */\nexport type RelationshipEventAction = \"add\" | \"remove\" | \"supersede\";\n\n/** Caller-authored relationship mutation before its sequence is assigned. */\nexport interface RelationshipEventInput {\n  /** Globally unique idempotency key for this event. */\n  eventId: string;\n  /** Stable logical relationship identifier across superseding events. */\n  relationshipId: string;\n  /** Append, remove, or replace the logical relationship. */\n  action: RelationshipEventAction;\n  /** Edge required for add and supersede actions. */\n  edge?: RelationshipEdge;\n  /** Attributable actor responsible for the mutation. */\n  author: string;\n  /** Valid event-time timestamp. */\n  timestamp: string;\n  /** Optional optimistic concurrency precondition. */\n  expectedVersion?: number;\n  /** Optional human-readable mutation rationale. */\n  reason?: string;\n}\n\n/** One immutable sequenced relationship mutation. */\nexport interface RelationshipEvent extends Omit<\n  RelationshipEventInput,\n  \"expectedVersion\"\n> {\n  /** One-based append sequence assigned by the ledger. */\n  sequence: number;\n}\n\n/** Point-in-time materialized relationship view. */\nexport interface RelationshipSnapshot {\n  /** Final event sequence included in this snapshot. */\n  version: number;\n  /** Timestamp of the final included event, when one exists. */\n  asOf?: string;\n  /** Deterministic active edge materialization. */\n  edges: readonly RelationshipEdge[];\n  /** Immutable graph query view over the active edges. */\n  graph: RelationshipGraph;\n}\n\n/** Stable cursor page over a fixed relationship event-log version. */\nexport interface RelationshipEventPage {\n  /** Log version against which this page was produced. */\n  version: number;\n  /** Events in append order. */\n  events: RelationshipEvent[];\n  /** Whether another event page exists. */\n  hasMore: boolean;\n  /** Opaque continuation cursor when another page exists. */\n  nextCursor?: string;\n}\n\n/** Construction controls for the in-memory reference ledger. */\nexport interface RelationshipEventLogOptions {\n  /** Registry defining edge semantics and cardinality. */\n  registry?: RelationshipKindRegistry;\n}\n\n/** Filesystem controls for the durable relationship event store. */\nexport interface RelationshipEventStoreOptions extends RelationshipEventLogOptions {\n  /** Tracker root that owns the relationship history directory. */\n  pmRoot: string;\n  /** Fixed node universe validated by every replay and append. */\n  nodes: Iterable<string>;\n  /** Optional JSONL path relative to the tracker root. */\n  relativePath?: string;\n}\n\ninterface RelationshipCardinalityIndexes {\n  identities: Map<string, string>;\n  outgoingOne: Map<string, string>;\n  incomingOne: Map<string, string>;\n}\n\nfunction requiredText(value: unknown, field: string): string {\n  if (typeof value !== \"string\" || value.trim().length === 0)\n    throw new TypeError(`Relationship event ${field} must be non-empty`);\n  return value.trim();\n}\n\nfunction edgeIdentity(\n  edge: RelationshipEdge,\n  registry: RelationshipKindRegistry,\n): string {\n  const definition = registry.require(edge.kind);\n  const endpoints =\n    definition.direction === \"undirected\"\n      ? [edge.source, edge.target].sort().join(\"\\u0000\")\n      : `${edge.source}\\u0000${edge.target}`;\n  return `${definition.kind}\\u0000${endpoints}`;\n}\n\nfunction freezeEdge(edge: RelationshipEdge): RelationshipEdge {\n  return Object.freeze({\n    ...edge,\n    ...(edge.payload === undefined\n      ? {}\n      : { payload: Object.freeze(structuredClone(edge.payload)) }),\n  });\n}\n\nfunction assertCardinality(\n  candidate: RelationshipEdge,\n  excludeRelationshipId: string,\n  registry: RelationshipKindRegistry,\n  indexes: RelationshipCardinalityIndexes,\n): void {\n  const definition = registry.require(candidate.kind);\n  const outgoingOwner = indexes.outgoingOne.get(\n    `${definition.kind}\\u0000${candidate.source}`,\n  );\n  if (outgoingOwner !== undefined && outgoingOwner !== excludeRelationshipId)\n    throw new TypeError(\n      `Relationship outgoing cardinality exceeded for ${definition.kind}`,\n    );\n  const incomingOwner = indexes.incomingOne.get(\n    `${definition.kind}\\u0000${candidate.target}`,\n  );\n  if (incomingOwner !== undefined && incomingOwner !== excludeRelationshipId)\n    throw new TypeError(\n      `Relationship incoming cardinality exceeded for ${definition.kind}`,\n    );\n  const identity = edgeIdentity(candidate, registry);\n  const identityOwner = indexes.identities.get(identity);\n  if (identityOwner !== undefined && identityOwner !== excludeRelationshipId)\n    throw new TypeError(`Relationship edge already active: ${identity}`);\n}\n\nfunction replayEvents(\n  events: readonly RelationshipEvent[],\n): Map<string, RelationshipEdge> {\n  const active = new Map<string, RelationshipEdge>();\n  for (const event of events) {\n    if (event.action === \"remove\") active.delete(event.relationshipId);\n    else active.set(event.relationshipId, event.edge!);\n  }\n  return active;\n}\n\nfunction normalizeEventHeader(\n  input: RelationshipEventInput,\n  currentVersion: number,\n  eventIds: ReadonlySet<string>,\n): {\n  eventId: string;\n  relationshipId: string;\n  author: string;\n  timestamp: string;\n} {\n  if (\n    input.expectedVersion !== undefined &&\n    input.expectedVersion !== currentVersion\n  )\n    throw new TypeError(\n      `Relationship event version conflict: expected ${input.expectedVersion}, current ${currentVersion}`,\n    );\n  const eventId = requiredText(input.eventId, \"eventId\");\n  if (eventIds.has(eventId))\n    throw new TypeError(`Relationship event already exists: ${eventId}`);\n  if (\n    input.action !== \"add\" &&\n    input.action !== \"remove\" &&\n    input.action !== \"supersede\"\n  )\n    throw new TypeError(`Unknown relationship event action: ${input.action}`);\n  if (!Number.isFinite(Date.parse(input.timestamp)))\n    throw new TypeError(\"Relationship event timestamp must be valid\");\n  return {\n    eventId,\n    relationshipId: requiredText(input.relationshipId, \"relationshipId\"),\n    author: requiredText(input.author, \"author\"),\n    timestamp: new Date(input.timestamp).toISOString(),\n  };\n}\n\nfunction resolveMutationEdge(\n  input: RelationshipEventInput,\n  relationshipId: string,\n  active: ReadonlyMap<string, RelationshipEdge>,\n  nodes: ReadonlySet<string>,\n  registry: RelationshipKindRegistry,\n  indexes: RelationshipCardinalityIndexes,\n): RelationshipEdge | undefined {\n  const isActive = active.has(relationshipId);\n  if (input.action === \"add\" && isActive)\n    throw new TypeError(`Relationship is already active: ${relationshipId}`);\n  if (input.action !== \"add\" && !isActive)\n    throw new TypeError(`Relationship is not active: ${relationshipId}`);\n  if (input.action === \"remove\") return undefined;\n  if (!input.edge)\n    throw new TypeError(`Relationship ${input.action} event requires an edge`);\n  const source =\n    typeof input.edge.source === \"string\" ? input.edge.source.trim() : \"\";\n  const target =\n    typeof input.edge.target === \"string\" ? input.edge.target.trim() : \"\";\n  if (!nodes.has(source) || !nodes.has(target))\n    throw new TypeError(\n      `Relationship endpoint not found: ${source} -> ${target}`,\n    );\n  const canonical = new RelationshipGraph(\n    [source, target],\n    [input.edge],\n    registry,\n  ).edges()[0]!;\n  assertCardinality(canonical, relationshipId, registry, indexes);\n  return freezeEdge(canonical);\n}\n\n/**\n * Append-only in-memory reference ledger. Durable adapters can persist the\n * returned immutable events while reusing the same replay and validation model.\n */\nexport class RelationshipEventLog {\n  readonly #nodes: ReadonlySet<string>;\n  readonly #registry: RelationshipKindRegistry;\n  readonly #events: RelationshipEvent[] = [];\n  readonly #eventIds = new Set<string>();\n  readonly #active = new Map<string, RelationshipEdge>();\n  readonly #cardinalityIndexes: RelationshipCardinalityIndexes = {\n    identities: new Map(),\n    outgoingOne: new Map(),\n    incomingOne: new Map(),\n  };\n\n  /** Create an empty relationship ledger for a fixed node universe. */\n  public constructor(\n    nodes: Iterable<string>,\n    options: RelationshipEventLogOptions = {},\n  ) {\n    this.#nodes = new Set(\n      [...nodes]\n        .filter((node): node is string => typeof node === \"string\")\n        .map((node) => node.trim())\n        .filter(Boolean),\n    );\n    this.#registry = options.registry ?? createRelationshipKindRegistry();\n  }\n\n  /** Current append sequence. */\n  public get version(): number {\n    return this.#events.length;\n  }\n\n  /** Return an immutable copy of the full event stream. */\n  public events(): readonly RelationshipEvent[] {\n    return Object.freeze([...this.#events]);\n  }\n\n  /** Add one active relationship to constant-time validation indexes. */\n  #indexActive(relationshipId: string, edge: RelationshipEdge): void {\n    const definition = this.#registry.require(edge.kind);\n    this.#cardinalityIndexes.identities.set(\n      edgeIdentity(edge, this.#registry),\n      relationshipId,\n    );\n    if (definition.outgoing === \"one\")\n      this.#cardinalityIndexes.outgoingOne.set(\n        `${definition.kind}\\u0000${edge.source}`,\n        relationshipId,\n      );\n    if (definition.incoming === \"one\")\n      this.#cardinalityIndexes.incomingOne.set(\n        `${definition.kind}\\u0000${edge.target}`,\n        relationshipId,\n      );\n  }\n\n  /** Remove one superseded or deleted relationship from validation indexes. */\n  #unindexActive(edge: RelationshipEdge): void {\n    const definition = this.#registry.require(edge.kind);\n    this.#cardinalityIndexes.identities.delete(\n      edgeIdentity(edge, this.#registry),\n    );\n    if (definition.outgoing === \"one\")\n      this.#cardinalityIndexes.outgoingOne.delete(\n        `${definition.kind}\\u0000${edge.source}`,\n      );\n    if (definition.incoming === \"one\")\n      this.#cardinalityIndexes.incomingOne.delete(\n        `${definition.kind}\\u0000${edge.target}`,\n      );\n  }\n\n  /** Validate and append one attributable relationship mutation. */\n  public append(input: RelationshipEventInput): RelationshipEvent {\n    const header = normalizeEventHeader(input, this.version, this.#eventIds);\n    const previous = this.#active.get(header.relationshipId);\n    const edge = resolveMutationEdge(\n      input,\n      header.relationshipId,\n      this.#active,\n      this.#nodes,\n      this.#registry,\n      this.#cardinalityIndexes,\n    );\n\n    const event = Object.freeze({\n      eventId: header.eventId,\n      relationshipId: header.relationshipId,\n      action: input.action,\n      ...(edge === undefined ? {} : { edge }),\n      author: header.author,\n      timestamp: header.timestamp,\n      ...(input.reason?.trim() ? { reason: input.reason.trim() } : {}),\n      sequence: this.version + 1,\n    }) satisfies RelationshipEvent;\n    this.#events.push(event);\n    this.#eventIds.add(header.eventId);\n    if (previous) this.#unindexActive(previous);\n    if (input.action === \"remove\") this.#active.delete(header.relationshipId);\n    else {\n      this.#active.set(header.relationshipId, edge!);\n      this.#indexActive(header.relationshipId, edge!);\n    }\n    return event;\n  }\n\n  /** Materialize an exact point-in-time graph without mutating the ledger. */\n  public snapshot(\n    options: {\n      atVersion?: number;\n      atTimestamp?: string;\n    } = {},\n  ): RelationshipSnapshot {\n    if (options.atVersion !== undefined && options.atTimestamp !== undefined)\n      throw new TypeError(\"Relationship snapshot accepts one target\");\n    let included: RelationshipEvent[];\n    if (options.atTimestamp !== undefined) {\n      const timestamp = Date.parse(options.atTimestamp);\n      if (!Number.isFinite(timestamp))\n        throw new TypeError(\"Relationship snapshot timestamp must be valid\");\n      let lastIndex = -1;\n      for (let index = this.#events.length - 1; index >= 0; index -= 1) {\n        if (Date.parse(this.#events[index]!.timestamp) > timestamp) continue;\n        lastIndex = index;\n        break;\n      }\n      included = lastIndex === -1 ? [] : this.#events.slice(0, lastIndex + 1);\n    } else {\n      const version = options.atVersion ?? this.version;\n      if (!Number.isInteger(version) || version < 0 || version > this.version)\n        throw new TypeError(\n          `Relationship snapshot version out of range: ${version}`,\n        );\n      included = this.#events.slice(0, version);\n    }\n    const active = replayEvents(included);\n    const graph = new RelationshipGraph(\n      this.#nodes,\n      active.values(),\n      this.#registry,\n    );\n    return Object.freeze({\n      version: included.length,\n      ...(included.at(-1) ? { asOf: included.at(-1)!.timestamp } : {}),\n      edges: graph.edges(),\n      graph,\n    });\n  }\n\n  /** Page the immutable event stream with a cursor bound to this log version. */\n  public page(options: {\n    limit: number;\n    cursor?: string;\n  }): RelationshipEventPage {\n    if (!Number.isInteger(options.limit) || options.limit < 1)\n      throw new TypeError(\"Relationship event page limit must be positive\");\n    const fingerprint = createQueryFingerprint(\"relationship-events\", {\n      order: \"append-sequence\",\n    });\n    const snapshot =\n      options.cursor === undefined\n        ? this.version\n        : Number(decodeQueryCursorState(options.cursor, fingerprint).snapshot);\n    if (\n      !Number.isSafeInteger(snapshot) ||\n      snapshot < 0 ||\n      snapshot > this.version\n    )\n      throw new TypeError(\n        \"Relationship event cursor snapshot version is invalid\",\n      );\n    const page = paginateQueryRows(this.#events.slice(0, snapshot), {\n      cursor: options.cursor,\n      fingerprint,\n      limit: options.limit,\n      readId: (event) => event.eventId,\n      snapshot: String(snapshot),\n    });\n    return {\n      version: snapshot,\n      events: page.rows,\n      hasMore: page.has_more,\n      ...(page.next_cursor ? { nextCursor: page.next_cursor } : {}),\n    };\n  }\n}\n\nconst RELATIONSHIP_STORE_LOCK_ID = \"relationship-event-store\";\nconst RELATIONSHIP_NOFOLLOW_FLAG = constants.O_NOFOLLOW;\n\nfunction acquireRelationshipStoreLock(\n  pmRoot: string,\n): Promise<() => Promise<void>> {\n  return acquireLock(\n    pmRoot,\n    RELATIONSHIP_STORE_LOCK_ID,\n    30,\n    `relationship-store:${process.pid}`,\n    false,\n    false,\n    3_000,\n  );\n}\n\nasync function resolveRelationshipEventStorePath(\n  pmRoot: string,\n  relativePath = \"relationships/events.jsonl\",\n): Promise<string> {\n  const root = path.resolve(pmRoot);\n  const target = path.resolve(root, relativePath);\n  const relative = path.relative(root, target);\n  if (relative.length === 0)\n    throw new TypeError(\n      \"Relationship event path must name a file within the tracker root\",\n    );\n  if (\n    relative === \"..\" ||\n    relative.startsWith(`..${path.sep}`) ||\n    path.isAbsolute(relative)\n  )\n    throw new TypeError(\n      \"Relationship event path must stay within the tracker root\",\n    );\n  await mkdir(root, { recursive: true });\n  const rootStats = await lstat(root);\n  if (rootStats.isSymbolicLink())\n    throw new TypeError(\n      \"Relationship event tracker root must not be a symbolic link\",\n    );\n  let current = root;\n  for (const segment of relative.split(path.sep)) {\n    current = path.join(current, segment);\n    try {\n      if ((await lstat(current)).isSymbolicLink())\n        throw new TypeError(\n          \"Relationship event path must not contain symbolic links\",\n        );\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"ENOENT\") break;\n      throw error;\n    }\n  }\n  return target;\n}\n\nasync function loadRelationshipEventLog(\n  target: string,\n  nodes: readonly string[],\n  registry: RelationshipKindRegistry | undefined,\n): Promise<RelationshipEventLog> {\n  const log = new RelationshipEventLog(nodes, { registry });\n  let raw: string;\n  let handle: FileHandle | undefined;\n  try {\n    handle = await open(\n      target,\n      constants.O_RDONLY | RELATIONSHIP_NOFOLLOW_FLAG,\n    );\n    raw = await handle.readFile(\"utf8\");\n  } catch (error) {\n    if ((error as NodeJS.ErrnoException).code === \"ENOENT\") return log;\n    throw error;\n  } finally {\n    await handle?.close();\n  }\n  const lines = raw.split(\"\\n\");\n  for (let index = 0; index < lines.length; index += 1) {\n    const line = lines[index]!.trim();\n    if (!line) continue;\n    let stored: RelationshipEvent;\n    try {\n      stored = JSON.parse(line) as RelationshipEvent;\n    } catch {\n      throw new TypeError(\n        `Invalid relationship event JSONL at line ${index + 1}`,\n      );\n    }\n    if (stored.sequence !== log.version + 1)\n      throw new TypeError(\n        `Invalid relationship event sequence at line ${index + 1}`,\n      );\n    log.append({\n      eventId: stored.eventId,\n      relationshipId: stored.relationshipId,\n      action: stored.action,\n      ...(stored.edge === undefined ? {} : { edge: stored.edge }),\n      author: stored.author,\n      timestamp: stored.timestamp,\n      ...(stored.reason === undefined ? {} : { reason: stored.reason }),\n      expectedVersion: log.version,\n    });\n  }\n  return log;\n}\n\n/**\n * Lock-serialized durable JSONL adapter for {@link RelationshipEventLog}.\n * Every append replays the current stream while holding the workspace lock, so\n * independent processes share optimistic versions without lost updates.\n */\nexport class RelationshipEventStore {\n  readonly #pmRoot: string;\n  readonly #nodes: readonly string[];\n  readonly #registry: RelationshipKindRegistry | undefined;\n  readonly #path: string;\n  #log: RelationshipEventLog;\n\n  private constructor(\n    options: RelationshipEventStoreOptions,\n    nodes: readonly string[],\n    target: string,\n    log: RelationshipEventLog,\n  ) {\n    this.#pmRoot = options.pmRoot;\n    this.#nodes = nodes;\n    this.#registry = options.registry;\n    this.#path = target;\n    this.#log = log;\n  }\n\n  /** Open and validate an existing stream or create an empty store view. */\n  public static async open(\n    options: RelationshipEventStoreOptions,\n  ): Promise<RelationshipEventStore> {\n    const nodes = Object.freeze([...options.nodes]);\n    const target = await resolveRelationshipEventStorePath(\n      options.pmRoot,\n      options.relativePath,\n    );\n    const release = await acquireRelationshipStoreLock(options.pmRoot);\n    try {\n      await resolveRelationshipEventStorePath(options.pmRoot, target);\n      const log = await loadRelationshipEventLog(\n        target,\n        nodes,\n        options.registry,\n      );\n      return new RelationshipEventStore(options, nodes, target, log);\n    } finally {\n      await release();\n    }\n  }\n\n  /** Absolute JSONL path, exposed for diagnostics and backup tooling. */\n  public get path(): string {\n    return this.#path;\n  }\n\n  /** Refresh from durable history and return the current validated append sequence. */\n  public async currentVersion(): Promise<number> {\n    this.#log = await this.#refreshFromDurableHistory();\n    return this.#log.version;\n  }\n\n  /** Append one event after refreshing under the shared workspace lock. */\n  public async append(\n    input: RelationshipEventInput,\n  ): Promise<RelationshipEvent> {\n    const release = await acquireRelationshipStoreLock(this.#pmRoot);\n    try {\n      const target = await resolveRelationshipEventStorePath(\n        this.#pmRoot,\n        this.#path,\n      );\n      const refreshed = await loadRelationshipEventLog(\n        target,\n        this.#nodes,\n        this.#registry,\n      );\n      const event = refreshed.append(input);\n      await mkdir(path.dirname(target), { recursive: true });\n      await resolveRelationshipEventStorePath(this.#pmRoot, target);\n      const handle = await open(\n        target,\n        constants.O_APPEND |\n          constants.O_CREAT |\n          constants.O_WRONLY |\n          RELATIONSHIP_NOFOLLOW_FLAG,\n      );\n      try {\n        await handle.appendFile(`${JSON.stringify(event)}\\n`, \"utf8\");\n      } finally {\n        await handle.close();\n      }\n      this.#log = refreshed;\n      return event;\n    } finally {\n      await release();\n    }\n  }\n\n  /** Refresh from durable history and materialize an exact validated snapshot. */\n  public async snapshot(\n    options: Parameters<RelationshipEventLog[\"snapshot\"]>[0] = {},\n  ): Promise<RelationshipSnapshot> {\n    this.#log = await this.#refreshFromDurableHistory();\n    return this.#log.snapshot(options);\n  }\n\n  /** Refresh from durable history and page immutable events. */\n  public async page(\n    options: Parameters<RelationshipEventLog[\"page\"]>[0],\n  ): Promise<RelationshipEventPage> {\n    this.#log = await this.#refreshFromDurableHistory();\n    return this.#log.page(options);\n  }\n\n  /** Serialize a durable refresh with writers so readers never observe a torn JSONL tail. */\n  async #refreshFromDurableHistory(): Promise<RelationshipEventLog> {\n    const release = await acquireRelationshipStoreLock(this.#pmRoot);\n    try {\n      const target = await resolveRelationshipEventStorePath(\n        this.#pmRoot,\n        this.#path,\n      );\n      return await loadRelationshipEventLog(\n        target,\n        this.#nodes,\n        this.#registry,\n      );\n    } finally {\n      await release();\n    }\n  }\n}\n"],"names":[],"mappings":"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","debugId":"787e8f44-80d5-554f-9232-9675cf6a8637"}

package/dist/sdk/relationships.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @module sdk/relationships
+ *
+ * Provides the dependency-free relationship ontology and bounded graph-query
+ * kernel shared by the SDK, CLI, MCP adapters, extensions, and non-PM apps.
+ */
+import type { Dependency, ItemMetadata } from "../types/index.js";
+/** Direction exposed by a relationship kind. */
+export type RelationshipDirection = "directed" | "undirected";
+/** Cardinality constraint applied independently to outgoing and incoming edges. */
+export type RelationshipCardinality = "one" | "many";
+/** Lifecycle policy for a relationship kind. */
+export type RelationshipLifecycle = "persistent" | "supersedable" | "ephemeral";
+/** Direction in which an ordering edge contributes to execution precedence. */
+export type RelationshipPrecedence = "source_before_target" | "target_before_source";
+/** Endpoint that represents the structural parent for hierarchy kinds. */
+export type RelationshipHierarchyDirection = "source_parent" | "target_parent";
+/** Versioned semantic definition for a built-in or application-defined edge kind. */
+export interface RelationshipKindDefinition {
+    /** Canonical, case-insensitive kind identifier. */
+    kind: string;
+    /** Whether traversing source to target has distinct meaning from the reverse. */
+    direction: RelationshipDirection;
+    /** Optional canonical kind used when traversing a directed edge in reverse. */
+    inverse?: string;
+    /** Whether the kind participates in execution-order cycle checks. */
+    ordering: boolean;
+    /** Execution direction for ordering kinds; defaults to source before target. */
+    precedence?: RelationshipPrecedence;
+    /** Whether the kind contributes to structural ancestry. */
+    hierarchy: boolean;
+    /** Endpoint that represents the parent; defaults to source for custom kinds. */
+    hierarchyDirection?: RelationshipHierarchyDirection;
+    /** Maximum logical outgoing edges of this kind from one node. */
+    outgoing: RelationshipCardinality;
+    /** Maximum logical incoming edges of this kind to one node. */
+    incoming: RelationshipCardinality;
+    /** Edge replacement and retention behavior. */
+    lifecycle: RelationshipLifecycle;
+    /** JSON Schema for optional application-owned payloads. */
+    payloadSchema?: Readonly<Record<string, unknown>>;
+    /** Legacy spellings normalized to this definition. */
+    aliases?: readonly string[];
+    /** Compatibility version of this semantic contract. */
+    compatibilityVersion: number;
+    /** Whether source and target may be the same node. */
+    allowSelf: boolean;
+}
+/** One normalized relationship edge indexed by the graph kernel. */
+export interface RelationshipEdge {
+    /** Source node identifier. */
+    source: string;
+    /** Target node identifier. */
+    target: string;
+    /** Canonical relationship kind. */
+    kind: string;
+    /** Optional creation timestamp retained from storage. */
+    createdAt?: string;
+    /** Optional author retained from storage. */
+    author?: string;
+    /** Optional application-owned edge payload. */
+    payload?: Readonly<Record<string, unknown>>;
+}
+/** Direction used by adjacency, closure, and path traversal. */
+export type RelationshipTraversalDirection = "outgoing" | "incoming" | "both";
+/** Shared bounded-query controls. */
+export interface RelationshipQueryOptions {
+    /** Edge kinds to traverse after alias normalization. */
+    kinds?: readonly string[];
+    /** Traversal direction relative to each visited node. */
+    direction?: RelationshipTraversalDirection;
+    /** Maximum number of returned nodes, excluding the starting node. */
+    limit?: number;
+    /** Maximum traversal depth. */
+    maxDepth?: number;
+    /** Abort signal checked throughout traversal. */
+    signal?: AbortSignal;
+}
+/** Cost and truncation metadata returned by every graph query. */
+export interface RelationshipQueryMeta {
+    /** Number of nodes removed from the traversal frontier. */
+    visitedNodes: number;
+    /** Number of candidate edges inspected. */
+    inspectedEdges: number;
+    /** Whether a configured bound stopped traversal. */
+    truncated: boolean;
+    /** Deterministic continuation cursor for the final returned node. */
+    nextCursor?: string;
+}
+/** Generic bounded graph query result. */
+export interface RelationshipQueryResult<T> {
+    /** Deterministically ordered query value. */
+    value: T;
+    /** Explicit query work and truncation metadata. */
+    meta: RelationshipQueryMeta;
+}
+/** Induced subgraph returned by bounded traversal. */
+export interface RelationshipSubgraph {
+    /** Deterministically ordered node identifiers. */
+    nodes: string[];
+    /** Deterministically ordered edges whose endpoints are both present. */
+    edges: RelationshipEdge[];
+}
+/** Mutable registry with immutable snapshots and collision-safe extension registration. */
+export declare class RelationshipKindRegistry {
+    #private;
+    /** Create a registry initialized with the stable built-in ontology by default. */
+    constructor(definitions?: readonly RelationshipKindDefinition[]);
+    /** Register one definition after validating its identifier, version, and aliases. */
+    register(definition: RelationshipKindDefinition): this;
+    /** Resolve a canonical kind or compatibility alias. */
+    resolve(kind: unknown): RelationshipKindDefinition | undefined;
+    /** Resolve a kind or throw a precise error suitable for command adapters. */
+    require(kind: string): RelationshipKindDefinition;
+    /** Return a deterministic immutable registry snapshot. */
+    list(): readonly RelationshipKindDefinition[];
+}
+/** Create a registry containing the built-in relationship ontology. */
+export declare function createRelationshipKindRegistry(): RelationshipKindRegistry;
+/** Report whether a kind participates in execution-order cycle detection. */
+export declare function isOrderingRelationshipKind(kind: string, registry?: RelationshipKindRegistry): boolean;
+/** Build an immutable, deterministic in-memory relationship index. */
+export declare class RelationshipGraph {
+    #private;
+    /** Validate and index nodes and edges without reading tracker storage. */
+    constructor(nodes: Iterable<string>, edges: Iterable<RelationshipEdge>, registry?: RelationshipKindRegistry);
+    /** Build the graph directly from item metadata, including hierarchy and legacy blocker fields. */
+    static fromItems(items: readonly Pick<ItemMetadata, "id" | "parent" | "blocked_by" | "dependencies">[], registry?: RelationshipKindRegistry): RelationshipGraph;
+    /** Return the deterministic immutable edge snapshot. */
+    edges(): readonly RelationshipEdge[];
+    /** Return the deterministic immutable edges incident to one node. */
+    incidentEdges(id: string): readonly RelationshipEdge[];
+    /** Return the deterministic immutable node snapshot. */
+    nodes(): readonly string[];
+    /** Return one-hop adjacent node identifiers. */
+    adjacency(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<string[]>;
+    /** Return bounded transitive closure in breadth-first discovery order. */
+    closure(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<string[]>;
+    /** Return a deterministic shortest path, or an empty array when disconnected. */
+    shortestPath(source: string, target: string, options?: RelationshipQueryOptions): RelationshipQueryResult<string[]>;
+    /** Return the induced subgraph over a bounded closure including the root. */
+    subgraph(id: string, options?: RelationshipQueryOptions): RelationshipQueryResult<RelationshipSubgraph>;
+}
+/** Convert one stored dependency into the public relationship edge contract. */
+export declare function dependencyToRelationship(source: string, dependency: Dependency, registry?: RelationshipKindRegistry): RelationshipEdge;