kibi-cli 0.19.0 → 2.0.0

package/dist/operations/mutation/source-authoring.js

@@ -0,0 +1,576 @@
+import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { dump as dumpYaml, load as loadYaml } from "js-yaml";
+import { parseDocument, stringify } from "yaml";
+import { OperationError } from "../../cli-errors.js";
+import { CANONICAL_ENTITY_PATHS, isDerivedKbPath, } from "../../utils/kb-paths.js";
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function pendingReceiptPath(workspaceRoot, relativePath) {
+    return path.join(workspaceRoot, ".kb", "recovery", "pending-sources", `${digest(relativePath)}.json`);
+}
+export function writePendingSourceReceipt(workspaceRoot, relativePath, afterHash) {
+    const receiptPath = pendingReceiptPath(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(receiptPath), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(receiptPath, `${JSON.stringify({
+        version: 1,
+        path: relativePath,
+        afterHash,
+        createdAt: new Date().toISOString(),
+    }, null, 2)}\n`, { mode: 0o600 });
+}
+function authoredPath(value) {
+    if (typeof value !== "string" || !value.trim())
+        return undefined;
+    const normalized = value.replaceAll("\\", "/");
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(normalized))
+        return undefined;
+    if (!/\.(?:md|mdx|ya?ml)$/i.test(normalized))
+        return undefined;
+    return normalized;
+}
+export function resolveContainedSourcePath(workspaceRoot, relative) {
+    if (path.isAbsolute(relative) ||
+        relative.split(/[\\/]/).some((part) => part === ".." || part === "")) {
+        throw new OperationError("SOURCE_PATH_INVALID", `document.path must be a workspace-relative path without traversal: ${relative}`);
+    }
+    const absolute = path.resolve(workspaceRoot, relative);
+    const root = path.resolve(workspaceRoot);
+    if (absolute !== root && !absolute.startsWith(`${root}${path.sep}`)) {
+        throw new OperationError("SOURCE_PATH_INVALID", `document.path escapes the workspace: ${relative}`);
+    }
+    const workspaceRelative = path
+        .relative(root, absolute)
+        .replaceAll(path.sep, "/");
+    if (isDerivedKbPath(workspaceRelative)) {
+        throw new OperationError("SOURCE_PATH_INVALID", `document.path cannot target Kibi's derived state under ${workspaceRelative}: ${relative}`);
+    }
+    // A symlinked existing file or parent could otherwise escape the workspace.
+    let existing = fs.existsSync(absolute) ? absolute : path.dirname(absolute);
+    while (!fs.existsSync(existing) && path.dirname(existing) !== existing) {
+        existing = path.dirname(existing);
+    }
+    const real = fs.realpathSync.native(existing);
+    if (real !== root && !real.startsWith(`${root}${path.sep}`)) {
+        throw new OperationError("SOURCE_PATH_INVALID", `document.path resolves outside the workspace: ${relative}`);
+    }
+    return absolute;
+}
+export function normalizeAuthoredSourcePath(workspaceRoot, source) {
+    const normalized = source.replaceAll("\\", "/");
+    const relative = path.isAbsolute(normalized)
+        ? path.relative(path.resolve(workspaceRoot), path.resolve(normalized))
+        : normalized;
+    return path
+        .relative(path.resolve(workspaceRoot), resolveContainedSourcePath(workspaceRoot, relative))
+        .replaceAll(path.sep, "/");
+}
+function bodyAndFrontmatter(content) {
+    if (!content.startsWith("---"))
+        return { frontmatter: {}, body: content };
+    const firstEnd = content.indexOf("\n", 3);
+    if (firstEnd < 0)
+        return { frontmatter: {}, body: content };
+    const marker = content.indexOf("\n---", firstEnd);
+    if (marker < 0)
+        return { frontmatter: {}, body: content };
+    const raw = content.slice(firstEnd + 1, marker);
+    const parsed = loadYaml(raw);
+    return {
+        frontmatter: parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {},
+        body: content.slice(marker + "\n---".length),
+    };
+}
+/**
+ * Canonical authored target for an entity type: `.kb/<lane>/<ID>.md` for
+ * markdown entities and `.kb/symbols.yaml` for symbols. Kibi owns these
+ * locations; repositories cannot relocate them.
+ */
+export function configuredSourceTarget(workspaceRoot, type) {
+    const laneByType = {
+        req: CANONICAL_ENTITY_PATHS.requirements,
+        scenario: CANONICAL_ENTITY_PATHS.scenarios,
+        test: CANONICAL_ENTITY_PATHS.tests,
+        adr: CANONICAL_ENTITY_PATHS.adr,
+        flag: CANONICAL_ENTITY_PATHS.flags,
+        event: CANONICAL_ENTITY_PATHS.events,
+        fact: CANONICAL_ENTITY_PATHS.facts,
+        symbol: CANONICAL_ENTITY_PATHS.symbols,
+    };
+    return laneByType[type];
+}
+export function hasConfiguredSourceTarget(workspaceRoot, type) {
+    return configuredSourceTarget(workspaceRoot, type) !== undefined;
+}
+function sourcePath(context, input, entity, existing) {
+    const requested = input.document?.path;
+    const canonical = configuredSourceTarget(context.workspaceRoot, input.type);
+    let relative = requested ?? authoredPath(existing?.source);
+    // Canonical markdown lanes name a directory; append the entity's file so
+    // upserts without document.path land in the canonical location.
+    if (relative === undefined &&
+        canonical !== undefined &&
+        !/\.(?:md|mdx|ya?ml)$/i.test(canonical)) {
+        relative = `${canonical}/${String(entity.id)}.md`;
+    }
+    else if (relative === undefined && canonical !== undefined) {
+        relative = canonical;
+    }
+    if (!relative) {
+        throw new OperationError("DOCUMENT_PATH_REQUIRED", `No writable source target is available for ${input.type}; provide document.path explicitly`);
+    }
+    // Extracted entities may carry an absolute source path even though the
+    // authored document contract is workspace-relative. Rebase paths that are
+    // inside the workspace before applying containment and symlink checks.
+    if (path.isAbsolute(relative)) {
+        const root = path.resolve(context.workspaceRoot);
+        const absolute = path.resolve(relative);
+        if (absolute !== root && !absolute.startsWith(`${root}${path.sep}`)) {
+            throw new OperationError("SOURCE_PATH_INVALID", `document.path resolves outside the workspace: ${relative}`);
+        }
+        relative = path.relative(root, absolute).replaceAll(path.sep, "/");
+    }
+    return resolveContainedSourcePath(context.workspaceRoot, relative);
+}
+function renderEntityDocument(input, entity, existingContent) {
+    const existing = existingContent
+        ? bodyAndFrontmatter(existingContent)
+        : { frontmatter: {}, body: "" };
+    const body = input.document?.body !== undefined
+        ? input.document.body
+        : existingContent !== undefined
+            ? existing.body
+            : input.type === "req"
+                ? `${String(entity.semantic_text ?? "").trim()}\n`
+                : "\n";
+    const frontmatter = {
+        ...existing.frontmatter,
+        ...Object.fromEntries(Object.entries(entity).filter(([key]) => 
+        // Runtime provenance/timestamps belong to the compiled entity, not to
+        // the authored source artifact. Keeping them out also makes the source
+        // diff deterministic across CLI and MCP transports.
+        ![
+            "id",
+            "type",
+            "source",
+            "links",
+            "relationships",
+            "created_at",
+            "updated_at",
+        ].includes(key))),
+    };
+    frontmatter.id = entity.id;
+    frontmatter.title ??= entity.id;
+    frontmatter.type = entity.type;
+    return `---\n${dumpYaml(frontmatter, { noRefs: true, lineWidth: -1, sortKeys: false })}---${body.startsWith("\n") ? "" : "\n"}${body}`;
+}
+/** Generated coordinate fields belong exclusively to `.kb/symbol-coordinates.yaml`. */
+// implements REQ-generated-coordinate-persistence
+export const GENERATED_SYMBOL_FIELDS = [
+    "sourceLine",
+    "sourceColumn",
+    "sourceEndLine",
+    "sourceEndColumn",
+    "coordinatesGeneratedAt",
+];
+function symbolManifestRecord(entity, relationships = []) {
+    const record = Object.fromEntries(Object.entries(entity).filter(([key]) => ![
+        "type",
+        "source",
+        "relationships",
+        "created_at",
+        "updated_at",
+        // Generated coordinates are compiler output. They must never enter
+        // the authored manifest, including legacy inline occurrences.
+        ...GENERATED_SYMBOL_FIELDS,
+    ].includes(key)));
+    if (relationships.length > 0) {
+        record.relationships = relationships.map(({ type, target }) => ({
+            type,
+            target,
+        }));
+    }
+    return record;
+}
+export function manifestRelationships(item) {
+    if (item === null ||
+        typeof item !== "object" ||
+        !("get" in item) ||
+        typeof item.get !== "function") {
+        return [];
+    }
+    const sequence = item.get("relationships", true);
+    if (sequence === null ||
+        typeof sequence !== "object" ||
+        !("toJSON" in sequence) ||
+        typeof sequence.toJSON !== "function") {
+        return [];
+    }
+    const value = sequence.toJSON();
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((relationship) => {
+        if (relationship === null || typeof relationship !== "object") {
+            return [];
+        }
+        const candidate = relationship;
+        const type = candidate.type;
+        const target = candidate.target ?? candidate.to;
+        return typeof type === "string" && typeof target === "string"
+            ? [{ type, target }]
+            : [];
+    });
+}
+function mergeManifestRelationships(existing, incoming, entityId) {
+    const merged = new Map();
+    for (const relationship of existing) {
+        merged.set(`${relationship.type}\u0000${relationship.target}`, {
+            type: relationship.type,
+            target: relationship.target,
+        });
+    }
+    for (const relationship of incoming) {
+        if (relationship.from !== entityId ||
+            typeof relationship.type !== "string" ||
+            typeof relationship.to !== "string") {
+            continue;
+        }
+        const normalized = { type: relationship.type, target: relationship.to };
+        merged.set(`${normalized.type}\u0000${normalized.target}`, normalized);
+    }
+    return [...merged.values()].sort((left, right) => `${left.type}\u0000${left.target}`.localeCompare(`${right.type}\u0000${right.target}`));
+}
+function renderSymbolManifest(entity, relationships, existingContent) {
+    if (existingContent === undefined) {
+        const doc = parseDocument(stringify({
+            symbols: [
+                symbolManifestRecord(entity, mergeManifestRelationships([], relationships, String(entity.id))),
+            ],
+        }));
+        return doc.toString();
+    }
+    const doc = parseDocument(existingContent);
+    const symbols = doc.get("symbols", true);
+    if (!symbols || typeof symbols !== "object" || !("items" in symbols)) {
+        throw new OperationError("SOURCE_FORMAT_INVALID", "Symbol manifest must contain a symbols array");
+    }
+    const items = symbols.items;
+    const id = String(entity.id);
+    const index = items.findIndex((item) => {
+        if (!item || typeof item !== "object" || !("get" in item))
+            return false;
+        return String(item.get("id")) === id;
+    });
+    const existingRelationships = index >= 0 ? manifestRelationships(items[index]) : [];
+    let next = symbolManifestRecord(entity, mergeManifestRelationships(existingRelationships, relationships, id));
+    if (index >= 0) {
+        // Partial symbol payloads (for example a relationship-only upsert) must
+        // never erase authored provenance from the manifest. Preserve fields the
+        // payload omits, with incoming values winning on explicit conflicts.
+        const item = items[index];
+        const previous = typeof item?.toJSON === "function" ? item.toJSON() : null;
+        if (typeof previous === "object" &&
+            previous !== null &&
+            !Array.isArray(previous)) {
+            const preserved = symbolManifestRecord(previous, []);
+            next = { ...preserved, ...next };
+        }
+        doc.setIn(["symbols", index], next);
+    }
+    else {
+        doc.addIn(["symbols"], next);
+    }
+    return doc.toString();
+}
+export function renderSourceDeletion(sourcePathValue, entityId, entityType, existingContent) {
+    const extension = path.extname(sourcePathValue).toLowerCase();
+    if (extension === ".md" || extension === ".mdx") {
+        const parsed = bodyAndFrontmatter(existingContent);
+        if (String(parsed.frontmatter.id ?? "") !== entityId) {
+            throw new OperationError("SOURCE_ENTITY_MISMATCH", `Authored document ${sourcePathValue} does not contain ${entityId}`);
+        }
+        return { mode: "delete" };
+    }
+    if (extension === ".yaml" || extension === ".yml") {
+        if (entityType !== "symbol") {
+            throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `YAML deletion is supported only for symbol manifests, not ${entityType}`);
+        }
+        const doc = parseDocument(existingContent);
+        const symbols = doc.get("symbols", true);
+        if (!symbols || typeof symbols !== "object" || !("items" in symbols)) {
+            throw new OperationError("SOURCE_FORMAT_INVALID", "Symbol manifest must contain a symbols array");
+        }
+        const items = symbols.items;
+        const index = items.findIndex((item) => {
+            if (!item || typeof item !== "object" || !("get" in item))
+                return false;
+            return (String(item.get("id")) === entityId);
+        });
+        if (index < 0) {
+            throw new OperationError("SOURCE_ENTITY_MISMATCH", `Symbol manifest ${sourcePathValue} does not contain ${entityId}`);
+        }
+        doc.deleteIn(["symbols", index]);
+        return { mode: "write", body: doc.toString() };
+    }
+    throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `Unsupported authored source format: ${extension || "unknown"}`);
+}
+/**
+ * Remove one legacy relationship declaration from an authored Markdown
+ * document.  Relationship shards are the canonical relationship lane, but
+ * older entity documents may still carry `links` or typed `relationships`
+ * frontmatter.  When such a declaration is explicitly deleted, patch only
+ * that record through the YAML CST so comments, ordering, and the Markdown
+ * body remain byte-stable.
+ */
+export function renderMarkdownRelationshipDeletion(sourcePathValue, existingContent, selector) {
+    const extension = path.extname(sourcePathValue).toLowerCase();
+    if (extension !== ".md" && extension !== ".mdx") {
+        throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `Relationship declarations can only be patched in Markdown documents: ${sourcePathValue}`);
+    }
+    if (!existingContent.startsWith("---"))
+        return { body: existingContent, removed: false };
+    const firstEnd = existingContent.indexOf("\n", 3);
+    if (firstEnd < 0)
+        return { body: existingContent, removed: false };
+    const marker = existingContent.indexOf("\n---", firstEnd);
+    if (marker < 0)
+        return { body: existingContent, removed: false };
+    const frontmatter = parseDocument(existingContent.slice(firstEnd + 1, marker));
+    let removed = false;
+    for (const key of ["links", "relationships"]) {
+        const sequence = frontmatter.get(key, true);
+        if (!sequence || typeof sequence !== "object" || !("items" in sequence))
+            continue;
+        const items = sequence.items;
+        for (let index = items.length - 1; index >= 0; index -= 1) {
+            const item = items[index];
+            if (!item || typeof item !== "object")
+                continue;
+            if (key === "links" && !("get" in item)) {
+                const scalar = item;
+                const value = scalar.toJSON?.() ?? scalar.value;
+                if (typeof value === "string" &&
+                    value.replace(/^kb:entity\//, "") === selector.to) {
+                    frontmatter.deleteIn([key, index]);
+                    removed = true;
+                }
+                continue;
+            }
+            if (!("get" in item))
+                continue;
+            const node = item;
+            const target = node.get("target") ?? node.get("to");
+            const relationType = node.get("type");
+            const matches = typeof target === "string" &&
+                target.replace(/^kb:entity\//, "") === selector.to &&
+                (key === "links" ||
+                    relationType === selector.type ||
+                    relationType === undefined);
+            if (matches) {
+                frontmatter.deleteIn([key, index]);
+                removed = true;
+            }
+        }
+    }
+    if (!removed)
+        return { body: existingContent, removed: false };
+    const body = existingContent.slice(marker + "\n---".length);
+    return {
+        body: `---\n${frontmatter.toString()}---${body.startsWith("\n") ? "" : "\n"}${body}`,
+        removed: true,
+    };
+}
+/**
+ * Remove one exact typed relationship from an authored symbol manifest. The
+ * YAML CST is edited in place so comments, ordering, and unrelated symbols or
+ * relationships remain authored content rather than being re-serialized.
+ */
+export function renderYamlRelationshipDeletion(sourcePathValue, existingContent, selector) {
+    const extension = path.extname(sourcePathValue).toLowerCase();
+    if (extension !== ".yaml" && extension !== ".yml") {
+        throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `Relationship declarations can only be patched in YAML symbol manifests: ${sourcePathValue}`);
+    }
+    const doc = parseDocument(existingContent);
+    if (doc.errors.length > 0) {
+        throw new OperationError("SOURCE_FORMAT_INVALID", `Symbol manifest contains invalid YAML: ${doc.errors[0]?.message ?? "parse failed"}`);
+    }
+    const symbols = doc.get("symbols", true);
+    if (!symbols || typeof symbols !== "object" || !("items" in symbols)) {
+        throw new OperationError("SOURCE_FORMAT_INVALID", "Symbol manifest must contain a symbols array");
+    }
+    const items = symbols.items;
+    const symbol = items.find((item) => {
+        if (!item || typeof item !== "object" || !("get" in item))
+            return false;
+        return (String(item.get("id")) ===
+            selector.from);
+    });
+    if (!symbol || typeof symbol !== "object" || !("get" in symbol)) {
+        return { body: existingContent, removed: false };
+    }
+    const relationships = symbol.get("relationships", true);
+    if (!relationships ||
+        typeof relationships !== "object" ||
+        !("items" in relationships)) {
+        return { body: existingContent, removed: false };
+    }
+    const relationshipItems = relationships.items;
+    let removed = false;
+    for (let index = relationshipItems.length - 1; index >= 0; index -= 1) {
+        const item = relationshipItems[index];
+        if (!item || typeof item !== "object" || !("get" in item))
+            continue;
+        const node = item;
+        const type = node.get("type");
+        const target = node.get("target") ?? node.get("to");
+        const normalizedTarget = typeof target === "string"
+            ? target.replace(/^kb:entity\//, "")
+            : undefined;
+        if (type === selector.type && normalizedTarget === selector.to) {
+            relationships.delete(index);
+            removed = true;
+        }
+    }
+    return removed
+        ? { body: doc.toString(), removed: true }
+        : { body: existingContent, removed: false };
+}
+function renderSourceDocument(input, entity, existingContent, relativePath) {
+    const extension = path.extname(relativePath).toLowerCase();
+    if (extension === ".yaml" || extension === ".yml") {
+        if (input.type !== "symbol") {
+            throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `YAML source authoring is supported only for symbol manifests, not ${input.type}`);
+        }
+        return renderSymbolManifest(entity, input.relationships ?? [], existingContent);
+    }
+    if (extension !== ".md" && extension !== ".mdx") {
+        throw new OperationError("SOURCE_FORMAT_UNSUPPORTED", `Unsupported authored source format: ${extension || "unknown"}`);
+    }
+    return renderEntityDocument(input, entity, existingContent);
+}
+export async function writeSourceForUpsert(input, entity, existing, context, sourceDocumentOverride) {
+    if (!context?.fs)
+        return null;
+    const absolute = sourcePath(context, input, entity, existing);
+    const relative = path
+        .relative(context.workspaceRoot, absolute)
+        .replaceAll("\\", "/");
+    let before;
+    try {
+        before = await context.fs.readFile(absolute);
+    }
+    catch {
+        before = undefined;
+    }
+    // Proof-receipt ingest supplies pre-patched bytes so unrelated frontmatter
+    // keeps its authored formatting (and the workspace snapshot stays stable).
+    // Only valid when the document already exists; a new document still needs
+    // the canonical render.
+    const after = before !== undefined && sourceDocumentOverride !== undefined
+        ? sourceDocumentOverride
+        : renderSourceDocument(input, entity, before, relative);
+    await context.fs.mkdir(path.dirname(absolute));
+    const temporary = `${absolute}.kibi-source-${process.pid}-${randomUUID()}`;
+    try {
+        await context.fs.writeFile(temporary, after);
+        if (context.fs.rename) {
+            await context.fs.rename(temporary, absolute);
+        }
+        else {
+            await context.fs.writeFile(absolute, after);
+            await context.fs.unlink?.(temporary).catch(() => undefined);
+        }
+    }
+    catch (error) {
+        // A failed rename must not leak the unique temp file into the authored
+        // tree; the published target (if any) is untouched at this point.
+        await context.fs.unlink?.(temporary).catch(() => undefined);
+        throw error;
+    }
+    const receipt = {
+        path: relative,
+        mode: "write",
+        beforeHash: before === undefined ? null : digest(before),
+        afterHash: digest(after),
+        created: before === undefined,
+    };
+    const rollback = async () => {
+        const fsPort = context.fs;
+        if (fsPort === undefined)
+            return;
+        // Compare before restore: a concurrent writer may have replaced the file
+        // after our publication. Never clobber newer bytes; keep the recovery
+        // receipt so the next sync reconciles deterministically instead.
+        let current;
+        try {
+            current = await fsPort.readFile(absolute);
+        }
+        catch {
+            current = undefined;
+        }
+        if (current !== undefined && digest(current) !== digest(after)) {
+            writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
+            console.warn(`Skipped source rollback for ${relative}: file changed after the Kibi write; kept concurrent content and recorded recovery metadata.`);
+            return;
+        }
+        if (before === undefined) {
+            if (fsPort.unlink)
+                await fsPort.unlink(absolute);
+            else
+                await fsPort.writeFile(absolute, "");
+            try {
+                fs.unlinkSync(pendingReceiptPath(context.workspaceRoot, relative));
+            }
+            catch {
+                // The pending receipt is advisory recovery metadata.
+            }
+        }
+        else {
+            const rollbackTemp = `${absolute}.kibi-rollback-${process.pid}-${randomUUID()}`;
+            try {
+                await fsPort.writeFile(rollbackTemp, before);
+                if (fsPort.rename)
+                    await fsPort.rename(rollbackTemp, absolute);
+                else {
+                    await fsPort.writeFile(absolute, before);
+                    await fsPort.unlink?.(rollbackTemp).catch(() => undefined);
+                }
+            }
+            catch (error) {
+                await fsPort.unlink?.(rollbackTemp).catch(() => undefined);
+                throw error;
+            }
+        }
+    };
+    const pendingReceipt = pendingReceiptPath(context.workspaceRoot, relative);
+    try {
+        if (receipt.afterHash !== null &&
+            (before === undefined || fs.existsSync(pendingReceipt))) {
+            writePendingSourceReceipt(context.workspaceRoot, relative, receipt.afterHash);
+        }
+    }
+    catch (receiptError) {
+        // The source bytes are already published but the caller has not received
+        // the rollback handle yet. Unwind the publication here so no failed call
+        // ever leaves a half-registered source write behind.
+        try {
+            await rollback();
+        }
+        catch (rollbackError) {
+            throw new AggregateError([receiptError, rollbackError], `Source published for ${relative}, but pending receipt publication and rollback both failed; recover from the pending-source receipt or restore the authored file manually`);
+        }
+        throw receiptError;
+    }
+    return { receipt, rollback };
+}
+/** Resolve and normalize the canonical authored path for an entity. */
+export function canonicalSourcePath(context, input, entity, existing) {
+    return path
+        .relative(context.workspaceRoot, sourcePath(context, input, entity, existing))
+        .replaceAll(path.sep, "/");
+}

