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

package/dist/surface-instructions.js

@@ -0,0 +1,32 @@
+/** Content fields mirror the existing experimental contracts; host metadata is omitted. */
+export const legacySurfaceInstructions = `
+STRUCTURED SURFACE CAPABILITY (host adapter 0.1):
+When the user asks to create or update a Surface, call surface_draft with research and surface content objects. This stages a preview only. Never claim a save. Natural-language save requests explain /save surface. /save still saves Markdown. A later user turn invalidates the preview, so restage a revised pair after answering a correction. Retain stable component IDs from notes. If an old label is not namespaced, record the explicit old-to-new mapping in research.notes and show it to the human. Do not silently rename identities.
+
+Use these exact content fields (no contract, id, revision or records; the host assigns them):
+research: {title,scope,extensions,sources,findings,alternatives,decisions,questions,notes}.
+surface: {title,scope,extensions,kind:"definition",vocabularies,nodes,relationships,requirements,coverage,gaps}.
+All collections are arrays except extensions and entity attributes, which are objects. Empty arrays/objects are allowed. Nonempty text is required for text fields. IDs use a URI-style namespace such as urn:lumen:app. All timestamps use real UTC seconds, YYYY-MM-DDTHH:mm:ssZ, without fractions. Only safe integer JSON numbers are supported. Do not add undocumented fields.
+
+Source: {id,location,version,digest,inspectedAt,coverage:[{path,status,note}]}. location is a portable relative source path from an ACTUAL source_read/search or saved host evidence, never an absolute path. digest must be the exact SHA-256 from that tool or saved host evidence. Never invent a digest. status is inspected|missing|unreadable|excluded|truncated|unsupported. Record ranges and limits. On revision retain historical source objects exactly and add a new source ID for new bytes or inspection; never relabel old evidence as fresh.
+Finding: {id,subject,property,state,note,claims:[{value,evidence:[{source,locator}]}]}. subject is a component ID; evidence.source references sources[].id. state is known|unknown|omitted|redacted|absent|out-of-scope|conflicting. known/absent require one agreed sourced value; conflicting requires different sourced values; other states require empty claims. Every claim requires evidence. Keep human decisions separate from sourced claims.
+Alternative: {id,title,findings:[finding IDs],requirements:[text descriptions]}.
+Decision: {id,alternative,choice:"selected"|"rejected"|"deferred",reason,by,at}. One current decision per alternative. Use actual human choices, never infer selection from support. Preserve prior choices unless the human changes them. Record an explicit correction's reason and date; previous revisions retain prior choices.
+Question: {id,text,findings:[finding IDs]}. Note: {by,at,text}. Keep human prose, unresolved questions and recommended next investigations.
+Vocabulary: {id,version}; version is a token such as 0.1. Use an explicitly scoped provisional vocabulary, not a claim of universal compatibility.
+Node: {id,label,type:{vocabulary,term},attributes:{property:{state,note,value?}},basis:[{items:[finding/decision/alternative/question IDs]}],requirements:[requirement IDs]}.
+Relationship: same fields as a node EXCEPT no label, plus {from:node ID,to:node ID,claim:"declared"}. Keep endpoint identity for retained relationship IDs. Only selected composition belongs in relationships. A supported option is not automatically selected. Shared components, cycles and parallel edges are allowed.
+Fact state is known|unknown|omitted|redacted|absent|out-of-scope. Only known facts have a value; all other states omit value. Put conflicting values in research and unknown in the Surface with an explanatory note.
+Requirement: {id,kind:"secret"|"resource"|"configuration",description,state}. Never include credential values. coverage and gaps are arrays of nonempty strings. Surface basis contains only items; the host fills the exact research record/revision and digest.
+
+On pair reopening keep research and Surface identities via host bookkeeping. Retain all research sources, findings, alternatives, decisions, questions and component IDs. Keep historical claims and research notes exactly; append corrections and new evidence instead of removing history. Every node and relationship needs nonempty basis linking structured findings/decisions. Retained finding subjects/properties and node types cannot change; retain opaque extensions exactly. Removed selections remain rejected/deferred in research. Preserve prior unknowns unless evidence resolves them. Explain source unavailable/changed status and distinguish declared from reachable or exercised. On validation error, repair the staged content using feedback; do not discard evidence to make validation pass.
+`;
+export const surfaceInstructions = `
+STRUCTURED SURFACE HOST ADAPTER 0.3:
+For new research, use the bundled Capability/Bound contract and surface_draft with a COMPLETE bundle {research,surface,dependencies}. This tool validates and stages only; the user enters /save surface to save the preview as brief.md, research.html, surface.json, dependencies.json and manifest.json. /save still saves Markdown. A later conversational turn invalidates the preview.
+Use surface_digest with {artifact: COMPLETE_ARTIFACT} to get canonical SHA-256 for exact revision references. Never guess artifact or source digests. Source digests come from source_read/search. Use real UTC timestamps in seconds. All artifact envelopes include contract, id, revision, title, scope, extensions. Revision includes id, parent (null initially), createdAt, author and reason. The current UTC time is supplied by the host.
+Use the shapes below as schema examples ONLY: they are synthetic and are NOT evidence. Replace identities and findings with actual source evidence. Unknown details need explicit notes and empty claims. The host has no shell or filesystem staging tool. Use only surface_digest and surface_draft for structured work; do not attempt to invoke the standalone helper.
+Compute research digest first, then set surface.records to the exact research reference. Each basis is {record:research.id,revision:research.revision.id,items:[finding IDs]}. Bound dependencies include its pinned Capability and that Capability's exact research. For a successor retain research/surface identity and kind, use new revision IDs, exact parent references, unchanged prior decisions, stable component and relationship identities, and exact historical dependencies. Retain parent research in dependencies to explain changes. Do not discard contradictory evidence.
+On reopening a LEGACY n8r.surface/0.1 pair, continue that original format with the legacy content-only tool input described below; never silently migrate old files. For new work, always use n8r.surface/0.3. A saved Capability and a Bound description are distinct identities, not kind-changing successors.
+LEGACY INSTRUCTIONS (only for reopened definitions):
+` + legacySurfaceInstructions;

