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

package/dist/source-tools.js

@@ -0,0 +1,201 @@
+import { lstatSync, realpathSync, opendirSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { InspectionError, readBytes, problem } from './settings.js';
+const MAX_FILE = 256 * 1024;
+const MAX_ENTRIES = 1000;
+const MAX_SEARCH_FILES = 100;
+const MAX_SEARCH_BYTES = 8 * 1024 * 1024;
+const excludedName = (name) => name.startsWith('.') || ['node_modules', 'vendor', 'dist'].includes(name)
+    || /\.(pem|key|p12|pfx)$/i.test(name);
+/** Local read capability. Directory topology must remain stable during an operation. */
+export class SourceTools {
+    root;
+    file;
+    identity;
+    constructor(source) {
+        const selected = realpathSync(resolve(source));
+        const stat = lstatSync(selected);
+        if (!stat.isDirectory() && !stat.isFile())
+            throw new InspectionError('Select a directory or regular file');
+        this.file = stat.isFile() ? basename(selected) : undefined;
+        this.root = this.file ? dirname(selected) : selected;
+        const rootStat = lstatSync(this.root);
+        this.identity = { dev: rootStat.dev, ino: rootStat.ino };
+    }
+    get selected() { return this.file ? join(this.root, this.file) : this.root; }
+    checkRoot() {
+        const stat = lstatSync(this.root);
+        if (!stat.isDirectory() || realpathSync(this.root) !== this.root || stat.dev !== this.identity.dev || stat.ino !== this.identity.ino)
+            throw new InspectionError('Source scope changed; start a new discovery session');
+    }
+    path(path) {
+        this.checkRoot();
+        if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(path))
+            throw new InspectionError('Invalid source path');
+        if (path === '.' && !this.file)
+            return this.root;
+        const parts = path.split('/');
+        if (parts.some(p => !p || p === '.' || p === '..'))
+            throw new InspectionError('Path escapes source scope');
+        if (this.file && path !== this.file)
+            throw new InspectionError('Path outside file-only scope');
+        let current = this.root;
+        for (const part of parts) {
+            if (excludedName(part))
+                throw new InspectionError('Path excluded from source scope');
+            current = join(current, part);
+            if (lstatSync(current).isSymbolicLink())
+                throw new InspectionError('Symbolic links are outside source scope');
+        }
+        return current;
+    }
+    list(path = '.') {
+        this.checkRoot();
+        if (this.file) {
+            if (path !== '.')
+                throw new InspectionError('Only . can be listed in file-only scope');
+            return excludedName(this.file) ? { entries: [], excluded: [{ path: this.file, reason: 'Excluded name' }], truncated: false }
+                : { entries: [{ path: this.file, kind: 'file' }], excluded: [], truncated: false };
+        }
+        const dir = opendirSync(this.path(path));
+        const entries = [], excluded = [];
+        let truncated = false;
+        try {
+            let count = 0;
+            for (let entry = dir.readSync(); entry !== null; entry = dir.readSync()) {
+                if (++count > MAX_ENTRIES) {
+                    truncated = true;
+                    break;
+                }
+                const child = path === '.' ? entry.name : `${path}/${entry.name}`;
+                if (excludedName(entry.name) || entry.isSymbolicLink() || (!entry.isFile() && !entry.isDirectory())) {
+                    excluded.push({ path: child, reason: 'Excluded name, symbolic link or special entry' });
+                }
+                else
+                    entries.push({ path: child, kind: entry.isDirectory() ? 'directory' : 'file' });
+            }
+        }
+        finally {
+            dir.closeSync();
+        }
+        entries.sort((a, b) => a.path.localeCompare(b.path));
+        return { entries, excluded, truncated };
+    }
+    bytes(path) {
+        const bytes = readBytes(this.path(path), MAX_FILE);
+        if (bytes.includes(0))
+            throw new InspectionError('Binary source is not supported text');
+        try {
+            return { bytes, text: new TextDecoder('utf-8', { fatal: true }).decode(bytes) };
+        }
+        catch {
+            throw new InspectionError('Source is not valid UTF-8 text');
+        }
+    }
+    read(path, startLine = 1, lineCount = 200) {
+        if (!Number.isSafeInteger(startLine) || startLine < 1 || !Number.isSafeInteger(lineCount) || lineCount < 1 || lineCount > 200)
+            throw new InspectionError('Invalid line range (1–200 lines per read)');
+        const { bytes, text } = this.bytes(path);
+        const lines = text.split('\n');
+        const selected = [];
+        let length = 0;
+        for (let n = startLine - 1; n < Math.min(lines.length, startLine - 1 + lineCount); n++) {
+            const content = `${n + 1}: ${lines[n]}`;
+            if (length + content.length > 32 * 1024)
+                break;
+            selected.push(content);
+            length += content.length + 1;
+        }
+        return { path, digest: `sha256:${createHash('sha256').update(bytes).digest('hex')}`,
+            inspectedAt: new Date().toISOString(), startLine, endLine: startLine + selected.length - 1,
+            totalLines: lines.length, text: selected.join('\n'), truncated: startLine > 1 || selected.length < lines.length };
+    }
+    search(query) {
+        if (typeof query !== 'string' || !query || query.length > 200 || /[\r\n\0]/.test(query))
+            throw new InspectionError('Invalid literal search query (1–200 characters, one line)');
+        const matches = [];
+        const excluded = [];
+        const pending = ['.'];
+        let files = 0, bytesRead = 0, entriesSeen = 0, truncated = false;
+        outer: while (pending.length) {
+            const directory = pending.shift();
+            let listing;
+            try {
+                listing = this.list(directory);
+            }
+            catch (error) {
+                excluded.push({ path: directory, reason: problem(error) });
+                continue;
+            }
+            truncated ||= listing.truncated;
+            excluded.push(...listing.excluded.slice(0, MAX_ENTRIES - excluded.length));
+            entriesSeen += listing.excluded.length;
+            if (entriesSeen > MAX_ENTRIES) {
+                truncated = true;
+                break;
+            }
+            for (const entry of listing.entries) {
+                if (++entriesSeen > MAX_ENTRIES || files >= MAX_SEARCH_FILES || bytesRead >= MAX_SEARCH_BYTES || matches.length >= 100) {
+                    truncated = true;
+                    break outer;
+                }
+                if (entry.kind === 'directory') {
+                    if (entry.path.split('/').length < 32)
+                        pending.push(entry.path);
+                    else {
+                        truncated = true;
+                        excluded.push({ path: entry.path, reason: 'Search depth limit' });
+                    }
+                    continue;
+                }
+                files++;
+                try {
+                    const { bytes, text } = this.bytes(entry.path);
+                    bytesRead += bytes.length;
+                    const digest = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+                    const lines = text.split('\n');
+                    for (let n = 0; n < lines.length; n++)
+                        if (lines[n].includes(query)) {
+                            matches.push({ path: entry.path, line: n + 1, text: lines[n].slice(0, 1000), digest });
+                            if (matches.length >= 100) {
+                                truncated = true;
+                                break outer;
+                            }
+                        }
+                }
+                catch (error) {
+                    excluded.push({ path: entry.path, reason: problem(error) });
+                }
+            }
+        }
+        return { query, matches, excluded, truncated, filesInspected: files, inspectedAt: new Date().toISOString() };
+    }
+    call(tool, args) {
+        if (!args || typeof args !== 'object' || Array.isArray(args))
+            throw new InspectionError('Invalid tool arguments');
+        const a = args;
+        const keys = tool === 'source_list' ? ['path'] : tool === 'source_read' ? ['path', 'startLine', 'lineCount'] : tool === 'source_search' ? ['query'] : undefined;
+        if (!keys)
+            throw new InspectionError('Unknown source tool');
+        if (Object.keys(a).some(k => !keys.includes(k)))
+            throw new InspectionError('Invalid tool arguments');
+        if (tool === 'source_search')
+            return this.search(a.query);
+        if (a.path !== undefined && typeof a.path !== 'string')
+            throw new InspectionError('Invalid tool arguments');
+        if (tool === 'source_list')
+            return this.list(a.path);
+        if (typeof a.path !== 'string')
+            throw new InspectionError('Invalid tool arguments');
+        return this.read(a.path, a.startLine, a.lineCount);
+    }
+}
+export const sourceToolSpecs = [
+    { name: 'source_list', description: 'List a directory in the authorized local source. Start with path ".". Returns explicit omissions and truncation.',
+        inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'], additionalProperties: false } },
+    { name: 'source_read', description: 'Read UTF-8 source evidence with line numbers and exact full-file SHA-256. Paths are relative to source; no shell or writes. Maximum 200 lines per call.',
+        inputSchema: { type: 'object', properties: { path: { type: 'string' }, startLine: { type: 'integer' }, lineCount: { type: 'integer' } }, required: ['path'], additionalProperties: false } },
+    { name: 'source_search', description: 'Bounded recursive literal case-sensitive search within authorized source text. Reports coverage omissions. Use source_read to inspect matching context.',
+        inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'], additionalProperties: false } }
+];

package/dist/startup.d.ts

@@ -0,0 +1,7 @@
+import { type Settings } from './settings.js';
+export declare function overview(): {
+    text: string;
+    failed: boolean;
+    configured: boolean;
+    settings?: Settings;
+};

package/dist/startup.js

@@ -0,0 +1,74 @@
+import { readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, join } from 'node:path';
+import { decode } from './codec.js';
+import { readResearchHtml } from './html.js';
+import { line, problem, readLocal, InspectionError, loadSettings } from './settings.js';
+function artefacts(root) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch (error) {
+        return { lines: ['Local artefacts', `  ${line(root)} | Folder unavailable (${problem(error)})`], failed: error?.code !== 'ENOENT' };
+    }
+    entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    const lines = [`Local artefacts (${entries.length})`];
+    let failed = false;
+    if (!entries.length)
+        lines.push('  Folder is empty');
+    for (const entry of entries) {
+        const path = join(root, entry.name);
+        try {
+            if (entry.isSymbolicLink())
+                throw new InspectionError('Symlink not followed');
+            if (!entry.isFile())
+                throw new InspectionError('Not a regular file');
+            const extension = extname(entry.name).toLowerCase();
+            if (!['.json', '.yaml', '.yml', '.html'].includes(extension))
+                throw new InspectionError('Unsupported file type');
+            const text = readLocal(path, 2 * 1024 * 1024);
+            let value;
+            try {
+                value = extension === '.html' ? readResearchHtml(text) : decode(text, extension === '.json' ? 'json' : 'yaml');
+            }
+            catch {
+                throw new InspectionError('Invalid or unsupported artefact; content not displayed');
+            }
+            const type = value.contract === 'n8r.surface/0.1' ? 'Surface definition' : 'Research record';
+            lines.push(`  ${line(value.title)} | ${type} | ${line(path)}`);
+        }
+        catch (error) {
+            failed = true;
+            lines.push(`  ${line(path)} | ${problem(error)}`);
+        }
+    }
+    return { lines, failed };
+}
+export function overview() {
+    const home = homedir();
+    const file = join(home, '.n8r/n8r-surface.json');
+    const lines = ['Configuration', `  File: ${line(file)}`];
+    let config;
+    let failed = false;
+    try {
+        config = loadSettings(home);
+        const text = config.original;
+        if (text === undefined)
+            lines.push('  Missing; using defaults (no file created)');
+        lines.push(`  Settings version: 1${text === undefined ? ' (default)' : ''}`, `  Artefact folder: ${line(config.root)}${config.defaultRoot ? ' (default)' : ''}`, `  Vault folder: ${config.vault === undefined ? 'Not configured' : line(config.vault)}`, `  Surface output: ${config.format.toUpperCase()}${config.defaultFormat ? ' (default)' : ''}`, `  AI runner: ${config.runner ? 'Configured (unverified; details withheld)' : 'Not configured'}`, `  Lab connection: ${config.lab ? 'Configured (unverified; details withheld)' : 'Not configured'}`);
+    }
+    catch (error) {
+        failed = true;
+        lines.push(`  Configuration unavailable: ${problem(error)}`);
+    }
+    lines.push('', 'Processes', `  n8r-surface overview: running (PID ${process.pid}); observed ${new Date().toISOString()}`, '  Runner/Lab processes: Status unknown (no live status source)', '');
+    if (config) {
+        const listed = artefacts(config.root);
+        lines.push(...listed.lines);
+        failed ||= listed.failed;
+    }
+    else
+        lines.push('Local artefacts', '  Not inspected: configuration unavailable');
+    return { text: lines.join('\n') + '\n', failed, configured: config !== undefined, settings: config };
+}

package/dist/surface-bom.d.ts

@@ -0,0 +1,73 @@
+export type Bom = Record<string, any>;
+export interface Relationship {
+    id: string;
+    from: string;
+    to: string;
+    kind: 'dependency' | 'integration' | 'hosting' | 'data-flow';
+    optionality: 'required' | 'optional' | 'alternative' | 'unknown';
+    group: string;
+    support: 'supported' | 'unknown' | 'absent' | 'conflicting' | 'out-of-scope';
+    selection: 'selected' | 'unknown' | 'not-selected' | 'conflicting';
+    observations: {
+        at: string;
+        evidence: string[];
+        note: string;
+    }[];
+    evidence: string[];
+    selectionEvidence: string[];
+    purpose: string;
+    mechanism: string;
+    configuration: string[];
+    conditions: string[];
+    note: string;
+}
+export interface Entry {
+    id: string;
+    kind: 'next' | 'question' | 'decision' | 'diversion' | 'finding';
+    title: string;
+    text: string;
+    status: 'open' | 'active' | 'done' | 'deferred' | 'superseded';
+    reason: string;
+    access: string;
+    evidence: string[];
+    at: string;
+    parent?: string;
+    supersedes?: string;
+}
+export interface Evidence {
+    id: string;
+    basis: 'source' | 'configuration' | 'observation' | 'user';
+    sources: {
+        index: number;
+        locator: string;
+    }[];
+    applicability: string;
+}
+export interface Surface {
+    bom: Bom;
+    objective: string;
+    scope: string;
+    relationships: Relationship[];
+    entries: Entry[];
+    evidence: Evidence[];
+    coverage: string[];
+    gaps: string[];
+    presentation: Record<string, Presentation>;
+}
+export interface Presentation {
+    boundary: 'internal' | 'external' | 'unknown';
+    area: string;
+    focus?: boolean;
+    evidence: string[];
+}
+export declare const prefix = "n8r:surface:";
+export declare const property: (name: string, value: unknown) => {
+    name: string;
+    value: string;
+};
+export declare function projectDependencies(edges: Relationship[]): {
+    ref: string;
+    dependsOn: string[];
+}[];
+/** Parses only the documented profile, checking references and projection consistency. */
+export declare function checkSurfaceBom(input: unknown): Surface;

package/dist/surface-bom.js

@@ -0,0 +1,139 @@
+/** Bounded Surface profile over CycloneDX 1.7; no parallel native authority. */
+import { validateBom } from './cyclonedx-validation.js';
+import { privacy } from './skill-artifacts.js';
+import { canonical } from './portable.js';
+import { decodeJsonValue } from './codec.js';
+export const prefix = 'n8r:surface:';
+export const property = (name, value) => ({ name: prefix + name, value: typeof value === 'string' ? value : JSON.stringify(value) });
+function fail(reason) { throw Error(`Surface BOM refused: ${reason}. Input values withheld.`); }
+function requireThat(ok, reason) { if (!ok)
+    fail(reason); }
+const nonempty = (x) => typeof x === 'string' && x.trim().length > 0;
+const strings = (x) => Array.isArray(x) && x.every(nonempty) && new Set(x).size === x.length;
+const date = (x) => typeof x === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(x) && Number.isFinite(Date.parse(x));
+const keys = (x, required, optional = []) => x && typeof x === 'object' && !Array.isArray(x) && required.every(k => Object.hasOwn(x, k)) && Object.keys(x).every(k => [...required, ...optional].includes(k));
+const unique = (xs) => new Set(xs).size === xs.length;
+export function projectDependencies(edges) {
+    const map = new Map();
+    for (const e of edges)
+        if (e.kind === 'dependency' && e.selection === 'selected') {
+            const targets = map.get(e.from) ?? new Set();
+            targets.add(e.to);
+            map.set(e.from, targets);
+        }
+    return [...map].sort(([a], [b]) => a.localeCompare(b)).map(([ref, to]) => ({ ref, dependsOn: [...to].sort() }));
+}
+/** Parses only the documented profile, checking references and projection consistency. */
+export function checkSurfaceBom(input) {
+    validateBom(input);
+    const b = structuredClone(input);
+    requireThat(nonempty(b.serialNumber) && Number.isSafeInteger(b.version) && b.version > 0 && date(b.metadata?.timestamp), 'revision identity');
+    // Safe profile does not carry endpoints/connection values. Public source URLs are
+    // supported only as externalReferences; source content itself is not persisted.
+    const safe = structuredClone(b);
+    for (const r of safe.externalReferences ?? []) {
+        requireThat(!r.url.startsWith('file:') && !r.url.includes('@') && !/[?]/.test(r.url), 'source locator privacy');
+        if (/^https:\/\//.test(r.url)) {
+            const u = new URL(r.url);
+            requireThat(!u.username && !u.password && !/^\d/.test(u.hostname) && !['localhost'].includes(u.hostname), 'source locator privacy');
+            r.url = 'urn:public-source';
+        }
+    }
+    privacy(safe);
+    const refs = new Set();
+    function visit(x) { if (!x || typeof x !== 'object')
+        return; if (!Array.isArray(x) && Object.hasOwn(x, 'bom-ref')) {
+        requireThat(nonempty(x['bom-ref']) && !refs.has(x['bom-ref']), 'unique BOM references');
+        refs.add(x['bom-ref']);
+    } for (const v of Object.values(x))
+        visit(v); }
+    visit(b);
+    const nodes = new Set([...(b.components ?? []), ...(b.services ?? [])].map(n => n['bom-ref']));
+    const annotations = new Map((b.annotations ?? []).map((a) => [a['bom-ref'], a]));
+    for (const a of annotations.values())
+        requireThat(nonempty(a['bom-ref']) && a.subjects.length > 0 && a.subjects.every((id) => refs.has(id)), 'annotation subjects');
+    for (const c of b.citations ?? []) {
+        requireThat(c.pointers && !c.expressions && refs.has(c.attributedTo) && !c.process, 'citation attribution');
+        for (const p of c.pointers) {
+            requireThat(typeof p === 'string' && p.startsWith('/'), 'citation pointer');
+            let v = b;
+            for (const k of p.slice(1).split('/').map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~'))) {
+                requireThat(v !== null && typeof v === 'object' && Object.hasOwn(v, k), 'citation pointer target');
+                v = v[k];
+            }
+        }
+    }
+    const allowed = ['profile', 'objective', 'scope', 'relationship', 'entry', 'evidence', 'coverage', 'gap', 'predecessor-digest', 'reconciliation', 'migration'];
+    const ps = b.properties ?? [];
+    for (const p of ps)
+        requireThat(p.name.startsWith(prefix) && allowed.includes(p.name.slice(prefix.length)), 'profile property');
+    const values = (key) => ps.filter((p) => p.name === prefix + key).map((p) => p.value);
+    const one = (key) => { const vs = values(key); requireThat(vs.length === 1 && nonempty(vs[0]), 'single ' + key); return vs[0]; };
+    requireThat(one('profile') === '1', 'supported profile version');
+    for (const key of ['predecessor-digest', 'reconciliation', 'migration'])
+        requireThat(values(key).length <= 1, 'single ' + key);
+    const parsed = (key) => values(key).map((s) => { try {
+        return decodeJsonValue(s);
+    }
+    catch {
+        return fail('profile JSON');
+    } });
+    const evidence = parsed('evidence'), relationships = parsed('relationship'), entries = parsed('entry');
+    requireThat(unique(evidence.map(e => e.id)) && unique(relationships.map(e => e.id)) && unique(entries.map(e => e.id)), 'unique profile IDs');
+    const evidenceIds = new Set(evidence.map(e => e.id));
+    for (const e of evidence) {
+        requireThat(keys(e, ['id', 'basis', 'sources', 'applicability']) && annotations.has(e.id) && ['source', 'configuration', 'observation', 'user'].includes(e.basis) && nonempty(e.applicability) && Array.isArray(e.sources), 'evidence record');
+        requireThat(e.basis === 'user' || e.sources.length > 0, 'source-backed evidence');
+        for (const s of e.sources)
+            requireThat(keys(s, ['index', 'locator']) && Number.isSafeInteger(s.index) && s.index >= 0 && b.externalReferences?.[s.index] && nonempty(s.locator), 'source reference');
+    }
+    const evidenceFor = (ids, subjects, basis) => strings(ids) && ids.every(id => evidenceIds.has(id) && subjects.every(n => annotations.get(id).subjects.includes(n)) && (!basis || basis.includes(evidence.find(e => e.id === id).basis)));
+    const presentation = Object.create(null);
+    for (const n of [...(b.components ?? []), ...(b.services ?? [])]) {
+        const hints = (n.properties ?? []).filter((p) => p.name === prefix + 'presentation');
+        requireThat(hints.length <= 1, 'single node presentation');
+        if (!hints.length)
+            continue;
+        let p;
+        try {
+            p = decodeJsonValue(hints[0].value);
+        }
+        catch {
+            return fail('node presentation JSON');
+        }
+        requireThat(keys(p, ['boundary', 'area', 'evidence'], ['focus']) && ['internal', 'external', 'unknown'].includes(p.boundary) && nonempty(p.area) && (p.focus === undefined || typeof p.focus === 'boolean'), 'node presentation shape');
+        requireThat(evidenceFor(p.evidence, [n['bom-ref']]) && (p.boundary === 'unknown' || p.evidence.length > 0), 'node presentation evidence');
+        presentation[n['bom-ref']] = p;
+    }
+    requireThat(Object.values(presentation).filter(p => p.focus).length <= 1, 'single focus application');
+    const edgeKeys = ['id', 'from', 'to', 'kind', 'optionality', 'group', 'support', 'selection', 'observations', 'evidence', 'selectionEvidence', 'purpose', 'mechanism', 'configuration', 'conditions', 'note'];
+    for (const e of relationships) {
+        requireThat(keys(e, edgeKeys) && nonempty(e.id) && nodes.has(e.from) && nodes.has(e.to), 'relationship endpoints/shape');
+        requireThat(['dependency', 'integration', 'hosting', 'data-flow'].includes(e.kind) && ['required', 'optional', 'alternative', 'unknown'].includes(e.optionality) && typeof e.group === 'string', 'relationship kind/optionality');
+        requireThat(e.optionality !== 'alternative' || nonempty(e.group), 'alternative group');
+        requireThat(['supported', 'unknown', 'absent', 'conflicting', 'out-of-scope'].includes(e.support) && ['selected', 'unknown', 'not-selected', 'conflicting'].includes(e.selection), 'relationship states');
+        requireThat([e.purpose, e.mechanism, e.note].every(nonempty) && strings(e.configuration) && strings(e.conditions), 'relationship detail');
+        requireThat(evidenceFor(e.evidence, [e.from, e.to]) && evidenceFor(e.selectionEvidence, [e.from, e.to], ['configuration', 'user']), 'relationship evidence');
+        requireThat(!['supported', 'absent', 'conflicting'].includes(e.support) || e.evidence.length > 0, 'support evidence');
+        requireThat(e.selection === 'unknown' || e.selectionEvidence.length > 0, 'selection evidence');
+        requireThat(e.selection !== 'selected' || !e.configuration.some(x => /\$\{|<[^>]+>|placeholder/i.test(x)), 'placeholder selection');
+        requireThat(Array.isArray(e.observations), 'observations');
+        for (const o of e.observations)
+            requireThat(keys(o, ['at', 'evidence', 'note']) && date(o.at) && nonempty(o.note) && o.evidence.length > 0 && evidenceFor(o.evidence, [e.from, e.to], ['observation']), 'dated observed evidence');
+    }
+    const entryIds = new Set(entries.map(e => e.id));
+    for (const e of entries) {
+        requireThat(keys(e, ['id', 'kind', 'title', 'text', 'status', 'reason', 'access', 'evidence', 'at'], ['parent', 'supersedes']) && [e.id, e.title, e.text, e.reason, e.access].every(nonempty) && date(e.at), 'investigation entry');
+        requireThat(['next', 'question', 'decision', 'diversion', 'finding'].includes(e.kind) && ['open', 'active', 'done', 'deferred', 'superseded'].includes(e.status), 'investigation state');
+        requireThat(strings(e.evidence) && e.evidence.every(id => evidenceIds.has(id)), 'investigation evidence');
+        requireThat(e.kind !== 'decision' || e.evidence.some(id => evidence.find(x => x.id === id)?.basis === 'user'), 'decision provenance');
+        for (const id of [e.parent, e.supersedes])
+            requireThat(id === undefined || (entryIds.has(id) && id !== e.id), 'investigation links');
+    }
+    const deps = (b.dependencies ?? []).map((d) => ({ ref: d.ref, dependsOn: [...(d.dependsOn ?? [])].sort() })).sort((a, z) => a.ref.localeCompare(z.ref));
+    requireThat((b.dependencies ?? []).every((d) => !d.provides) && canonical(deps) === canonical(projectDependencies(relationships)), 'selected dependency projection');
+    requireThat(b.compositions?.some((c) => c.aggregate === 'unknown'), 'bounded coverage declaration');
+    const coverage = values('coverage'), gaps = values('gap');
+    requireThat(strings(coverage) && strings(gaps), 'coverage/gaps');
+    return { bom: b, objective: one('objective'), scope: one('scope'), relationships, entries, evidence, coverage, gaps, presentation };
+}

package/dist/surface-draft.d.ts

@@ -0,0 +1,22 @@
+import { type Bundle } from './skill-artifacts.js';
+import type { ResearchRecord, SurfaceDefinition, Artefact } from './contracts.js';
+export type LegacyDraft = {
+    research: ResearchRecord;
+    surface: SurfaceDefinition;
+};
+export type SurfaceDraft = LegacyDraft | Bundle;
+export declare const isBundle: (draft: SurfaceDraft) => draft is Bundle;
+export type DraftContext = {
+    createdAt?: string;
+    previous?: SurfaceDraft;
+};
+export declare const revisionRef: (a: Artefact) => {
+    id: string;
+    revision: string;
+    digest: string;
+};
+/** Preservation beyond the library's bounded lineage checks. */
+export declare function verifyPairSuccessor(before: SurfaceDraft, after: SurfaceDraft): void;
+/** New bundles use the shared skill checker; legacy content keeps host-owned envelopes. */
+export declare function prepareSurfaceDraft(input: unknown, context?: DraftContext): SurfaceDraft;
+export declare function previewSurface(draft: SurfaceDraft): string;

package/dist/surface-draft.js

@@ -0,0 +1,112 @@
+import { checkBundle, verifyBundleSuccessor } from './skill-artifacts.js';
+import { renderBrief } from './skill-presentation.js';
+import { randomUUID } from 'node:crypto';
+import { canonical, digest } from './portable.js';
+import { validateArtefact, verifyReferences } from './validate.js';
+import { verifySuccessor } from './revisions.js';
+import { InspectionError } from './settings.js';
+export const isBundle = (draft) => draft.surface.contract === 'n8r.surface/0.3';
+export const revisionRef = (a) => ({ id: a.id, revision: a.revision.id, digest: digest(a) });
+const error = (s) => { throw new InspectionError(s); };
+function retained(before, after, label) {
+    for (const old of before)
+        if (!after.some(x => x.id === old.id))
+            error(`Preserve ${label} identity ${old.id}; deletion is outside this increment`);
+}
+/** Preservation beyond the library's bounded lineage checks. */
+export function verifyPairSuccessor(before, after) {
+    if (isBundle(before) && isBundle(after)) {
+        verifyBundleSuccessor(before, after);
+        return;
+    }
+    verifySuccessor(before.research, after.research);
+    verifySuccessor(before.surface, after.surface);
+    for (const key of ['sources', 'findings', 'alternatives', 'decisions', 'questions'])
+        retained(before.research[key], after.research[key], key);
+    retained(before.surface.nodes, after.surface.nodes, 'component');
+    for (const source of before.research.sources) {
+        if (canonical(source) !== canonical(after.research.sources.find(x => x.id === source.id)))
+            error(`Preserve historical source ${source.id}; add a new source identity for new evidence`);
+    }
+    for (const finding of before.research.findings) {
+        const next = after.research.findings.find(x => x.id === finding.id);
+        for (const claim of finding.claims)
+            if (!next.claims.some(c => canonical(c) === canonical(claim)))
+                error(`Preserve historical claim in ${finding.id}`);
+        if (next.subject !== finding.subject || next.property !== finding.property)
+            error(`Retained finding changed subject/property: ${finding.id}`);
+    }
+    for (const note of before.research.notes)
+        if (!after.research.notes.some(n => canonical(n) === canonical(note)))
+            error('Preserve historical research note; append corrections');
+    for (const decision of before.research.decisions)
+        if (after.research.decisions.find(x => x.id === decision.id).alternative !== decision.alternative)
+            error(`Retained decision changed alternative: ${decision.id}`);
+    for (const node of before.surface.nodes)
+        if (canonical(after.surface.nodes.find(x => x.id === node.id).type) !== canonical(node.type))
+            error(`Retained component changed type: ${node.id}`);
+    for (const key of ['research', 'surface'])
+        for (const [name, value] of Object.entries(before[key].extensions)) {
+            if (!Object.hasOwn(after[key].extensions, name) || canonical(value) !== canonical(after[key].extensions[name]))
+                error(`Preserve opaque extension ${name}`);
+        }
+}
+/** New bundles use the shared skill checker; legacy content keeps host-owned envelopes. */
+export function prepareSurfaceDraft(input, context = {}) {
+    canonical(input); // bound size/depth and reject non-data before inspecting it
+    const raw = input;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !['research,surface', 'dependencies,research,surface'].includes(Object.keys(raw).sort().join(',')))
+        error('Expected research and surface content objects');
+    if (raw?.surface?.contract === 'n8r.surface/0.3') {
+        const bundle = checkBundle(JSON.parse(JSON.stringify(raw)));
+        if (context.previous) {
+            verifyPairSuccessor(context.previous, bundle);
+        }
+        return bundle;
+    }
+    const data = JSON.parse(JSON.stringify(raw));
+    const createdAt = context.createdAt ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    for (const key of ['research', 'surface']) {
+        const value = data[key];
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            error(`Invalid ${key} content`);
+        for (const reserved of ['id', 'revision', 'contract', ...(key === 'surface' ? ['records'] : [])])
+            if (Object.hasOwn(value, reserved))
+                error(`Host owns ${key}.${reserved}; supply content only`);
+        const prior = context.previous?.[key];
+        value.contract = key === 'research' ? 'n8r.research/0.1' : 'n8r.surface/0.1';
+        value.id = prior?.id ?? `urn:n8r:${key}:${randomUUID()}`;
+        value.revision = { id: randomUUID(), parent: prior ? revisionRef(prior) : null, createdAt, author: 'n8r-surface Researcher', reason: prior ? 'Human-requested revision' : 'Generated from research' };
+    }
+    const research = validateArtefact(data.research);
+    data.surface.records = [revisionRef(research)];
+    for (const entity of [...(data.surface.nodes ?? []), ...(data.surface.relationships ?? [])]) {
+        if (!Array.isArray(entity.basis) || !entity.basis.length)
+            error('Each entity needs a nonempty structured basis array');
+        for (const basis of entity.basis) {
+            if (!basis || Object.keys(basis).join(',') !== 'items')
+                error('Supply each basis as {items: [finding or decision IDs]}; the host owns record/revision');
+            basis.record = research.id;
+            basis.revision = research.revision.id;
+        }
+    }
+    const surface = validateArtefact(data.surface);
+    verifyReferences(surface, [research]);
+    const draft = { research, surface };
+    if (context.previous)
+        verifyPairSuccessor(context.previous, draft);
+    return draft;
+}
+export function previewSurface(draft) {
+    if (isBundle(draft))
+        return renderBrief(draft) + '\nNot saved. Enter /save surface to save exactly this preview.';
+    const { research: r, surface: s } = draft;
+    return ['Validated partial Surface preview (declared only; not runtime proof)', s.title,
+        'Components:', ...s.nodes.map(n => `  ${n.id} | ${n.label}`),
+        'Declared connections:', ...s.relationships.map(e => `  ${e.id}: ${e.from} -> ${e.to} (${e.type.term})`),
+        'Human decisions:', ...r.decisions.map(d => `  ${d.id}: ${d.choice} ${r.alternatives.find(a => a.id === d.alternative)?.title} — ${d.reason}`),
+        'Requirements:', ...s.requirements.map(q => `  ${q.id}: ${q.state} — ${q.description}`),
+        'Coverage:', ...s.coverage.map(x => `  ${x}`), 'Unknowns and gaps:', ...s.gaps.map(x => `  ${x}`),
+        'Evidence:', ...r.findings.map(f => `  ${f.id}: ${f.state} — ${f.note}; ${f.claims.flatMap(c => c.evidence.map(e => `${e.source} ${e.locator}`)).join('; ')}`),
+        'Not saved. Enter /save surface to save exactly this preview.'].join('\n');
+}

package/dist/surface-instructions.d.ts

@@ -0,0 +1,3 @@
+/** Content fields mirror the existing experimental contracts; host metadata is omitted. */
+export declare const legacySurfaceInstructions = "\nSTRUCTURED SURFACE CAPABILITY (host adapter 0.1):\nWhen 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.\n\nUse these exact content fields (no contract, id, revision or records; the host assigns them):\nresearch: {title,scope,extensions,sources,findings,alternatives,decisions,questions,notes}.\nsurface: {title,scope,extensions,kind:\"definition\",vocabularies,nodes,relationships,requirements,coverage,gaps}.\nAll 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.\n\nSource: {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.\nFinding: {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.\nAlternative: {id,title,findings:[finding IDs],requirements:[text descriptions]}.\nDecision: {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.\nQuestion: {id,text,findings:[finding IDs]}. Note: {by,at,text}. Keep human prose, unresolved questions and recommended next investigations.\nVocabulary: {id,version}; version is a token such as 0.1. Use an explicitly scoped provisional vocabulary, not a claim of universal compatibility.\nNode: {id,label,type:{vocabulary,term},attributes:{property:{state,note,value?}},basis:[{items:[finding/decision/alternative/question IDs]}],requirements:[requirement IDs]}.\nRelationship: 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.\nFact 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.\nRequirement: {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.\n\nOn 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.\n";
+export declare const surfaceInstructions: string;