package/dist/operations/mutation/strict-fact.d.ts

@@ -1,4 +1,5 @@
 export declare function valueFieldHint(value: unknown): string;
 export declare function factKindShapeHints(entity: Readonly<Record<string, unknown>>): string[];
+export declare function assertRuleSchemaArity(argumentNames: unknown, argumentTypes: unknown): void;
 export declare function validateFactModelingShape(entity: Readonly<Record<string, unknown>>): void;
 //# sourceMappingURL=strict-fact.d.ts.map

package/dist/operations/mutation/strict-fact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-fact.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/strict-fact.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAarD;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CA+EV;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,IAAI,CAuDN"}
+{"version":3,"file":"strict-fact.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/strict-fact.ts"],"names":[],"mappings":"AAUA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAarD;AAGD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,MAAM,EAAE,CA+EV;AAED,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,OAAO,EACtB,aAAa,EAAE,OAAO,GACrB,IAAI,CAUN;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACxC,IAAI,CA+CN"}

package/dist/operations/mutation/strict-fact.js

@@ -93,6 +93,13 @@ export function factKindShapeHints(entity) {
         ];
     return [];
 }
+export function assertRuleSchemaArity(argumentNames, argumentTypes) {
+    if (!Array.isArray(argumentNames) ||
+        !Array.isArray(argumentTypes) ||
+        argumentNames.length !== argumentTypes.length) {
+        throw new Error("Entity validation failed: rule_schema argument_names and argument_types must have equal lengths");
+    }
+}
 // implements REQ-kibi-operation-interface-parity
 export function validateFactModelingShape(entity) {
     const hints = factKindShapeHints(entity);
@@ -123,10 +130,6 @@ export function validateFactModelingShape(entity) {
             entity.rule_name.trim() === "") {
             throw new Error("Entity validation failed: fact_kind 'rule_schema' requires rule_name");
         }
-        if (!Array.isArray(entity.argument_names) ||
-            !Array.isArray(entity.argument_types) ||
-            entity.argument_names.length !== entity.argument_types.length) {
-            throw new Error("Entity validation failed: rule_schema argument_names and argument_types must have equal lengths");
-        }
+        assertRuleSchemaArity(entity.argument_names, entity.argument_types);
     }
 }