package/dist/surface-overview.d.ts

@@ -0,0 +1,15 @@
+/** Deterministic, offline overview. Layout hints never establish deployed boundaries. */
+import type { Surface } from './surface-bom.js';
+export declare const escapeHtml: (s: unknown) => string;
+export declare const fragmentId: (kind: string, id: string) => string;
+export declare const boundaryNames: {
+    internal: string;
+    external: string;
+    unknown: string;
+};
+export declare function nodeGroups(s: Surface): {
+    boundary: keyof typeof boundaryNames;
+    area: string;
+    nodes: any[];
+}[];
+export declare function renderOverview(s: Surface): string;

package/dist/surface-overview.js

@@ -0,0 +1,86 @@
+export const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+// No percent escapes in IDs: browsers decode fragment URLs before lookup.
+// Escape underscores too so literal and encoded identifiers cannot collide.
+export const fragmentId = (kind, id) => kind + '-' + Array.from(id).map(c => /[a-zA-Z0-9-]/.test(c) ? c : '_' + c.codePointAt(0).toString(16) + '_').join('');
+export const boundaryNames = { internal: 'Inside the application', external: 'External integrations', unknown: 'Unclassified' };
+export function nodeGroups(s) {
+    const groups = new Map();
+    for (const n of [...(s.bom.components ?? []), ...(s.bom.services ?? [])]) {
+        const p = s.presentation[n['bom-ref']], boundary = p?.boundary ?? 'unknown', area = p?.area ?? 'Placement not researched';
+        const key = JSON.stringify([boundary, area]);
+        if (!groups.has(key))
+            groups.set(key, { boundary, area, nodes: [] });
+        groups.get(key).nodes.push(n);
+    }
+    return [...groups.values()].sort((a, b) => Object.keys(boundaryNames).indexOf(a.boundary) - Object.keys(boundaryNames).indexOf(b.boundary));
+}
+function wrap(text) {
+    // Wrap long tokens too; preserve the full label in the accessible title.
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line && (line + ' ' + word).length > 30) {
+            lines.push(line);
+            line = '';
+        }
+        let rest = word;
+        while (rest.length > 30) {
+            lines.push(rest.slice(0, 30));
+            rest = rest.slice(30);
+        }
+        line += (line ? ' ' : '') + rest;
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+export function renderOverview(s) {
+    const h = escapeHtml, groups = nodeGroups(s);
+    if (!groups.length)
+        return '<p>No components recorded yet. Continue the source investigation.</p>';
+    const positions = new Map();
+    const columns = Object.keys(boundaryNames);
+    const heights = [65, 65, 65];
+    let labels = '';
+    const counts = new Map();
+    for (const e of s.relationships) {
+        const key = JSON.stringify([e.from, e.to].sort());
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const columnWidth = 370 + Math.max(0, ...counts.values()) * 12, canvasWidth = columnWidth * 3 + 10;
+    const lanes = new Map();
+    for (const g of groups) {
+        const col = columns.indexOf(g.boundary), x = 25 + col * columnWidth;
+        let y = heights[col];
+        const areaLines = wrap(g.area);
+        labels += `<text x="${x}" y="${y}" class="area-label">${areaLines.map((line, i) => `<tspan x="${x}" dy="${i ? 18 : 0}">${h(line)}</tspan>`).join('')}</text>`;
+        y += areaLines.length * 18 + 12;
+        for (const n of g.nodes) {
+            const lines = wrap(n.name), height = Math.max(54, lines.length * 18 + 24);
+            positions.set(n['bom-ref'], { x, y, height, n, lines });
+            y += height + 24;
+        }
+        heights[col] = y + 22;
+    }
+    const edges = s.relationships.map((e, i) => {
+        const a = positions.get(e.from), b = positions.get(e.to);
+        const ay = a.y + a.height / 2, by = b.y + b.height / 2;
+        const key = JSON.stringify([e.from, e.to].sort()), rank = lanes.get(key) ?? 0;
+        lanes.set(key, rank + 1);
+        let d;
+        if (e.from === e.to)
+            d = `M${a.x + 280} ${ay - 9} C${a.x + 330 + rank * 12} ${ay - 28} ${a.x + 330 + rank * 12} ${ay + 28} ${a.x + 280} ${ay + 9}`;
+        else if (a.x === b.x) {
+            const lane = a.x + 300 + rank * 12;
+            d = `M${a.x + 280} ${ay} C${lane} ${ay} ${lane} ${by} ${b.x + 280} ${by}`;
+        }
+        else {
+            const right = b.x > a.x, ax = a.x + (right ? 280 : 0), bx = b.x + (right ? 0 : 280), bend = (ax + bx) / 2;
+            const offset = (rank + 1) * 12;
+            d = `M${ax} ${ay} C${bend + offset} ${ay + offset} ${bend + offset} ${by + offset} ${bx} ${by}`;
+        }
+        return `<a href="#edge-${i}"><path data-edge="${h(e.id)}" d="${d}" class="${e.selection === 'selected' ? 'selected' : 'possible'}" marker-end="url(#arrow)"><title>${h(a.n.name + ' → ' + b.n.name + ': ' + e.purpose + '; support ' + e.support + '; selection ' + e.selection)}</title></path></a>`;
+    }).join('');
+    const nodes = [...positions].map(([id, p]) => `<a href="#${fragmentId('node', id)}"><g data-node="${h(id)}"><title>${h(p.n.name)}</title><rect x="${p.x}" y="${p.y}" width="280" height="${p.height}" rx="6"/><text x="${p.x + 12}" y="${p.y + 24}">${p.lines.map((line, i) => `<tspan x="${p.x + 12}" dy="${i ? 18 : 0}">${h(line)}</tspan>`).join('')}</text></g></a>`).join('');
+    return `<div class="map"><svg role="img" aria-label="Connected application overview; full relationships follow" viewBox="0 0 ${canvasWidth} ${Math.max(...heights) + 20}"><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3 z" fill="#64746d"/></marker></defs>${columns.map((c, i) => `<text x="${25 + i * columnWidth}" y="30" class="boundary-label">${h(boundaryNames[c])}</text>`).join('')}${labels}${edges}${nodes}</svg></div>`;
+}

package/dist/surface-store.d.ts

@@ -0,0 +1,34 @@
+import { type SurfaceDraft } from './surface-draft.js';
+import { type Note, type NoteContext } from './notes.js';
+type Manifest = {
+    version: 1 | 2;
+    files: Record<string, string>;
+    provenance?: NoteContext;
+    note?: {
+        file: string;
+        digest: string;
+    };
+    predecessor?: {
+        directory: string;
+        manifestDigest: string;
+    } | string | null;
+};
+export type SavedSurfacePair = SurfaceDraft & {
+    directory: string;
+    researchPath: string;
+    surfacePath: string;
+    manifest: Manifest;
+    briefPath?: string;
+    bytes: Record<string, Buffer>;
+};
+export declare function readSurfacePair(path: string): SavedSurfacePair;
+export declare class SurfaceStore {
+    private note?;
+    readonly directory: string;
+    previous: SavedSurfacePair | undefined;
+    private stamps;
+    constructor(vault: string, source: string, previous?: SavedSurfacePair, note?: Note | undefined);
+    private unchanged;
+    save(draft: SurfaceDraft, provenance: NoteContext): SavedSurfacePair;
+}
+export {};

package/dist/surface-store.js

@@ -0,0 +1,213 @@
+import fs from 'node:fs';
+import { readBundle, saveBundle } from './skill-artifacts.js';
+import { basename, dirname, join, resolve, relative, sep } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { decode, encode } from './codec.js';
+import { readResearchHtml, renderResearchHtml } from './html.js';
+import { verifyReferences } from './validate.js';
+import { canonical } from './portable.js';
+import { verifyPairSuccessor, isBundle } from './surface-draft.js';
+import {} from './notes.js';
+import { InspectionError, readBytes } from './settings.js';
+const LIMIT = 8 * 1024 * 1024;
+const HASH = /^sha256:[a-f0-9]{64}$/;
+const MEMBERS = ['research.html', 'surface.json', 'manifest.json'];
+const hash = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+function fail(message) { throw new InspectionError(message); }
+function safeName(value) { return typeof value === 'string' && !!value && value !== '.' && value !== '..' && !/[\\/\x00-\x1f]/.test(value); }
+function checkProvenance(p) {
+    if (!p || typeof p.model !== 'string' || typeof p.researcher?.version !== 'string' || !HASH.test(p.researcher?.digest)
+        || !Array.isArray(p.evidence) || p.evidence.length > 1000 || p.evidence.some((e) => !e || typeof e.path !== 'string' || !HASH.test(e.digest)
+        || typeof e.inspectedAt !== 'string' || !Number.isSafeInteger(e.startLine) || !Number.isSafeInteger(e.endLine)))
+        fail('Invalid pair provenance');
+}
+function manifest(value) {
+    canonical(value);
+    if (!value || value.version !== 1 || !value.files || Object.keys(value.files).sort().join(',') !== 'research.html,surface.json'
+        || !HASH.test(value.files['research.html']) || !HASH.test(value.files['surface.json'])
+        || Object.keys(value).some(k => !['version', 'files', 'provenance', 'note', 'predecessor'].includes(k))
+        || (value.note && (!safeName(value.note.file) || !HASH.test(value.note.digest)))
+        || (value.predecessor && (!safeName(value.predecessor.directory) || !HASH.test(value.predecessor.manifestDigest))))
+        fail('Invalid Surface pair manifest');
+    checkProvenance(value.provenance);
+}
+/** No symlink ancestry; stable directory topology is required during synchronous operations. */
+function checkDirectories(directory, stamps) {
+    const paths = [];
+    for (let p = directory;; p = dirname(p)) {
+        paths.unshift(p);
+        if (dirname(p) === p)
+            break;
+    }
+    for (const p of paths) {
+        let stat;
+        try {
+            stat = fs.lstatSync(p);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT' && !stamps?.has(p))
+                continue;
+            throw e;
+        }
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            fail('Surface directory is occupied or a symbolic link');
+        const stamp = `${stat.dev}:${stat.ino}`, old = stamps?.get(p);
+        if (old && old !== stamp)
+            fail('Surface directory changed; reopen before saving');
+        stamps?.set(p, stamp);
+    }
+}
+function read(path, limit = LIMIT) {
+    if (fs.lstatSync(path).isSymbolicLink())
+        fail('Pair member cannot be a symbolic link');
+    return readBytes(path, limit);
+}
+function utf8(bytes) { try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
+catch {
+    fail('Pair is not UTF-8');
+} }
+export function readSurfacePair(path) {
+    path = resolve(path);
+    if (!['research.html', 'surface.json'].includes(basename(path)))
+        fail('Select research.html or surface.json from a saved pair');
+    const directory = dirname(path);
+    checkDirectories(directory);
+    const bytes = {};
+    bytes['manifest.json'] = read(join(directory, 'manifest.json'), 512 * 1024);
+    let m;
+    try {
+        m = JSON.parse(utf8(bytes['manifest.json']));
+    }
+    catch {
+        fail('Invalid pair manifest JSON');
+    }
+    if (m?.files?.['dependencies.json']) {
+        const bundle = readBundle(directory);
+        for (const name of Object.keys(m.files))
+            bytes[name] = read(join(directory, name));
+        // Standalone skill manifests have no runner receipt. Re-read recorded sources
+        // on reopening; they remain historical evidence, not a fresh tool result.
+        if (m.provenance)
+            checkProvenance(m.provenance);
+        return { ...bundle, directory, researchPath: join(directory, 'research.html'), surfacePath: join(directory, 'surface.json'), briefPath: join(directory, 'brief.md'), manifest: m, bytes };
+    }
+    manifest(m);
+    for (const name of ['research.html', 'surface.json']) {
+        bytes[name] = read(join(directory, name));
+        if (hash(bytes[name]) !== m.files[name])
+            fail('Pair bytes conflict with manifest hash; preserve edits and reopen an accepted revision');
+    }
+    const research = readResearchHtml(utf8(bytes['research.html'])), surface = decode(utf8(bytes['surface.json']), 'json');
+    if (surface.contract !== 'n8r.surface/0.1')
+        fail('Expected Surface definition');
+    if (surface.records.length !== 1 || surface.records[0].id !== research.id)
+        fail('This host reopens one linked research record per pair');
+    verifyReferences(surface, [research]);
+    return { research, surface, directory, researchPath: join(directory, 'research.html'), surfacePath: join(directory, 'surface.json'), manifest: m, bytes };
+}
+export class SurfaceStore {
+    note;
+    directory;
+    previous;
+    stamps = new Map();
+    constructor(vault, source, previous, note) {
+        this.note = note;
+        source = fs.realpathSync(source);
+        const slug = basename(source).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80) || 'source';
+        this.directory = previous ? dirname(previous.directory) : join(fs.realpathSync(vault), 'surfaces', slug);
+        const rel = relative(source, this.directory);
+        if (fs.statSync(source).isDirectory() && (!rel || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep))))
+            fail('Surface cannot be saved inside selected source');
+        this.previous = previous;
+        checkDirectories(this.directory, this.stamps);
+    }
+    unchanged() {
+        checkDirectories(this.directory, this.stamps);
+        if (this.note && !read(this.note.path, 256 * 1024).equals(Buffer.from(this.note.text)))
+            fail('Original note changed; reopen before saving');
+        if (this.previous)
+            for (const name of Object.keys(this.previous.bytes))
+                if (!read(join(this.previous.directory, name)).equals(this.previous.bytes[name]))
+                    fail('Predecessor changed; reopen before saving');
+    }
+    save(draft, provenance) {
+        this.unchanged();
+        checkProvenance(provenance);
+        if (isBundle(draft)) {
+            if (this.previous)
+                verifyPairSuccessor(this.previous, draft);
+            fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+            checkDirectories(this.directory, this.stamps);
+            const names = fs.readdirSync(this.directory);
+            if (names.length > 10000)
+                fail('Too many Surface revisions');
+            const max = names.reduce((n, name) => Math.max(n, Number(/^surface-(\d+)$/.exec(name)?.[1] ?? 0)), 0);
+            if (!Number.isSafeInteger(max + 1))
+                fail('Surface numbering limit reached');
+            const target = join(this.directory, `surface-${String(max + 1).padStart(3, '0')}`);
+            saveBundle(draft, target, this.previous?.directory);
+            const manifestPath = join(target, 'manifest.json');
+            const receipt = JSON.parse(utf8(read(manifestPath)));
+            fs.writeFileSync(manifestPath, JSON.stringify({ ...receipt, provenance, ...(this.note ? { note: { file: basename(this.note.path), digest: this.note.digest } } : this.previous?.manifest.note ? { note: this.previous.manifest.note } : {}) }, null, 2) + '\n', { mode: 0o600 });
+            const saved = readSurfacePair(join(target, 'surface.json'));
+            this.unchanged();
+            this.previous = saved;
+            return saved;
+        }
+        verifyReferences(draft.surface, [draft.research]);
+        if (this.previous)
+            verifyPairSuccessor(this.previous, draft);
+        else if (draft.research.revision.parent || draft.surface.revision.parent)
+            fail('Initial pair cannot have an unavailable predecessor');
+        const html = renderResearchHtml(draft.research), json = encode(draft.surface, 'json');
+        if (Buffer.byteLength(html) > LIMIT)
+            fail('Research HTML exceeds host size limit');
+        const m = { version: 1, files: { 'research.html': hash(html), 'surface.json': hash(json) }, provenance,
+            ...(this.note ? { note: { file: basename(this.note.path), digest: this.note.digest } } : this.previous?.manifest.note ? { note: this.previous.manifest.note } : {}),
+            ...(this.previous ? { predecessor: { directory: basename(this.previous.directory), manifestDigest: hash(this.previous.bytes['manifest.json']) } } : {}) };
+        manifest(m);
+        const data = { 'research.html': html, 'surface.json': json, 'manifest.json': JSON.stringify(m, null, 2) + '\n' };
+        if (Buffer.byteLength(data['manifest.json']) > 512 * 1024)
+            fail('Pair manifest exceeds size limit');
+        fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        checkDirectories(this.directory, this.stamps);
+        const names = fs.readdirSync(this.directory);
+        if (names.length > 10000)
+            fail('Too many Surface revisions');
+        const max = names.reduce((n, name) => Math.max(n, Number(/^surface-(\d+)$/.exec(name)?.[1] ?? 0)), 0);
+        if (!Number.isSafeInteger(max + 1))
+            fail('Surface numbering limit reached');
+        const target = join(this.directory, `surface-${String(max + 1).padStart(3, '0')}`);
+        const temporary = fs.mkdtempSync(join(this.directory, '.surface-'));
+        try {
+            for (const name of MEMBERS) {
+                const fd = fs.openSync(join(temporary, name), 'wx', 0o600);
+                try {
+                    fs.writeFileSync(fd, data[name]);
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+            }
+            readSurfacePair(join(temporary, 'surface.json'));
+            this.unchanged();
+            // Under the stable-topology assumption, never replace any occupied destination.
+            if (fs.existsSync(target))
+                fail('Surface destination occupied');
+            fs.renameSync(temporary, target);
+            const saved = readSurfacePair(join(target, 'surface.json'));
+            for (const name of MEMBERS)
+                if (!saved.bytes[name].equals(Buffer.from(data[name])))
+                    fail('Saved pair readback differs; inspect output before retrying');
+            this.previous = saved;
+            return saved;
+        }
+        finally {
+            if (fs.existsSync(temporary))
+                fs.rmSync(temporary, { recursive: true });
+        }
+    }
+}

