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

package/dist/setup.js

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { InspectionError, loadSettings, localPath } from './settings.js';
+const children = ['research', 'artifacts', 'surfaces'];
+/** Resolve existing ancestors as well as explicitly chosen root symlinks. */
+function canonical(path) {
+    try {
+        return fs.realpathSync(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // Reject dangling symlinks rather than treating them as new directories.
+        try {
+            fs.lstatSync(path);
+            throw new InspectionError('Dangling symlink');
+        }
+        catch (entryError) {
+            if (entryError.code !== 'ENOENT')
+                throw entryError;
+        }
+        const parent = dirname(path);
+        if (parent === path)
+            throw error;
+        return join(canonical(parent), path.slice(parent.length));
+    }
+}
+export function chooseVault(value, home, cwd) {
+    return localPath(canonical(localPath(value, home, cwd)), home, cwd);
+}
+/** Read-only validation: missing folders need consent, occupied paths are errors. */
+export function inspectVault(root) {
+    root = canonical(root);
+    let missing = false;
+    for (const path of [root, ...children.map(child => join(root, child))]) {
+        try {
+            const stat = fs.lstatSync(path);
+            if (stat.isSymbolicLink())
+                throw new InspectionError('Vault children cannot be symlinks');
+            if (!stat.isDirectory())
+                throw new InspectionError('Vault path is not a directory');
+            fs.accessSync(path, fs.constants.R_OK | fs.constants.X_OK);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            missing = true;
+        }
+    }
+    return { root, missing };
+}
+function inside(path, source) {
+    const part = relative(source, canonical(path));
+    return part === '' || (part !== '..' && !part.startsWith(`..${sep}`) && !part.startsWith(sep));
+}
+function unchanged(snapshot) {
+    const current = loadSettings(snapshot.home).original;
+    if (snapshot.original === undefined ? current !== undefined : current === undefined || !snapshot.original.equals(current)) {
+        throw new InspectionError('Settings changed; setup conflict. Restart and review the saved values.');
+    }
+}
+/** Called only after explicit acceptance. See startup.md for the writer boundary. */
+export function saveSetup(snapshot, selected, cwd) {
+    const vault = inspectVault(chooseVault(selected, snapshot.home, cwd)).root;
+    const source = canonical(resolve(cwd));
+    const file = snapshot.file;
+    for (const path of [dirname(file), file, vault, ...children.map(child => join(vault, child))]) {
+        if (inside(path, source))
+            throw new InspectionError('Setup would write inside the source; choose a separate vault or source directory.');
+    }
+    if (snapshot.vault !== undefined && canonical(snapshot.vault) !== vault)
+        throw new InspectionError('Configured vault cannot be changed by setup');
+    const legacy = canonical(snapshot.root);
+    for (const child of children) {
+        const path = join(vault, child);
+        if (canonical(path) !== legacy && inside(path, legacy)) {
+            throw new InspectionError('Vault folders would occupy the legacy artefact corpus; choose a separate vault.');
+        }
+    }
+    // Keep unknown JSON member bytes, including numbers outside JS precision/range.
+    // The validated original is an object containing version, so a comma is valid.
+    let output = Buffer.alloc(0);
+    if (snapshot.vault === undefined) {
+        if (snapshot.original === undefined) {
+            output = Buffer.from(JSON.stringify({ version: 1, vaultRoot: vault }, null, 2) + '\n');
+        }
+        else {
+            const end = snapshot.original.lastIndexOf(0x7d);
+            output = Buffer.concat([snapshot.original.subarray(0, end),
+                Buffer.from(`,\n  "vaultRoot": ${JSON.stringify(vault)}\n`), snapshot.original.subarray(end)]);
+        }
+    }
+    if (output.length > 64 * 1024)
+        throw new InspectionError('Updated settings exceeds 65536 bytes');
+    fs.mkdirSync(dirname(file), { recursive: true });
+    const lock = file + '.lock';
+    let lockFd;
+    try {
+        lockFd = fs.openSync(lock, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new InspectionError('Setup lock exists; another setup may be in progress. See startup documentation for stale-lock recovery.');
+        throw error;
+    }
+    let temporary;
+    try {
+        unchanged(snapshot);
+        fs.mkdirSync(vault, { recursive: true });
+        for (const child of children) {
+            const path = join(vault, child);
+            try {
+                fs.mkdirSync(path);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            const stat = fs.lstatSync(path);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new InspectionError('Vault child is occupied or a symlink');
+        }
+        inspectVault(vault);
+        unchanged(snapshot);
+        if (snapshot.vault === undefined) {
+            const candidate = file + '.' + randomUUID() + '.tmp';
+            const fd = fs.openSync(candidate, 'wx', 0o600);
+            temporary = candidate;
+            try {
+                fs.writeFileSync(fd, output);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            unchanged(snapshot);
+            if (snapshot.original === undefined)
+                fs.linkSync(temporary, file);
+            else
+                fs.renameSync(temporary, file);
+        }
+        return vault;
+    }
+    finally {
+        try {
+            if (temporary !== undefined) {
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+            }
+        }
+        finally {
+            fs.closeSync(lockFd);
+            fs.unlinkSync(lock);
+        }
+    }
+}

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 {};

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-draft.d.ts

@@ -0,0 +1,19 @@
+import type { ResearchRecord, SurfaceDefinition, Artefact } from './contracts.js';
+export type SurfaceDraft = {
+    research: ResearchRecord;
+    surface: SurfaceDefinition;
+};
+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;
+/** The model supplies contract content; the host owns envelope and record-reference fields. */
+export declare function prepareSurfaceDraft(input: unknown, context?: DraftContext): SurfaceDraft;
+export declare function previewSurface({ research: r, surface: s }: SurfaceDraft): string;

package/dist/surface-draft.js

@@ -0,0 +1,95 @@
+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 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) {
+    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}`);
+        }
+}
+/** The model supplies contract content; the host owns envelope and record-reference fields. */
+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) || Object.keys(raw).sort().join(',') !== 'research,surface')
+        error('Expected research and surface content objects');
+    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({ research: r, surface: s }) {
+    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');
+}