package/dist/operations/mutation/symbol-compiler-lock.d.ts

@@ -0,0 +1,54 @@
+export interface SymbolCompilerLockFileSystem {
+    readonly mkdirSync: (target: string, options?: {
+        readonly recursive?: boolean;
+    }) => void;
+    readonly readFileSync: (target: string) => string;
+    readonly writeFileSync: (target: string, data: string, options: {
+        readonly encoding: "utf8";
+        readonly flag: "wx";
+    }) => void;
+    readonly unlinkSync: (target: string) => void;
+    readonly rmdirSync: (target: string) => void;
+}
+export interface SymbolCompilerLockOptions {
+    readonly timeoutMs?: number;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly fileSystem?: SymbolCompilerLockFileSystem;
+    readonly isProcessAlive?: (pid: number) => boolean;
+}
+export declare class SymbolCompilerLockError extends Error {
+    readonly name = "SymbolCompilerLockError";
+}
+export interface SymbolCompilerLockHandle {
+    /**
+     * Remove this handle's validated owner metadata and then its empty lock
+     * directory. Transient cleanup errors are retried; exhausted or permanent
+     * failures leave the lock fail-closed and may require verified manual
+     * cleanup. Successful release is idempotent, and a stale handle never
+     * removes a different owner token.
+     */
+    readonly release: () => void;
+}
+export declare function releaseSymbolCompilerLock(handle: SymbolCompilerLockHandle | undefined, operationFailure?: {
+    readonly error: unknown;
+}, committed?: boolean): void;
+/**
+ * Acquire the workspace symbol compiler lock without a callback shape, for
+ * operations whose lock must span several awaits (source publication,
+ * coordinate refresh, canonical re-extraction, and the RDF commit).
+ */
+export declare function acquireSymbolCompilerLock(workspaceRoot: string, options?: SymbolCompilerLockOptions): Promise<SymbolCompilerLockHandle>;
+/**
+ * Run `operation` while holding the workspace symbol compiler lock.
+ *
+ * Atomic directory creation is the lock authority. Owner metadata is
+ * release authorization and diagnostics: every existing target, including a
+ * legacy file or a directory with missing/corrupt metadata, blocks contenders
+ * until timeout. A well-formed owner record whose holder pid is provably
+ * dead is stolen immediately instead of blocking for the full timeout;
+ * corrupt metadata and live holders stay fail-closed.
+ * Release failures propagate so successful work is never reported unlocked.
+ */
+export declare function withSymbolCompilerLock<T>(workspaceRoot: string, operation: () => Promise<T>, options?: SymbolCompilerLockOptions): Promise<T>;
+//# sourceMappingURL=symbol-compiler-lock.d.ts.map

package/dist/operations/mutation/symbol-compiler-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-compiler-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/symbol-compiler-lock.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KACvC,IAAI,CAAC;IACV,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KACxD,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAeD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC;IACnD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACpD;AAGD,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,SAAkB,IAAI,6BAA6B;CACpD;AA8MD,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,wBAAwB,GAAG,SAAS,EAC5C,gBAAgB,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC9C,SAAS,UAAQ,GAChB,IAAI,CAoBN;AAED;;;;GAIG;AAEH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,wBAAwB,CAAC,CA2InC;AAED;;;;;;;;;;GAUG;AAEH,wBAAsB,sBAAsB,CAAC,CAAC,EAC5C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,CAAC,CAAC,CAWZ"}