package/dist/surface-view.d.ts

@@ -0,0 +1,3 @@
+/** Views are generated from the BOM and never become a second authority. */
+import type { Surface } from './surface-bom.js';
+export declare function renderSurface(s: Surface): Record<'brief.md' | 'investigation.md' | 'surface.html', string>;

package/dist/surface-view.js

@@ -0,0 +1,50 @@
+import { escapeHtml as html, nodeGroups, boundaryNames, renderOverview, fragmentId } from './surface-overview.js';
+const md = (s) => String(s).replace(/[\r\n]/g, ' ').replace(/[\\`*_{}\[\]<>|]/g, c => '\\' + c);
+export function renderSurface(s) {
+    const nodes = [...(s.bom.components ?? []), ...(s.bom.services ?? [])];
+    const name = (id) => nodes.find(n => n['bom-ref'] === id)?.name ?? id;
+    const focus = nodes.find(n => s.presentation[n['bom-ref']]?.focus);
+    const title = focus ? `${focus.name} — initial security overview` : 'Surface overview';
+    const intro = focus?.description ?? s.objective;
+    const groups = nodeGroups(s);
+    const replaced = new Set(s.entries.flatMap(e => e.supersedes ? [e.supersedes] : []));
+    const current = s.entries.filter(e => !replaced.has(e.id) && e.status !== 'superseded');
+    const findings = current.filter(e => e.kind === 'finding' && e.status === 'done' && e.evidence.length > 0);
+    const next = current.filter(e => ['next', 'question'].includes(e.kind) && ['open', 'active'].includes(e.status)).sort((a, b) => Number(b.status === 'active') - Number(a.status === 'active'));
+    const briefFindings = findings.slice(-5).reverse();
+    const label = (e) => `${e.selection === 'selected' ? 'Selected' : e.support === 'supported' ? 'Possible' : 'Support ' + e.support} · ${e.kind}${e.observations.length ? ' · observed ' + e.observations.map(o => o.at).join(', ') : ''}`;
+    const mechanics = `BOM revision ${s.bom.version}. Generated view; propose edits for reconciliation into a successor. The BOM remains authoritative.`;
+    const scopeNote = 'Supported paths describe options. Selection can reflect human intent or configuration; inspect its evidence. Dated observations stand separately. Missing information does not establish absence.';
+    const continuation = 'Continue with the available evidence: trace a source-level path, describe an intended setup, or inspect an identified deployment. Source-only research needs no running services. Choose another direction or stop at any time.';
+    const interchange = 'This architecture and research record is not a comprehensive dependency SBOM. Standard dependencies contain only selected dependency relationships; profile properties retain other paths and evidence. Generic consumers may omit that detail.';
+    const evidence = (ids) => ids.map(id => `<a href="#${fragmentId('ev', id)}">${html(id)}</a>`).join(', ') || 'No evidence yet';
+    const evidenceMd = (ids) => ids.map(id => `[${md(id)}](surface.html#${fragmentId('ev', id)})`).join(', ');
+    const basis = (id) => { const b = s.evidence.find(e => e.id === id)?.basis; return b === 'user' ? 'user intent' : b ?? 'unknown'; };
+    const placementMd = (id) => { const p = s.presentation[id]; return p ? ' Placement basis: ' + (p.evidence.map(e => `${md(basis(e))} — ${evidenceMd([e])}`).join('; ') || 'Not recorded') : ''; };
+    const list = (xs, empty) => xs.length ? xs.map(x => '- ' + md(x)).join('\n') : '- ' + empty;
+    const more = (count, section) => count > 0 ? `\n\n${count} additional items in [the full ${section}](surface.html#${section}).` : '';
+    const briefList = (xs, empty) => list(xs.slice(0, 7), empty) + more(xs.length - 7, 'coverage');
+    let remaining = 12;
+    const grouped = groups.flatMap(g => {
+        const shown = g.nodes.slice(0, remaining);
+        remaining -= shown.length;
+        return shown.length ? [`### ${boundaryNames[g.boundary]} · ${md(g.area)}\n\n` + shown.map(n => `- **${md(n.name)}** · ${md(n.type ?? 'service')} · ${md(n['bom-ref'])}${placementMd(n['bom-ref'])}${s.relationships.some(e => e.from === n['bom-ref'] || e.to === n['bom-ref']) ? '' : ' · Connections unknown.'}`).join('\n')] : [];
+    }).join('\n\n') + more(nodes.length - 12, 'inventory');
+    const brief = `# ${md(title)}\n\n${md(intro)}\n\nScope: ${md(s.scope)}\n\n## Major areas and integrations\n\n${grouped || 'No components recorded yet.'}\n\n${scopeNote}\n\nOpen the [connected overview and relationship details](surface.html#overview). Grouping records placement, not verified deployed trust boundaries. Inspect its evidence basis: source, user intent, configuration or dated observation.\n\n## Security observations and investigation leads\n\n${findings.length ? briefFindings.map(e => `- **${md(e.title)}** — ${md(e.text)} Why it matters: ${md(e.reason)} Evidence: ${evidenceMd(e.evidence)}.`).join('\n') : 'No evidence-backed findings recorded. Continue research; this is not an assurance conclusion.'}${more(findings.length - 5, 'findings')}\n\n${findings.length > 5 ? 'Showing the five most recently recorded current findings, not a severity ranking.\n\n' : ''}## Coverage and gaps\n\nResearched:\n\n${briefList(s.coverage, 'No coverage recorded.')}\n\nUnknown or not researched:\n\n${briefList(s.gaps, 'No gaps recorded; completeness is not established.')}\n\n## Next step\n\n${next.slice(0, 1).map(e => `- **${md(e.title)}** — ${md(e.text)} Why: ${md(e.reason)} Access: ${md(e.access)}`).join('\n') || 'No current action recorded.'}${more(next.length - 1, 'next')}\n\n${continuation}\n\n## Evidence and saved detail\n\nOpen [the map and evidence](surface.html), [investigation journal](investigation.md), or [saved Surface](surface.cdx.json).\n\n${interchange}\n\n${mechanics}\n`;
+    const journal = `# Investigation journal\n\n${mechanics}\n\n## Objective and scope\n\n${md(s.objective)}\n\n${md(s.scope)}\n\n## Available evidence and coverage\n\n${list(s.coverage, 'No coverage recorded.')}\n\n## Journey\n\n` + s.entries.map(e => `### ${md(e.title)}\n\n${md(e.kind)} · ${md(e.status)} · ${md(e.at)} · ID: ${md(e.id)}\n\n${md(e.text)}\n\nWhy: ${md(e.reason)}\n\nAccess needed: ${md(e.access)}\n\nEvidence: ${evidenceMd(e.evidence) || 'None yet'}${e.parent ? '\n\nBranch of: ' + md(e.parent) : ''}${e.supersedes ? '\n\nSupersedes: ' + md(e.supersedes) : ''}\n`).join('\n') + `\n## Open gaps\n\n${list(s.gaps, 'No gaps recorded; completeness is not established.')}\n\nChoose a next step, inspect the whole map, redirect or stop.\n`;
+    const details = s.relationships.map((e, i) => `<details id="edge-${i}"><summary>${html(name(e.from))} → ${html(name(e.to))} <small>${html(label(e))}</small></summary><p>${html(e.purpose)}</p><p>Support: ${html(e.support)}. Selection: ${html(e.selection)}. Optionality: ${html(e.optionality)}. ${html(e.group ? 'Alternative group: ' + e.group : '')}</p><p>${html(e.note)}</p><p>Integration: ${html(e.mechanism)}. Configuration locations: ${html(e.configuration.join('; ') || 'Unknown')}</p><p>Conditions: ${html(e.conditions.join('; ') || 'None recorded')}</p><p>Support evidence: ${evidence(e.evidence)}. Selection evidence: ${evidence(e.selectionEvidence)}</p>${e.observations.map(o => `<p>Observed ${html(o.at)}: ${html(o.note)} — ${evidence(o.evidence)}</p>`).join('')}</details>`).join('');
+    const ev = (s.bom.annotations ?? []).map((a) => `<article id="${fragmentId('ev', a['bom-ref'])}"><h3>${html(a['bom-ref'])}</h3><p>${html(a.text)}</p><p>${html(a.timestamp)} · ${html(a.annotator.individual?.name ?? a.annotator.organization?.name ?? 'Recorded annotator')}</p>${s.evidence.filter(e => e.id === a['bom-ref']).map(e => `<p>${html(e.basis)} — ${html(e.applicability)}</p>${e.sources.map(ref => { const source = s.bom.externalReferences[ref.index]; return `<p>Source: ${html(source.url)} · ${html(ref.locator)}<br>${html(source.comment ?? '')}<br>${html((source.hashes ?? []).map((h) => h.alg + ': ' + h.content).join('; '))}</p>`; }).join('')}`).join('')}</article>`).join('');
+    const ul = (items) => '<ul>' + items.map(x => `<li>${html(x)}</li>`).join('') + '</ul>';
+    const journey = (entries) => entries.map(e => `<article><p class="tag">${html(e.kind)} · ${html(e.status)}</p><h3>${html(e.title)}</h3><p>${html(e.text)}</p><p>Why: ${html(e.reason)}<br>Access needed: ${html(e.access)}</p><p>${html(e.at)} · ${html(e.id)}${e.parent ? ' · Branch of ' + html(e.parent) : ''}${e.supersedes ? ' · Supersedes ' + html(e.supersedes) : ''}</p><p>${evidence(e.evidence)}</p></article>`).join('');
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src 'none'; base-uri 'none'; form-action 'none'"><title>${html(title)}</title><style>
+body{margin:0;background:#f5f3ec;color:#18362e;font:17px/1.6 system-ui,sans-serif}main{max-width:1200px;margin:auto;padding:40px 28px}header{border-bottom:2px solid #18362e;padding-bottom:25px}h1{font:42px/1.1 Georgia,serif;max-width:1000px}h2{font:28px Georgia,serif;margin-top:48px}a{color:#14634b}nav{display:flex;gap:22px;flex-wrap:wrap}small,.muted{color:#58675f}svg{width:100%;min-width:1000px}svg rect{fill:#e6ebe1;stroke:#a3b7a7}svg text{fill:#18362e;font:14px system-ui,sans-serif}.boundary-label{font-weight:bold}.area-label{font-style:italic}.selected{stroke:#14634b;stroke-width:3;fill:none}.possible{stroke:#64746d;stroke-width:2;stroke-dasharray:7 5;fill:none}svg a:focus{outline:3px solid #ba882f}svg path:hover{stroke:#ba882f;stroke-width:5}.map{overflow:auto;background:white;border:1px solid #d6dace;border-radius:8px;margin:24px 0}details,article{background:#fff;padding:18px 22px;margin:12px 0;border:1px solid #d6dace;border-radius:6px;overflow-wrap:anywhere}summary{cursor:pointer;font-weight:600}summary small{display:block;font-weight:400}:target{outline:3px solid #ba882f}li{margin:10px 0}.tag{letter-spacing:.12em;font-size:12px;text-transform:uppercase}p,li,h1,h2,h3{overflow-wrap:anywhere}
+</style></head><body><main><header><p class="tag">Initial security overview</p><h1>${html(title)}</h1><p>${html(intro)}</p><p>Scope: ${html(s.scope)}</p><nav><a href="#overview">Overview</a><a href="#findings">Security observations</a><a href="#coverage">Coverage</a><a href="#next">Next step</a><a href="#relationships">Relationships</a><a href="#evidence">Evidence</a><a href="brief.md">Brief</a></nav></header>
+<section id="overview"><h2>Connected application overview</h2><p>Each node appears once. Grouping records placement, not verified deployed trust boundaries. Inspect its evidence basis: source, user intent, configuration or dated observation. Unclassified means placement has not been established.</p><p>Solid green: selected. Dashed: selection unestablished or not selected; inspect the support state in details. Arrowheads show direction. Click a node for its record or a path for its details.</p><p>${html(scopeNote)}</p>${renderOverview(s)}</section>
+<section id="findings"><h2>Security observations and investigation leads</h2>${findings.length ? journey(findings) : '<p>No evidence-backed findings recorded. Continue research; this is not an assurance conclusion.</p>'}</section>
+<section id="coverage"><h2>Coverage and gaps</h2><h3>Researched</h3>${s.coverage.length ? ul(s.coverage) : '<p>No coverage recorded.</p>'}<h3>Unknown or not researched</h3>${s.gaps.length ? ul(s.gaps) : '<p>No gaps recorded; completeness is not established.</p>'}</section>
+<section id="next"><h2>Next step</h2><p>${html(continuation)}</p>${journey(next)}</section>
+<section id="relationships"><h2>Detailed relationships</h2>${details || '<p>No relationships recorded yet.</p>'}</section>
+<section id="inventory"><h2>Component and service records</h2>${groups.map(g => `<h3>${html(boundaryNames[g.boundary])} · ${html(g.area)}</h3>${g.nodes.map(n => `<article id="${fragmentId('node', n['bom-ref'])}"><h3>${html(n.name)}</h3><p>${html(n.description ?? 'Description not recorded.')}</p><p>${html(n.type ?? 'service')} · ${html(n['bom-ref'])}${s.relationships.some(e => e.from === n['bom-ref'] || e.to === n['bom-ref']) ? '' : ' · Connections unknown.'}</p><p>Grouping evidence: ${(s.presentation[n['bom-ref']]?.evidence ?? []).map(id => html(basis(id)) + ' — ' + evidence([id])).join('; ') || 'Not recorded'}</p></article>`).join('')}`).join('')}</section>
+<section id="journey"><h2>Investigation journey</h2><p>Choose a next step, inspect the full journey, redirect or stop.</p>${journey(s.entries)}</section><section id="evidence"><h2>Evidence and decisions</h2>${ev}</section><footer><h2>Saved detail and interoperability</h2><p>${html(interchange)}</p><p><a href="investigation.md">Journal file</a> · <a href="surface.cdx.json">Saved Surface</a></p><p>${html(mechanics)} This view proves neither completeness nor runtime use.</p></footer></main></body></html>\n`;
+    return { 'brief.md': brief, 'investigation.md': journal, 'surface.html': body };
+}

package/dist/validate.d.ts

@@ -0,0 +1,4 @@
+import type { Artefact } from './contracts.js';
+export declare function validateArtefact(input: unknown): Artefact;
+/** Explicit offline bundle verification. Missing external context is an error here. */
+export declare function verifyReferences(input: unknown, context: unknown[]): void;