@software-dlc/cli 0.157.2

package/dist/local/projection.js

@@ -0,0 +1,709 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { encodeEvidenceMeta, isEvidenceBoundaryEnabled, markEvidenceFormatUpgrade, upgradeGraphEvidenceFormat, portable_graph_edge_schema, portable_graph_node_schema, portable_graph_path_relation_schema, portable_graph_path_schema, portable_graph_schema, withoutEvidenceTransientState } from '@software-dlc/graph/schema';
+import { validateBuiltGraph } from '@software-dlc/graph/validator';
+import { diffPortableGraphs } from '@software-dlc/graph/computation';
+import { canonicalizePortableGraph, stringifyCanonicalGraph, stringifyCanonicalJson } from './canonical.js';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export const DEFAULT_PROJECTION_DIRECTORY_NAME = 'sdlc';
+/** The graph's package uses (graph-packages.md, Use), only while it has some. */
+export const PACKAGE_USES_FILE = 'package-uses.json';
+const ENTITY_CONFIG = {
+    node: {
+        directory: 'nodes',
+        graph_key: 'nodes',
+        safe_parse: (value) => portable_graph_node_schema.safeParse(value)
+    },
+    edge: {
+        directory: 'edges',
+        graph_key: 'edges',
+        safe_parse: (value) => portable_graph_edge_schema.safeParse(value)
+    },
+    path: {
+        directory: 'paths',
+        graph_key: 'paths',
+        safe_parse: (value) => portable_graph_path_schema.safeParse(value)
+    },
+    path_relation: {
+        directory: 'path-relations',
+        graph_key: 'path_relations',
+        safe_parse: (value) => portable_graph_path_relation_schema.safeParse(value)
+    }
+};
+/** Every invalid entity file of a projection, reported together instead of the first one found. */
+export class ProjectionEntityErrors extends Error {
+    errors;
+    constructor(errors) {
+        super([
+            `The projection has ${errors.length} invalid entity ${errors.length === 1 ? 'field' : 'fields'}:`,
+            ...errors.map((error) => `  ${error.relative_path} (${error.entity_kind} ${error.entity_id})${error.field_path ? ` ${error.field_path}` : ''}: ${error.message}`)
+        ].join('\n'));
+        this.name = 'ProjectionEntityErrors';
+        this.errors = errors;
+    }
+}
+const ENTITY_KINDS = Object.keys(ENTITY_CONFIG);
+function entityRelativePath(kind, id) {
+    return `${ENTITY_CONFIG[kind].directory}/${id}.json`;
+}
+function graphEntities(graph, kind) {
+    const key = ENTITY_CONFIG[kind].graph_key;
+    return (graph[key] ?? []);
+}
+function parseJson(value, source) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid JSON in ${source}: ${message}`);
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function writeJsonAtomically(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary_path = `${path}.tmp-${randomUUID()}`;
+    try {
+        await writeFile(temporary_path, `${stringifyCanonicalJson(value, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+            flag: 'wx'
+        });
+        await rename(temporary_path, path);
+    }
+    catch (error) {
+        await rm(temporary_path, { force: true });
+        throw error;
+    }
+}
+async function assertManagedDirectoryEntries(directory) {
+    if (!(await pathExists(directory)))
+        return;
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json')) {
+            throw new Error(`Managed projection directory contains unsupported entry: ${join(directory, entry.name)}`);
+        }
+    }
+}
+async function materializeEntityKind(input) {
+    const directory = join(input.projection_dir, ENTITY_CONFIG[input.kind].directory);
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await assertManagedDirectoryEntries(directory);
+    const desired_names = new Set();
+    for (const entity of input.entities) {
+        input.check?.();
+        const name = `${entity.id}.json`;
+        desired_names.add(name);
+        await writeJsonAtomically(join(directory, name), entity);
+    }
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        if (entry.isFile() &&
+            entry.name.endsWith('.json') &&
+            !desired_names.has(entry.name)) {
+            input.check?.();
+            await rm(join(directory, entry.name));
+        }
+    }
+}
+export function resolveProjectionDirectory(input) {
+    return (input.override ??
+        join(input.repository_root, DEFAULT_PROJECTION_DIRECTORY_NAME));
+}
+export async function projectionHasManagedContent(projection_dir) {
+    if (await pathExists(join(projection_dir, 'tags.json')))
+        return true;
+    if (await pathExists(join(projection_dir, PACKAGE_USES_FILE)))
+        return true;
+    for (const kind of ENTITY_KINDS) {
+        const directory = join(projection_dir, ENTITY_CONFIG[kind].directory);
+        if (!(await pathExists(directory)))
+            continue;
+        if ((await readdir(directory)).some((name) => name.endsWith('.json'))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Undo an empty projection written into a directory that held no managed
+ * content: remove tags.json and the managed directories while they are still
+ * empty, and the projection directory itself only when nothing else is left.
+ */
+export async function removeEmptyGraphProjection(projection_dir) {
+    await rm(join(projection_dir, 'tags.json'), { force: true });
+    await rm(join(projection_dir, PACKAGE_USES_FILE), { force: true });
+    await rm(join(projection_dir, PROJECTION_MANIFEST_FILE), { force: true });
+    for (const name of [
+        ...ENTITY_KINDS.map((kind) => ENTITY_CONFIG[kind].directory),
+        'scratch'
+    ]) {
+        await removeEmptyDirectory(join(projection_dir, name));
+    }
+    await removeEmptyDirectory(projection_dir);
+}
+async function removeEmptyDirectory(path) {
+    if (!(await pathExists(path)))
+        return;
+    if ((await readdir(path)).length > 0)
+        return;
+    await rmdir(path);
+}
+/** Comparison authority belongs to the server, never editable projection metadata. */
+function withoutWorktreeBuildOverride(meta) {
+    if (!meta || !('worktree_build_override' in meta))
+        return meta;
+    const { worktree_build_override: _override, ...retained } = meta;
+    return retained;
+}
+/** Strips in-memory evidence and comparison markers from entities. */
+function withoutGraphEvidenceTransientState(graph) {
+    return {
+        ...graph,
+        nodes: graph.nodes.map((node) => ({
+            ...node,
+            data: {
+                ...node.data,
+                meta: withoutWorktreeBuildOverride(withoutEvidenceTransientState(node.data.meta))
+            }
+        })),
+        edges: graph.edges.map((edge) => edge.data
+            ? {
+                ...edge,
+                data: {
+                    ...edge.data,
+                    meta: withoutEvidenceTransientState(edge.data.meta)
+                }
+            }
+            : edge)
+    };
+}
+/**
+ * Evidence as storage holds it: a decoded legacy value is presented as the
+ * legacy value alone and current evidence without its decode marker, so
+ * unchanged entities never differ from their stored form.
+ */
+function storedGraphEvidence(graph) {
+    if (!isEvidenceBoundaryEnabled())
+        return graph;
+    return {
+        ...graph,
+        nodes: graph.nodes.map((node) => ({
+            ...node,
+            data: {
+                ...node.data,
+                meta: node.data.meta && encodeEvidenceMeta(node.data.meta)
+            }
+        })),
+        edges: graph.edges.map((edge) => edge.data
+            ? {
+                ...edge,
+                data: {
+                    ...edge.data,
+                    meta: edge.data.meta && encodeEvidenceMeta(edge.data.meta)
+                }
+            }
+            : edge)
+    };
+}
+/**
+ * Projection files show evidence as stored. `--upgrade-evidence` converts
+ * every legacy entity to the latest contract as one reviewable change;
+ * without it, legacy evidence is shown and saved unchanged.
+ */
+function presentProjectionEvidence(input_graph, upgrade_evidence) {
+    const graph = isEvidenceBoundaryEnabled() && upgrade_evidence
+        ? upgradeGraphEvidenceFormat(input_graph).graph
+        : storedGraphEvidence(input_graph);
+    return withoutGraphEvidenceTransientState(graph);
+}
+/**
+ * The local projection is current-format by construction, so every save
+ * states the explicit upgrade intent; the server keeps untouched legacy
+ * evidence only for clients that cannot retain it.
+ */
+export function prepareProjectionEvidenceForSave(graph) {
+    return isEvidenceBoundaryEnabled() ? markEvidenceFormatUpgrade(graph) : graph;
+}
+/**
+ * Present only in a scoped projection (workspace attach): the entities it
+ * holds. Every other entity is read from the workspace head.
+ */
+export const PROJECTION_MANIFEST_FILE = 'projection.json';
+function emptyProjectionScope() {
+    return { node: [], edge: [], path: [], path_relation: [] };
+}
+/** The entities a task scope names, whichever of their fields it covers. */
+export function projectionScopeOfTaskScope(task_scope) {
+    const scope = emptyProjectionScope();
+    for (const rule of task_scope.rules) {
+        if (!ENTITY_KINDS.includes(rule.entity_kind))
+            continue;
+        scope[rule.entity_kind].push(rule.entity_id);
+    }
+    return scope;
+}
+function mergeProjectionScopes(...scopes) {
+    const merged = emptyProjectionScope();
+    for (const kind of ENTITY_KINDS) {
+        merged[kind] = [...new Set(scopes.flatMap((scope) => scope[kind]))].sort();
+    }
+    return merged;
+}
+async function readProjectionManifest(projection_dir, access) {
+    // Found by listing, as package-uses.json is: an access may refuse a missing path.
+    if (!(await access.exists(projection_dir)))
+        return null;
+    const present = (await access.entries(projection_dir)).some((entry) => entry.is_file && entry.name === PROJECTION_MANIFEST_FILE);
+    if (!present)
+        return null;
+    const manifest = parseJson(await access.read(join(projection_dir, PROJECTION_MANIFEST_FILE)), PROJECTION_MANIFEST_FILE);
+    if (manifest?.version !== 1 ||
+        !manifest.scope ||
+        ENTITY_KINDS.some((kind) => !Array.isArray(manifest.scope?.[kind]))) {
+        throw new Error(`Unsupported ${PROJECTION_MANIFEST_FILE}.`);
+    }
+    return manifest;
+}
+async function projectionEntityIdsOnDisk(projection_dir) {
+    const scope = emptyProjectionScope();
+    for (const kind of ENTITY_KINDS) {
+        const directory = join(projection_dir, ENTITY_CONFIG[kind].directory);
+        if (!(await pathExists(directory)))
+            continue;
+        scope[kind] = (await readdir(directory))
+            .filter((name) => name.endsWith('.json'))
+            .map((name) => basename(name, '.json'));
+    }
+    return scope;
+}
+/** Whether the projection holds only a scope (workspace attach) instead of the whole graph. */
+export async function isScopedProjection(projection_dir) {
+    return ((await readProjectionManifest(projection_dir, DEFAULT_READ_ACCESS)) !== null);
+}
+function presentValidatedGraph(input_graph, upgrade_evidence) {
+    const graph = presentProjectionEvidence(canonicalizePortableGraph(portable_graph_schema.parse(input_graph)), upgrade_evidence);
+    const validation = validateProjectionGraph(graph);
+    if (!validation.is_valid) {
+        throw new Error(`Remote worktree graph failed local validation: ${validation.issues
+            .filter((issue) => issue.status === 'broken')
+            .map((issue) => `${issue.code}: ${issue.message}`)
+            .join('; ')}`);
+    }
+    return graph;
+}
+/**
+ * Writes the graph's projection. With `scope`, only those entities are
+ * written, with tags and package uses, and projection.json lists them. A
+ * projection that already holds a scope keeps it, with any entity the
+ * projection added, unless `full` asks for the whole graph again.
+ */
+export async function materializeGraphProjection(input) {
+    const graph = presentValidatedGraph(input.graph, input.upgrade_evidence === true);
+    let scope = input.scope
+        ? mergeProjectionScopes(input.scope)
+        : null;
+    if (!scope && !input.full) {
+        const existing = await readProjectionManifest(input.projection_dir, DEFAULT_READ_ACCESS);
+        if (existing) {
+            scope = mergeProjectionScopes(existing.scope, await projectionEntityIdsOnDisk(input.projection_dir));
+        }
+    }
+    input.check?.();
+    await mkdir(input.projection_dir, { recursive: true, mode: 0o700 });
+    for (const kind of ENTITY_KINDS) {
+        input.check?.();
+        const selected = scope ? new Set(scope[kind]) : null;
+        // The manifest keeps every scoped id, present in the graph or not, so a
+        // scoped entity created later still reads from its file, and its
+        // deletion as a deletion.
+        const entities = graphEntities(graph, kind).filter((entity) => !selected || selected.has(entity.id));
+        await materializeEntityKind({
+            projection_dir: input.projection_dir,
+            kind,
+            entities,
+            check: input.check
+        });
+    }
+    if (scope) {
+        await writeJsonAtomically(join(input.projection_dir, PROJECTION_MANIFEST_FILE), {
+            version: 1,
+            scope
+        });
+    }
+    else {
+        await rm(join(input.projection_dir, PROJECTION_MANIFEST_FILE), {
+            force: true
+        });
+    }
+    input.check?.();
+    await writeJsonAtomically(join(input.projection_dir, 'tags.json'), graph.tags ?? []);
+    // Present only while the graph uses a package, as the graph's key is.
+    if (graph.package_uses?.length) {
+        await writeJsonAtomically(join(input.projection_dir, PACKAGE_USES_FILE), graph.package_uses);
+    }
+    else {
+        await rm(join(input.projection_dir, PACKAGE_USES_FILE), { force: true });
+    }
+    await mkdir(join(input.projection_dir, 'scratch'), {
+        recursive: true,
+        mode: 0o700
+    });
+    return graph;
+}
+/**
+ * Adds entities to a scoped projection when its task scope grows: writes the
+ * file of each newly scoped entity the graph has and the projection lacks,
+ * leaving every existing file, edited or not, as it is.
+ */
+export async function extendScopedProjection(input) {
+    const manifest = await readProjectionManifest(input.projection_dir, DEFAULT_READ_ACCESS);
+    if (!manifest)
+        throw new Error('The projection holds the whole graph.');
+    // Presented as materializing writes it, but not validated as a whole: the
+    // graph may carry uncommitted edits, which only a commit validates.
+    const graph = presentProjectionEvidence(canonicalizePortableGraph(portable_graph_schema.parse(input.graph)), false);
+    const on_disk = await projectionEntityIdsOnDisk(input.projection_dir);
+    const added = emptyProjectionScope();
+    for (const kind of ENTITY_KINDS) {
+        // A listed entity whose file is missing was deleted; never restore it.
+        const held = new Set([...on_disk[kind], ...manifest.scope[kind]]);
+        const wanted = new Set(input.scope[kind]);
+        for (const entity of graphEntities(graph, kind)) {
+            if (!wanted.has(entity.id) || held.has(entity.id))
+                continue;
+            await writeJsonAtomically(join(input.projection_dir, entityRelativePath(kind, entity.id)), entity);
+            added[kind].push(entity.id);
+        }
+    }
+    // Every newly scoped id is listed, written or not, as materializing lists it.
+    await writeJsonAtomically(join(input.projection_dir, PROJECTION_MANIFEST_FILE), {
+        version: 1,
+        scope: mergeProjectionScopes(manifest.scope, input.scope, on_disk)
+    });
+    return added;
+}
+/**
+ * Lists in a scoped projection's manifest every entity file it holds, so an
+ * entity created in the projection and committed reads as deleted, not as
+ * the head has it, once its file is removed. A whole projection is left as
+ * it is.
+ */
+export async function recordScopedProjectionFiles(projection_dir) {
+    const manifest = await readProjectionManifest(projection_dir, DEFAULT_READ_ACCESS);
+    if (!manifest)
+        return;
+    await writeJsonAtomically(join(projection_dir, PROJECTION_MANIFEST_FILE), {
+        version: 1,
+        scope: mergeProjectionScopes(manifest.scope, await projectionEntityIdsOnDisk(projection_dir))
+    });
+}
+/** Whether a projection.json is present, readable or not. */
+export async function hasProjectionManifest(projection_dir) {
+    return pathExists(join(projection_dir, PROJECTION_MANIFEST_FILE));
+}
+const DEFAULT_READ_ACCESS = {
+    exists: pathExists,
+    read: (path) => readFile(path, 'utf8'),
+    entries: async (path) => (await readdir(path, { withFileTypes: true })).map((entry) => ({
+        name: entry.name,
+        is_file: entry.isFile()
+    }))
+};
+async function readProjectionEntities(input) {
+    const config = ENTITY_CONFIG[input.kind];
+    const directory = join(input.projection_dir, config.directory);
+    if (!(await input.access.exists(directory))) {
+        throw new Error(`Managed projection directory is missing: ${config.directory}`);
+    }
+    const entries = await input.access.entries(directory);
+    if (entries.some((entry) => !entry.is_file || !entry.name.endsWith('.json')))
+        throw new Error('Unsupported projection entry.');
+    const entities = [];
+    const errors = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const id = basename(entry.name, '.json');
+        if (!UUID_PATTERN.test(id)) {
+            throw new Error(`Projection filename must be a stable UUID: ${entry.name}`);
+        }
+        const relative_path = entityRelativePath(input.kind, id);
+        const fileError = (field_path, message) => errors.push({
+            entity_kind: input.kind,
+            entity_id: id,
+            relative_path,
+            field_path,
+            message
+        });
+        let value;
+        try {
+            value = parseJson(await input.access.read(join(directory, entry.name)), relative_path);
+        }
+        catch (error) {
+            if (!(error instanceof Error) ||
+                !error.message.startsWith('Invalid JSON'))
+                throw error;
+            fileError('', error.message);
+            continue;
+        }
+        const parsed = config.safe_parse(value);
+        if (!parsed.success) {
+            // The schema can check one field more than once; a field that fails
+            // the same way twice is one invalid field.
+            const reported = new Set();
+            for (const issue of parsed.error.issues) {
+                const field_path = issue.path.map(String).join('.');
+                const key = JSON.stringify([field_path, issue.message]);
+                if (reported.has(key))
+                    continue;
+                reported.add(key);
+                fileError(field_path, issue.message);
+            }
+            continue;
+        }
+        if (parsed.data.id !== id) {
+            fileError('id', `Projection entity id ${parsed.data.id} does not match filename ${entry.name}.`);
+            continue;
+        }
+        entities.push(parsed.data);
+    }
+    return { entities, errors };
+}
+/**
+ * Composes the projection's files into one graph. A scoped projection
+ * (projection.json) composes only over `base`, its workspace's head: the
+ * entities it lists or holds come from their files, a listed entity whose
+ * file is gone reads as deleted, and every other entity comes from the base.
+ */
+export async function composeGraphProjection(projection_dir, access = DEFAULT_READ_ACCESS, options = {}) {
+    const tags_path = join(projection_dir, 'tags.json');
+    if (!(await access.exists(tags_path))) {
+        throw new Error('Managed projection tags.json is missing.');
+    }
+    const manifest = await readProjectionManifest(projection_dir, access);
+    if (manifest && !options.base) {
+        throw new Error(`This projection holds only its workspace's task scope (${PROJECTION_MANIFEST_FILE}); read it through its workspace, for example sdlc workspace status.`);
+    }
+    const base = manifest && options.base ? await options.base() : null;
+    const entity_results = await Promise.allSettled(ENTITY_KINDS.map((kind) => readProjectionEntities({ projection_dir, kind, access }).then((read) => ({
+        kind,
+        ...read
+    }))));
+    const entity_groups = entity_results.map((result) => {
+        if (result.status === 'rejected')
+            throw result.reason;
+        return result.value;
+    });
+    const entity_errors = entity_groups.flatMap((group) => group.errors);
+    if (entity_errors.length > 0)
+        throw new ProjectionEntityErrors(entity_errors);
+    const graph_input = {
+        nodes: [],
+        edges: [],
+        paths: [],
+        path_relations: [],
+        tags: parseJson(await access.read(tags_path), 'tags.json')
+    };
+    // The file is optional, so it is found by listing the folder: an access may treat a
+    // missing path it is asked about as an incomplete projection (health inspection does).
+    const package_uses_path = join(projection_dir, PACKAGE_USES_FILE);
+    const has_package_uses = (await access.entries(projection_dir)).some((entry) => entry.is_file && entry.name === PACKAGE_USES_FILE);
+    if (has_package_uses) {
+        graph_input.package_uses = parseJson(await access.read(package_uses_path), PACKAGE_USES_FILE);
+    }
+    for (const group of entity_groups) {
+        if (manifest && base) {
+            const held = new Set([
+                ...manifest.scope[group.kind],
+                ...group.entities.map((entity) => entity.id)
+            ]);
+            group.entities = [
+                ...graphEntities(base, group.kind).filter((entity) => !held.has(entity.id)),
+                ...group.entities
+            ];
+        }
+        if (group.kind === 'node')
+            graph_input.nodes = group.entities;
+        if (group.kind === 'edge')
+            graph_input.edges = group.entities;
+        if (group.kind === 'path')
+            graph_input.paths = group.entities;
+        if (group.kind === 'path_relation') {
+            graph_input.path_relations =
+                group.entities;
+        }
+    }
+    const graph = canonicalizePortableGraph(portable_graph_schema.parse({
+        ...graph_input,
+        nodes: graph_input.nodes.map((node) => ({
+            ...node,
+            data: {
+                ...node.data,
+                meta: withoutWorktreeBuildOverride(node.data.meta)
+            }
+        }))
+    }));
+    const graph_json = stringifyCanonicalGraph(graph);
+    return {
+        graph,
+        graph_json,
+        graph_hash: createHash('sha256').update(graph_json).digest('hex')
+    };
+}
+/**
+ * With `node_parents`, every node's parent is checked as a hosted apply of the
+ * whole graph checks it; local workspace commits ask for it, while a graph
+ * pulled from or bound to a hosted branch keeps the hosted save's rules.
+ */
+export function validateProjectionGraph(graph, options = {}) {
+    const validation = validateBuiltGraph(graph, { id_policy: 'uuid', node_parents: options.node_parents });
+    return { is_valid: validation.is_valid, issues: validation.issues };
+}
+function entityMap(graph, kind) {
+    return new Map(graphEntities(graph, kind).map((entity) => [entity.id, entity]));
+}
+export function graphHasProjectionEntity(graph, intent) {
+    return entityMap(graph, intent.entity_kind).has(intent.entity_id);
+}
+export function restoreMissingProjectionEntities(input) {
+    const current_graph = canonicalizePortableGraph(portable_graph_schema.parse(input.current_graph));
+    const source_graph = canonicalizePortableGraph(portable_graph_schema.parse(input.source_graph));
+    const restored_graph = {
+        ...current_graph,
+        nodes: [...current_graph.nodes],
+        edges: [...current_graph.edges],
+        paths: [...(current_graph.paths ?? [])],
+        path_relations: [...(current_graph.path_relations ?? [])]
+    };
+    for (const kind of ENTITY_KINDS) {
+        const current_entities = entityMap(current_graph, kind);
+        const source_entities = entityMap(source_graph, kind);
+        for (const entry of input.entries) {
+            if (entry.entity_kind !== kind || current_entities.has(entry.entity_id)) {
+                continue;
+            }
+            const source_entity = source_entities.get(entry.entity_id);
+            if (!source_entity) {
+                throw new Error(`Recovery source is missing ${entry.entity_kind} ${entry.entity_id}.`);
+            }
+            current_entities.set(entry.entity_id, source_entity);
+        }
+        const restored_entities = [...current_entities.values()];
+        if (kind === 'node') {
+            restored_graph.nodes = restored_entities;
+        }
+        else if (kind === 'edge') {
+            restored_graph.edges = restored_entities;
+        }
+        else if (kind === 'path') {
+            restored_graph.paths = restored_entities;
+        }
+        else {
+            restored_graph.path_relations =
+                restored_entities;
+        }
+    }
+    return canonicalizePortableGraph(portable_graph_schema.parse(restored_graph));
+}
+function deletionKey(intent) {
+    return `${intent.entity_kind}:${intent.entity_id}`;
+}
+export function diffProjectionGraphs(input) {
+    // The decode marker is in-memory state, never a projection change.
+    const semantic_diff = diffPortableGraphs({
+        ...input,
+        base_graph: withoutGraphEvidenceTransientState(storedGraphEvidence(input.base_graph)),
+        current_graph: withoutGraphEvidenceTransientState(input.current_graph)
+    });
+    const deleted = [];
+    const missing_unrecorded = [];
+    const deletion_keys = new Set((input.deletion_intents ?? []).map(deletionKey));
+    const projectionEntry = (entry) => ({
+        ...entry,
+        relative_path: entityRelativePath(entry.entity_kind, entry.entity_id)
+    });
+    for (const semantic_entry of semantic_diff.deleted) {
+        const entry = projectionEntry(semantic_entry);
+        if (deletion_keys.has(deletionKey(entry)))
+            deleted.push(entry);
+        else
+            missing_unrecorded.push(entry);
+    }
+    const sort_entries = (entries) => entries.sort((left, right) => left.relative_path.localeCompare(right.relative_path));
+    return {
+        added: sort_entries(semantic_diff.added.map(projectionEntry)),
+        modified: sort_entries(semantic_diff.modified.map(projectionEntry)),
+        deleted: sort_entries(deleted),
+        missing_unrecorded: sort_entries(missing_unrecorded),
+        tags_changed: semantic_diff.tags_changed,
+        ...(semantic_diff.package_uses_changed
+            ? { package_uses_changed: true }
+            : {})
+    };
+}
+export function projectionDiffHasChanges(diff) {
+    return (diff.added.length > 0 ||
+        diff.modified.length > 0 ||
+        diff.deleted.length > 0 ||
+        diff.missing_unrecorded.length > 0 ||
+        diff.tags_changed ||
+        diff.package_uses_changed === true);
+}
+export function parseProjectionEntityPath(input) {
+    if (isAbsolute(input.path)) {
+        throw new Error('Projection entity path must be relative to sdlc/.');
+    }
+    const normalized = input.path.split('/').join(sep);
+    const absolute_path = join(input.projection_dir, normalized);
+    const relative_path = relative(input.projection_dir, absolute_path)
+        .split(sep)
+        .join('/');
+    if (relative_path.startsWith('../') || relative_path === '..') {
+        throw new Error('Projection entity path must stay inside sdlc/.');
+    }
+    for (const kind of ENTITY_KINDS) {
+        const match = relative_path.match(new RegExp(`^${ENTITY_CONFIG[kind].directory}/([0-9a-f-]+)\\.json$`, 'i'));
+        if (!match)
+            continue;
+        const entity_id = match[1] ?? '';
+        if (!UUID_PATTERN.test(entity_id)) {
+            throw new Error('Projection entity path must use a stable UUID filename.');
+        }
+        return { entity_kind: kind, entity_id, relative_path };
+    }
+    throw new Error('Projection entity path must identify a JSON file under nodes, edges, paths, or path-relations.');
+}
+/**
+ * Removes one entity file. A file already deleted by hand is accepted when
+ * the projection holds its entity (a scoped projection holds only its
+ * manifest's scope; compose fills the rest from the base) and `allow_missing`
+ * says the entity is still in the base, so the caller can record the deletion
+ * the commit or save asks for.
+ */
+export async function removeProjectionEntity(input) {
+    const entry = parseProjectionEntityPath({
+        projection_dir: input.projection_dir,
+        path: input.relative_path
+    });
+    const path = join(input.projection_dir, entry.relative_path);
+    if (!(await pathExists(path))) {
+        const manifest = await readProjectionManifest(input.projection_dir, DEFAULT_READ_ACCESS);
+        const held = !manifest || manifest.scope[entry.entity_kind].includes(entry.entity_id);
+        if (held && input.allow_missing?.(entry))
+            return entry;
+        throw new Error(`Projection entity does not exist: ${entry.relative_path}`);
+    }
+    await rm(path);
+    return entry;
+}
+//# sourceMappingURL=projection.js.map