@n8r/surface 0.0.0-stage → 0.1.0-experimental.5

package/dist/skill-cyclonedx.js

@@ -0,0 +1,214 @@
+/** Bounded offline exchange alongside checked native records. No source inspection. */
+import fs from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createHash } from 'node:crypto';
+import { checkBundle, readBundle, privacy, digest } from './skill-artifacts.js';
+import { canonical } from './portable.js';
+import { decodeJsonValue } from './codec.js';
+import { verifySuccessor } from './revisions.js';
+const members = ['surface.cdx.json', 'surface-records.json', 'mapping.json', 'README.md'];
+const hash = (x) => `sha256:${createHash('sha256').update(x).digest('hex')}`;
+const json = (x) => JSON.stringify(x, null, 2) + '\n';
+function refuse() { throw Error('CycloneDX exchange refused: check contracts, mapping, privacy, lineage and saved bytes.'); }
+function guard(fn) { try {
+    return fn();
+}
+catch {
+    return refuse();
+} }
+export { validateBom } from './cyclonedx-validation.js';
+import { validateBom } from './cyclonedx-validation.js';
+function mappingFor(input, b) {
+    privacy(input);
+    if (!input || typeof input !== 'object' || Object.keys(input).sort().join(',') !== 'dependencies,nodes')
+        refuse();
+    const m = input;
+    if (!Array.isArray(m.nodes) || !Array.isArray(m.dependencies))
+        refuse();
+    const ids = new Set(b.surface.nodes.map(n => n.id));
+    if (m.nodes.length !== ids.size)
+        refuse();
+    for (const n of m.nodes) {
+        if (!n || !ids.delete(n.id) || !['component', 'service'].includes(n.kind) || typeof n.rationale !== 'string' || !n.rationale.trim())
+            refuse();
+        const keys = Object.keys(n).sort().join(',');
+        if (n.kind === 'component' ? (keys !== 'id,kind,rationale,type' || typeof n.type !== 'string') : keys !== 'id,kind,rationale')
+            refuse();
+    }
+    if (new Set(m.dependencies).size !== m.dependencies.length || m.dependencies.some(x => typeof x !== 'string'))
+        refuse();
+    return m;
+}
+function serial(id) {
+    const h = createHash('sha256').update('n8r.surface.cyclonedx/1\0' + id).digest('hex');
+    return `urn:uuid:${h.slice(0, 8)}-${h.slice(8, 12)}-5${h.slice(13, 16)}-a${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+function checkPrevious(b, m, prev) {
+    const old = prev.bundle;
+    for (const key of ['research', 'surface']) {
+        if (digest(old[key]) !== digest(b[key])) {
+            verifySuccessor(old[key], b[key]);
+            if (b[key].revision.parent?.digest !== digest(old[key]))
+                refuse();
+        }
+    }
+    for (const a of [old.research, old.surface, ...old.dependencies]) {
+        const next = [b.research, b.surface, ...b.dependencies].find(n => n.id === a.id && n.revision.id === a.revision.id);
+        if (next && digest(a) !== digest(next))
+            refuse();
+    }
+    for (const n of old.surface.nodes)
+        if (!b.surface.nodes.some(x => x.id === n.id))
+            refuse();
+    for (const d of old.research.decisions)
+        if (!b.research.decisions.some(x => canonical(x) === canonical(d)))
+            refuse();
+    for (const n of prev.mapping.nodes) {
+        const next = m.nodes.find(x => x.id === n.id);
+        if (!next || next.kind !== n.kind || next.type !== n.type)
+            refuse();
+    }
+}
+export function projectBundle(input, mapping, previous) {
+    return guard(() => {
+        const b = checkBundle(input), m = mappingFor(mapping, b), s = b.surface;
+        if (previous)
+            checkPrevious(b, m, previous);
+        const components = [], services = [];
+        for (const n of s.nodes) {
+            const t = m.nodes.find(x => x.id === n.id);
+            const item = { 'bom-ref': n.id, name: n.label, description: `${s.kind} Surface node; classification: ${t.rationale} This inventory does not establish deployment or runtime use.` };
+            if (t.kind === 'component') {
+                item.type = t.type;
+                components.push(item);
+            }
+            else
+                services.push(item);
+        }
+        const selected = new Set(m.dependencies), deps = new Map();
+        const relationships = s.relationships.map(e => {
+            const projected = selected.delete(e.id);
+            if (projected) {
+                if (!('binding' in e) || e.binding.state !== 'configured' || e.binding.claims.length !== 1)
+                    refuse();
+                const targets = deps.get(e.from) ?? new Set();
+                targets.add(e.binding.claims[0].target);
+                deps.set(e.from, targets);
+            }
+            return { id: e.id, projected, reason: projected ? 'Explicit configured dependency projection; detailed semantics retained in native snapshot.' : 'Not projected as a dependency; see native relationship and evidence.', relationship: e };
+        });
+        if (selected.size)
+            refuse();
+        const bom = { bomFormat: 'CycloneDX', specVersion: '1.7', serialNumber: previous?.bom.serialNumber ?? serial(s.id), version: previous ? previous.bom.version + 1 : 1,
+            metadata: { timestamp: s.revision.createdAt }, ...(components.length ? { components } : {}), ...(services.length ? { services } : {}),
+            ...(deps.size ? { dependencies: [...deps].map(([ref, targets]) => ({ ref, dependsOn: [...targets].sort() })) } : {}),
+            compositions: [{ aggregate: 'unknown' }], externalReferences: [{ type: 'other', url: 'surface-records.json', comment: 'Exact checked native research/Surface snapshot. Required for evidence and Surface meanings.' }, { type: 'other', url: 'mapping.json', comment: 'Mapping and explicit semantic losses; not a lossless BOM-only representation.' }] };
+        validateBom(bom);
+        const report = { profile: 'n8r.cyclonedx-exchange/1', standard: 'CycloneDX 1.7', surface: { id: s.id, revision: s.revision.id, digest: digest(s), kind: s.kind }, research: { id: b.research.id, revision: b.research.revision.id, digest: digest(b.research) }, mapping: m, relationships,
+            losses: ['Dependency projection does not encode purpose, integration mechanism, configuration evidence, binding states, alternatives or decisions; retained in surface-records.json and relationship report.', 'Node versions, package identifiers, upstream SBOM contents and transitive dependency completeness are not inferred from labels.', 'No runtime, control conformance, complete inventory or round-trip compatibility claim. Native records remain authoritative.'], gaps: s.gaps };
+        return { bom, report };
+    });
+}
+function safeDirectory(directory) {
+    for (let p = resolve(directory);; p = dirname(p)) {
+        try {
+            const stat = fs.lstatSync(p);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                refuse();
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (p === dirname(p))
+            break;
+    }
+}
+function read(file) { const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); try {
+    const s = fs.fstatSync(fd);
+    if (!s.isFile() || s.size > 8 * 1024 * 1024)
+        refuse();
+    return new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(fd));
+}
+finally {
+    fs.closeSync(fd);
+} }
+function readJson(file) { return decodeJsonValue(read(file)); }
+function description(b, bom) { return `# CycloneDX exchange\n\nCycloneDX 1.7 · BOM version ${bom.version} · ${b.surface.kind} Surface.\n\nOpen surface.cdx.json in a compatible consumer. Keep surface-records.json and mapping.json with it: they preserve the native evidence and explain the projection/losses. Configured dependencies do not establish runtime use. Coverage remains unknown.\n\nUse the standalone helper read operation to verify this directory before continuation. Prior files must stay unchanged.\n`; }
+export function readExchange(directory) {
+    return guard(() => {
+        directory = resolve(directory);
+        safeDirectory(directory);
+        if (fs.readdirSync(directory).sort().join(',') !== [...members, 'manifest.json'].sort().join(','))
+            refuse();
+        const manifest = readJson(join(directory, 'manifest.json'));
+        if (manifest.version !== 1 || Object.keys(manifest).sort().join(',') !== 'files,predecessor,version' || Object.keys(manifest.files ?? {}).sort().join(',') !== [...members].sort().join(','))
+            refuse();
+        if (manifest.predecessor !== null && !/^sha256:[a-f0-9]{64}$/.test(manifest.predecessor))
+            refuse();
+        for (const f of members)
+            if (hash(read(join(directory, f))) !== manifest.files[f])
+                refuse();
+        const bundle = checkBundle(readJson(join(directory, 'surface-records.json'))), report = readJson(join(directory, 'mapping.json')), bom = readJson(join(directory, 'surface.cdx.json'));
+        const mapping = mappingFor(report.mapping, bundle), expected = projectBundle(bundle, mapping);
+        validateBom(bom);
+        if (!Number.isSafeInteger(bom.version) || bom.version < 1 || (bom.version === 1) !== (manifest.predecessor === null))
+            refuse();
+        expected.bom.version = bom.version;
+        if (canonical(expected.bom) !== canonical(bom) || canonical(expected.report) !== canonical(report) || read(join(directory, 'README.md')) !== description(bundle, bom))
+            refuse();
+        return { bundle, mapping, bom, report, predecessor: manifest.predecessor };
+    });
+}
+export function saveExchange(bundleDirectory, mapping, destination, previousDirectory) {
+    return guard(() => {
+        const bundle = readBundle(bundleDirectory), m = mappingFor(mapping, bundle);
+        const previous = previousDirectory ? readExchange(previousDirectory) : undefined;
+        const prevBytes = previousDirectory ? read(join(previousDirectory, 'manifest.json')) : undefined;
+        if (!previous && (bundle.surface.revision.parent || bundle.research.revision.parent))
+            refuse();
+        const { bom, report } = projectBundle(bundle, m, previous);
+        const files = { 'surface.cdx.json': json(bom), 'surface-records.json': json(bundle), 'mapping.json': json(report), 'README.md': description(bundle, bom) };
+        const manifest = { version: 1, predecessor: prevBytes ? hash(prevBytes) : null, files: Object.fromEntries(members.map(n => [n, hash(files[n])])) };
+        destination = resolve(destination);
+        safeDirectory(dirname(destination));
+        fs.mkdirSync(destination, { mode: 0o700 });
+        for (const [name, bytes] of Object.entries({ ...files, 'manifest.json': json(manifest) }))
+            fs.writeFileSync(join(destination, name), bytes, { flag: 'wx', mode: 0o600 });
+        const saved = readExchange(destination);
+        if (previousDirectory) {
+            readExchange(previousDirectory);
+            if (read(join(previousDirectory, 'manifest.json')) !== prevBytes)
+                refuse();
+        }
+        readBundle(bundleDirectory);
+        return saved;
+    });
+}
+function main(args) {
+    if (args.length === 1 && args[0] === 'help') {
+        console.log('CycloneDX 1.7 exchange helper: export BUNDLE_DIRECTORY MAPPING.json NEW_DIRECTORY [PREVIOUS_EXCHANGE] | read DIRECTORY. Requires checked native records. Mapping: {nodes:[{id,kind,type?,rationale}],dependencies:[relationshipId]}. No network, source reads, runtime package install or product CLI.');
+        return;
+    }
+    if (args[0] === 'read' && args.length === 2) {
+        const e = readExchange(args[1]);
+        console.log(json({ status: 'checked', bom: e.bom, report: e.report }));
+        return;
+    }
+    if (args[0] === 'export' && (args.length === 4 || args.length === 5)) {
+        const e = saveExchange(args[1], readJson(args[2]), args[3], args[4]);
+        console.log(json({ status: 'saved-and-read-back', serialNumber: e.bom.serialNumber, version: e.bom.version }));
+        return;
+    }
+    refuse();
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch {
+        console.error('CycloneDX exchange failed. Check mapping, native records, privacy, predecessor and destination; no success claimed.');
+        process.exitCode = 1;
+    }
+}

package/dist/skill-presentation.d.ts

@@ -0,0 +1,10 @@
+/** Versioned, deterministic human presentation. Never adds research claims. */
+import type { Bundle } from './skill-artifacts.js';
+interface Section {
+    title: string;
+    paragraphs: string[];
+}
+export declare function reportSections(b: Bundle): Section[];
+export declare function renderBrief(b: Bundle): string;
+export declare function renderBundleHtml(b: Bundle): string;
+export {};

package/dist/skill-presentation.js

@@ -0,0 +1,108 @@
+import { canonical, checkSize, digest } from './portable.js';
+const escape = (s) => s.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const markdown = (s) => s.replace(/[\r\n]+/g, ' ').replace(/[\\`*_{}\[\]<>#!|]/g, '\\$&');
+const embedded = (value) => JSON.stringify(value, null, 2).replace(/[<>&\u2028\u2029]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+export function reportSections(b) {
+    const { research: r, surface: s } = b;
+    const records = [r, ...b.dependencies.filter((a) => a.contract === 'n8r.research/0.1')];
+    const name = (id) => s.nodes.find(n => n.id === id)?.label.replace(/ \(role endpoint\)$/, '') ?? (s.kind === 'bound' && s.instance.id === id ? s.instance.label : id);
+    const value = (v) => typeof v === 'string' ? name(v) : Array.isArray(v) ? v.map(value).join('; ') : v && typeof v === 'object' ? Object.entries(v).map(([k, x]) => `${k}: ${value(x)}`).join('; ') : String(v);
+    const citations = (basis) => basis.flatMap(ref => {
+        const record = records.find(x => x.id === ref.record && x.revision.id === ref.revision);
+        return (record?.findings.filter(f => ref.items.includes(f.id)) ?? []).flatMap(f => f.claims.flatMap(c => c.evidence.map(e => {
+            const source = record.sources.find(x => x.id === e.source);
+            return `${e.locator.startsWith(source?.location ?? '\0') ? e.locator : `${source?.location ?? e.source} — ${e.locator}`} (source revision ${source?.version ?? 'unspecified'}; research ${record.revision.id})`;
+        })));
+    });
+    const previous = r.revision.parent && records.find(x => x.id === r.revision.parent.id && x.revision.id === r.revision.parent.revision && digest(x) === r.revision.parent.digest);
+    const summary = [], changes = [], impact = [], evidence = [], unknown = [...s.gaps];
+    for (const edge of s.relationships) {
+        const connection = `${name(edge.from)} → ${name(edge.to)}`;
+        const prefix = s.relationships.length > 1 ? `${connection}: ` : '';
+        if ('binding' in edge) {
+            const targets = edge.binding.claims.map(c => name(c.target)).join(' / ');
+            summary.push(edge.binding.state === 'configured' ? `${name(edge.from)} is configured to use ${targets}.` : edge.binding.state === 'conflicting' ? `${connection}: the configured target is disputed (${targets}). No single target is established.` : `${connection}: target ${edge.binding.state}. ${edge.binding.note}`);
+            const prior = previous && previous.findings.find(f => s.kind === 'bound' && f.subject === s.instance.id && f.property === edge.id);
+            if (prior && prior.state === 'known' && edge.binding.state === 'configured') {
+                const old = prior.claims.map(c => value(c.value)).join(' / ');
+                const same = canonical(prior.claims.map(c => c.value).sort()) === canonical(edge.binding.claims.map(c => c.target).sort());
+                const oldDisplay = old === targets && !same ? prior.claims.map(c => `${value(c.value)} (${String(c.value)})`).join(' / ') : old;
+                const newDisplay = old === targets && !same ? edge.binding.claims.map(c => `${name(c.target)} (${c.target})`).join(' / ') : targets;
+                changes.push(same ? `${prefix}The recorded target remains ${targets}.` : `${prefix}${oldDisplay} was the previously recorded target; ${newDisplay} is the configured target in this revision.`);
+            }
+            evidence.push(...citations(edge.binding.claims.flatMap(c => c.basis)).map(c => `${prefix}Target selection: ${c}.`));
+            if (edge.binding.state !== 'configured')
+                unknown.push(`${connection}: binding ${edge.binding.state}. ${edge.binding.note}`);
+            if (edge.binding.state === 'configured')
+                impact.push(`${prefix}${targets} is the target to consider when reviewing this configured connection. Configuration alone does not establish reachability or actual use.`);
+        }
+        else {
+            summary.push(edge.state === 'possible' ? `${name(edge.from)} can connect to ${name(edge.to)}, according to the documented capability. No instance target is established.` : `${connection}: capability ${edge.state}. ${edge.note}`);
+            impact.push(`${connection}: this describes a product possibility, not an instance selection or an exercised connection.`);
+        }
+        if (edge.conditions.length)
+            summary.push(`${connection} — Conditions: ${edge.conditions.join('; ')}`);
+        for (const [label, detail] of [['Purpose', edge.purpose], ['Integration', edge.integration]]) {
+            if (detail.claims.length)
+                impact.push(`${prefix}${label}${detail.state === 'known' ? '' : ` (${detail.state})`}: ${detail.claims.map(c => c.value).join(' / ')}`);
+            if (detail.state !== 'known')
+                unknown.push(`${connection}: ${label.toLowerCase()} ${detail.state}. ${detail.note}`);
+            evidence.push(...citations(detail.claims.flatMap(c => c.basis)).map(c => `${prefix}${label}: ${c}.`));
+        }
+        evidence.push(...citations(edge.basis).map(c => `${prefix}Documented support: ${c}.`));
+        evidence.push(...citations(edge.configuration.claims.flatMap(c => c.basis)).map(c => `${prefix}Configuration: ${c}.`));
+        if (edge.configuration.state !== 'known')
+            unknown.push(`${connection}: configuration ${edge.configuration.state}. ${edge.configuration.note}`);
+    }
+    if (s.kind === 'capability')
+        for (const group of s.exclusiveGroups)
+            summary.push(`Mutually exclusive alternatives: ${group.members.map(id => { const edge = s.relationships.find(e => e.id === id); return edge ? `${name(edge.from)} → ${name(edge.to)}` : id; }).join(' / ')}. These are not jointly available selections.`);
+    if (!changes.length)
+        changes.push(r.revision.parent ? 'A successor is recorded. An exact previous target comparison is unavailable in this bundle.' : 'This is the first saved description; no earlier revision is being compared.');
+    changes.push(`Reason recorded for this revision: ${r.revision.reason}.`);
+    const decisions = r.decisions.map(d => `${r.alternatives.find(a => a.id === d.alternative)?.title ?? d.alternative} — ${d.choice}. ${d.reason} Recorded by ${d.by} on ${d.at}.${previous?.decisions.some(x => canonical(x) === canonical(d)) ? ' Unchanged from the previous research revision.' : ''}`);
+    return [
+        { title: 'Current picture', paragraphs: summary.length ? summary : ['No connections have been described yet. This does not establish their absence.'] },
+        { title: 'What changed', paragraphs: changes },
+        { title: 'Why it matters', paragraphs: impact.length ? impact : ['The recorded scope bounds what can be concluded. No operational impact has been established.'] },
+        { title: 'Evidence', paragraphs: [...new Set(evidence)].length ? [...new Set(evidence)] : ['No connection evidence is recorded. Missing evidence does not establish absence.'] },
+        { title: 'Decisions', paragraphs: decisions.length ? decisions : ['No human decisions are recorded.'] },
+        { title: 'What remains unknown', paragraphs: [...new Set(unknown)].length ? [...new Set(unknown)] : ['No additional gaps are listed. This is not a completeness or runtime assurance claim.'] },
+        { title: 'Questions to carry forward', paragraphs: r.questions.length ? r.questions.map(q => q.text) : ['No next investigation is recorded. Review the evidence and scope before extending the research.'] }
+    ];
+}
+export function renderBrief(b) {
+    const sections = reportSections(b);
+    return `# ${markdown(b.surface.title)}\n\n${sections[0].paragraphs.map(markdown).join('\n\n')}\n\n` + sections.slice(1).map(s => `## ${s.title}\n\n${s.paragraphs.map(markdown).join('\n\n')}\n`).join('\n') + `\n## Scope\n\n${markdown(b.surface.scope)}\n` + '\n## Read further\n\n[Research and evidence](research.html) · [Checked Surface data](surface.json)\n';
+}
+export function renderBundleHtml(b) {
+    const sections = reportSections(b), lead = sections[0];
+    const section = (s, i) => `<section id="section-${i}"><h2>${s.title}</h2>${s.paragraphs.map(p => `<p>${escape(p)}</p>`).join('')}</section>`;
+    const records = [b.research, ...b.dependencies.filter((a) => a.contract === 'n8r.research/0.1')];
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="n8r-presentation" content="1">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
+<title>${escape(b.surface.title)}</title>
+<style>
+:root{color-scheme:light;--ink:#172d46;--muted:#465c72;--blue:#2058a5;--wash:#edf4fc;--line:#c8d6e6;--paper:#fff}
+*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:18px/1.65 'Avenir Next',Avenir,'Segoe UI',sans-serif}main{max-width:1120px;margin:auto;padding:48px 40px 72px}header{max-width:880px;margin-bottom:40px}h1{font-size:clamp(2rem,5vw,3.5rem);line-height:1.13;letter-spacing:-.035em;margin:16px 0 24px}h2{font-size:1.5rem;line-height:1.3;margin:0 0 20px}h3{font-size:1.1rem}p{max-width:72ch;margin:0 0 18px;overflow-wrap:anywhere}.meta,.scope,footer{color:var(--muted);font-size:.9rem}.lead{background:var(--wash);border-left:5px solid var(--blue);padding:24px 28px;margin:28px 0}.lead p{font-size:1.25rem;line-height:1.5}.lead p:last-child{margin-bottom:0}.layout{display:grid;grid-template-columns:190px minmax(0,1fr);gap:48px}nav{align-self:start;position:sticky;top:24px;font-size:.9rem}nav a{display:block;padding:7px 0}a{color:var(--blue);text-underline-offset:4px}a:focus-visible,summary:focus-visible{outline:3px solid var(--blue);outline-offset:4px}section{padding:0 0 28px;margin-bottom:32px;border-bottom:1px solid var(--line)}details{padding:20px 0;border-top:1px solid var(--line)}summary{cursor:pointer;font-weight:600}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:13px/1.5 ui-monospace,monospace;background:#f3f6fa;padding:20px;max-height:36rem;overflow:auto}.source{margin:24px 0}footer{margin-top:40px} @media(max-width:720px){main{padding:28px 20px}.layout{display:block}nav{position:static;margin-bottom:32px;display:flex;flex-wrap:wrap;gap:4px 18px}.lead{padding:20px}h1{letter-spacing:-.02em}}@media print{main{padding:0}nav{display:none}.layout{display:block}details{break-inside:avoid}a{color:inherit}}
+</style>
+</head><body><main>
+<header><p class="meta">${b.surface.kind === 'bound' ? 'Configured system' : 'Product capability'} · Revision ${escape(b.surface.revision.id)}</p><h1>${escape(b.surface.title)}</h1><div class="lead">${lead.paragraphs.map(p => `<p>${escape(p)}</p>`).join('')}</div><p class="scope">${escape(b.surface.scope)}</p></header>
+<div class="layout"><nav aria-label="Report sections">${sections.slice(1).map((s, i) => `<a href="#section-${i + 1}">${s.title}</a>`).join('')}<a href="#sources">Source coverage</a></nav><article>
+${sections.slice(1).map((s, i) => section(s, i + 1)).join('\n')}
+<section id="sources"><h2>Source coverage</h2>${records.map(r => `<details><summary>${escape(r.title)} — ${escape(r.revision.id)}${r.id === b.research.id && r.revision.id === b.research.revision.id ? ' (current)' : ' (pinned evidence)'}</summary>${r.sources.map(s => `<div class="source"><h3>${escape(s.location)}</h3><p>Source revision ${escape(s.version)}. Inspected ${escape(s.inspectedAt)}.</p>${s.coverage.map(c => `<p>${escape(c.path)} — ${escape(c.status)}. ${escape(c.note)}</p>`).join('')}</div>`).join('') || '<p>No sources recorded.</p>'}</details>`).join('')}</section>
+<details><summary>Technical record and exact evidence</summary><p>The complete checked data is retained below. IDs and hashes identify evidence; they do not establish runtime behavior.</p><pre>${escape(JSON.stringify(b, null, 2))}</pre></details>
+<footer><p><a href="brief.md">Read the brief</a> · <a href="surface.json">Surface JSON</a> · <a href="dependencies.json">Pinned evidence JSON</a></p><p>Presentation 1. Visible edits require review; they are never silently incorporated into the checked data.</p></footer>
+</article></div>
+<script type="application/json" id="n8r-record">${embedded(b.research)}</script>
+<script type="application/json" id="n8r-context">${embedded({ surface: b.surface, dependencies: b.dependencies })}</script>
+</main></body></html>
+`;
+    checkSize(html);
+    return html;
+}

package/dist/skill-surface-cli.d.ts

@@ -0,0 +1 @@
+export declare function main(args: string[]): void;

package/dist/skill-surface-cli.js

@@ -0,0 +1,37 @@
+/** Standalone installed-skill entry point; separate from the product CLI. */
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { checkSurfaceBom } from './surface-bom.js';
+import { readJson, readSurface, saveSurface, byteDigest, readBytes } from './skill-surface-store.js';
+export function main(args) {
+    const [op, file, dest, previous] = args;
+    if (op === 'help' && args.length === 1) {
+        console.log('Surface helper: check BOM.json | read BOM.json_OR_DIRECTORY | save BOM.json NEW_DIRECTORY [PREVIOUS_BOM_OR_DIRECTORY] | reconcile BOM.json NEW_DIRECTORY PREVIOUS_DIRECTORY. CycloneDX 1.7 Surface profile 1. New saves have one BOM authority and generated brief, journal and HTML map. Reconcile only reviewed view edits; it requires a reconciliation explanation in the BOM. Offline; Node 22/24/26; no product CLI or runtime install.');
+        return;
+    }
+    if (op === 'check' && args.length === 2) {
+        const s = checkSurfaceBom(readJson(file));
+        console.log(JSON.stringify({ status: 'checked', relationships: s.relationships.length, entries: s.entries.length }));
+        return;
+    }
+    if (op === 'read' && args.length === 2) {
+        const s = readSurface(file);
+        console.log(JSON.stringify({ status: 'checked', ...s }, null, 2));
+        return;
+    }
+    if ((op === 'save' && (args.length === 3 || args.length === 4)) || (op === 'reconcile' && args.length === 4)) {
+        const s = saveSurface(readJson(file), dest, previous, op === 'reconcile');
+        console.log(JSON.stringify({ status: 'saved-and-read-back', serialNumber: s.bom.serialNumber, version: s.bom.version, bomDigest: byteDigest(readBytes(resolve(dest, 'surface.cdx.json'))), files: ['surface.html', 'brief.md', 'investigation.md', 'surface.cdx.json'] }));
+        return;
+    }
+    throw Error('Arguments refused; run help.');
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    try {
+        main(process.argv.slice(2));
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : 'Surface operation failed; no success claimed.');
+        process.exitCode = 1;
+    }
+}

package/dist/skill-surface-store.d.ts

@@ -0,0 +1,7 @@
+import { type Surface } from './surface-bom.js';
+export declare const byteDigest: (bytes: string | Buffer) => string;
+export declare function safeParents(directory: string): void;
+export declare function readBytes(file: string): NonSharedBuffer;
+export declare const readJson: (file: string) => unknown;
+export declare function readSurface(file: string): Surface;
+export declare function saveSurface(input: unknown, destination: string, previous?: string, reconcile?: boolean): Surface;

package/dist/skill-surface-store.js

@@ -0,0 +1,126 @@
+/** Immutable BOM revisions, with disposable views and explicit edit reconciliation. */
+import fs from 'node:fs';
+import { resolve, dirname, join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import { canonical } from './portable.js';
+import { decodeJsonValue } from './codec.js';
+import { checkSurfaceBom, prefix } from './surface-bom.js';
+import { renderSurface } from './surface-view.js';
+export const byteDigest = (bytes) => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
+const refuse = (reason) => { throw Error(`Surface save/read refused: ${reason}. No input values shown.`); };
+export function safeParents(directory) {
+    for (let p = resolve(directory);; p = dirname(p)) {
+        try {
+            const s = fs.lstatSync(p);
+            if (!s.isDirectory() || s.isSymbolicLink())
+                refuse('unsafe directory');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (p === dirname(p))
+            break;
+    }
+}
+export function readBytes(file) { safeParents(dirname(file)); const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW); try {
+    const s = fs.fstatSync(fd);
+    if (!s.isFile() || s.size > 8 * 1024 * 1024)
+        refuse('file type or size');
+    return fs.readFileSync(fd);
+}
+finally {
+    fs.closeSync(fd);
+} }
+export const readJson = (file) => decodeJsonValue(new TextDecoder('utf8', { fatal: true }).decode(readBytes(file)));
+const prop = (s, key) => s.bom.properties.find((p) => p.name === prefix + key)?.value;
+function location(file) { safeParents(dirname(file)); return fs.lstatSync(file).isDirectory() ? join(file, 'surface.cdx.json') : file; }
+function savedDirectory(file) {
+    const p = resolve(file);
+    if (fs.lstatSync(p).isDirectory())
+        return p;
+    if (basename(p) === 'surface.cdx.json' && fs.existsSync(join(dirname(p), 'manifest.json')))
+        return dirname(p);
+    return undefined;
+}
+export function readSurface(file) { const directory = savedDirectory(file); if (directory)
+    checkViews(directory, false); return checkSurfaceBom(readJson(location(resolve(file)))); }
+function checkViews(directory, reconcile) {
+    const manifest = readJson(join(directory, 'manifest.json'));
+    if (manifest.profile !== 'n8r.surface-save/1' || Object.keys(manifest.files ?? {}).sort().join(',') !== 'brief.md,investigation.md,surface.cdx.json,surface.html')
+        refuse('manifest');
+    for (const [name, hash] of Object.entries(manifest.files)) {
+        const changed = byteDigest(readBytes(join(directory, name))) !== hash;
+        if (changed && (name === 'surface.cdx.json' || !reconcile))
+            refuse(name === 'surface.cdx.json' ? 'changed predecessor BOM' : 'edited generated view; reconcile proposals into a successor explicitly');
+    }
+}
+export function saveSurface(input, destination, previous, reconcile = false) {
+    const s = checkSurfaceBom(input);
+    destination = resolve(destination);
+    safeParents(dirname(destination));
+    let prevFile, previousBytes;
+    if (previous) {
+        const prior = resolve(previous);
+        prevFile = location(prior);
+        previousBytes = readBytes(prevFile);
+        const old = checkSurfaceBom(decodeJsonValue(previousBytes.toString('utf8')));
+        const saved = savedDirectory(prior);
+        if (saved)
+            checkViews(saved, reconcile);
+        if (s.bom.serialNumber !== old.bom.serialNumber || s.bom.version !== old.bom.version + 1 || prop(s, 'predecessor-digest') !== byteDigest(previousBytes))
+            refuse('revision identity/digest');
+        const link = `urn:cdx:${old.bom.serialNumber.slice(9)}/${old.bom.version}`;
+        if (!s.bom.externalReferences?.some((r) => r.type === 'bom' && r.url === link))
+            refuse('versioned predecessor BOM-Link');
+        for (const n of [...(old.bom.components ?? []), ...(old.bom.services ?? [])])
+            if (![...(s.bom.components ?? []), ...(s.bom.services ?? [])].some(x => x['bom-ref'] === n['bom-ref']))
+                refuse('lost node identity');
+        for (const e of old.relationships) {
+            const n = s.relationships.find(x => x.id === e.id);
+            if (!n || n.from !== e.from || n.to !== e.to || n.kind !== e.kind)
+                refuse('lost or changed relationship identity');
+            for (const o of e.observations)
+                if (!n.observations.some(x => canonical(x) === canonical(o)))
+                    refuse('lost historical observation');
+        }
+        for (const e of old.entries)
+            if (!s.entries.some(x => x.id === e.id))
+                refuse('lost investigation entry');
+        for (const a of old.bom.annotations ?? [])
+            if (!s.bom.annotations?.some((n) => canonical(n) === canonical(a)))
+                refuse('rewritten historical evidence');
+        for (const [i, r] of (old.bom.externalReferences ?? []).entries())
+            if (canonical(s.bom.externalReferences?.[i]) !== canonical(r))
+                refuse('changed source reference');
+        for (const e of old.evidence)
+            if (!s.evidence.some(n => canonical(n) === canonical(e)))
+                refuse('changed evidence applicability');
+        for (const e of old.entries.filter(e => e.kind === 'decision')) {
+            const next = s.entries.find(x => x.id === e.id);
+            if (!next || canonical({ ...next, status: e.status }) !== canonical(e))
+                refuse('lost or rewritten decision');
+            if (next.status !== e.status && (next.status !== 'superseded' || !s.entries.some(x => x.supersedes === e.id && x.kind === 'decision')))
+                refuse('decision supersession');
+            for (const id of e.evidence) {
+                const a = old.bom.annotations.find((a) => a['bom-ref'] === id);
+                if (!s.bom.annotations.some((b) => canonical(a) === canonical(b)))
+                    refuse('rewritten decision provenance');
+            }
+        }
+    }
+    else if (s.bom.version !== 1 || prop(s, 'predecessor-digest') !== undefined)
+        refuse('predecessor required');
+    if (reconcile && (!previous || !prop(s, 'reconciliation')))
+        refuse('reconciliation explanation required');
+    const files = { 'surface.cdx.json': JSON.stringify(s.bom, null, 2) + '\n', ...renderSurface(s) };
+    const manifest = JSON.stringify({ profile: 'n8r.surface-save/1', files: Object.fromEntries(Object.entries(files).map(([n, v]) => [n, byteDigest(v)])) }, null, 2) + '\n';
+    fs.mkdirSync(destination, { mode: 0o700 });
+    for (const [name, bytes] of Object.entries({ ...files, 'manifest.json': manifest }))
+        fs.writeFileSync(join(destination, name), bytes, { flag: 'wx', mode: 0o600 });
+    checkViews(destination, false);
+    const saved = readSurface(destination);
+    if (prevFile && !readBytes(prevFile).equals(previousBytes))
+        refuse('predecessor changed during save');
+    return saved;
+}

package/dist/source-tools.d.ts

@@ -0,0 +1,102 @@
+type Entry = {
+    path: string;
+    kind: 'file' | 'directory';
+};
+type Omission = {
+    path: string;
+    reason: string;
+};
+/** Local read capability. Directory topology must remain stable during an operation. */
+export declare class SourceTools {
+    readonly root: string;
+    readonly file: string | undefined;
+    private identity;
+    constructor(source: string);
+    get selected(): string;
+    private checkRoot;
+    private path;
+    list(path?: string): {
+        entries: Entry[];
+        excluded: Omission[];
+        truncated: boolean;
+    };
+    private bytes;
+    read(path: string, startLine?: number, lineCount?: number): {
+        path: string;
+        digest: string;
+        inspectedAt: string;
+        startLine: number;
+        endLine: number;
+        totalLines: number;
+        text: string;
+        truncated: boolean;
+    };
+    search(query: string): {
+        query: string;
+        matches: {
+            path: string;
+            line: number;
+            text: string;
+            digest: string;
+        }[];
+        excluded: Omission[];
+        truncated: boolean;
+        filesInspected: number;
+        inspectedAt: string;
+    };
+    call(tool: string, args: unknown): unknown;
+}
+export declare const sourceToolSpecs: ({
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+            };
+            startLine?: undefined;
+            lineCount?: undefined;
+            query?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            path: {
+                type: string;
+            };
+            startLine: {
+                type: string;
+            };
+            lineCount: {
+                type: string;
+            };
+            query?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+} | {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            query: {
+                type: string;
+            };
+            path?: undefined;
+            startLine?: undefined;
+            lineCount?: undefined;
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+})[];
+export {};