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

package/dist/cyclonedx-validation.d.ts

@@ -0,0 +1 @@
+export declare function validateBom(bom: unknown): void;

package/dist/cyclonedx-validation.js

@@ -0,0 +1,45 @@
+/** Standard validation shared by the legacy reader and BOM authority. */
+import { Ajv } from 'ajv';
+import formats from 'ajv-formats';
+import extendedFormats from 'ajv-formats-draft2019';
+import bomSchema from './cyclonedx-schemas/bom-1.7.schema.json' with { type: 'json' };
+import cryptoSchema from './cyclonedx-schemas/cryptography-defs.schema.json' with { type: 'json' };
+import spdxSchema from './cyclonedx-schemas/spdx.schema.json' with { type: 'json' };
+import jsfSchema from './cyclonedx-schemas/jsf-0.82.schema.json' with { type: 'json' };
+function refuse() { throw Error('CycloneDX 1.7 schema/reference validation failed. Input values withheld.'); }
+function guard(fn) { try {
+    return fn();
+}
+catch {
+    return refuse();
+} }
+const ajv = new Ajv({ strict: false, allErrors: false, validateFormats: true });
+// ajv-formats CJS interop is normalized by Node and the standalone bundler.
+formats(ajv);
+extendedFormats(ajv);
+// The upstream IRI checker rejects URNs because uri-js parses their NSS
+// separately from path. Accept only the standard BOM-Link grammar here.
+const iriReference = ajv.formats['iri-reference'];
+ajv.addFormat('iri-reference', (value) => /^urn:cdx:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/[1-9][0-9]*(?:#[^\s]+)?$/.test(value) || iriReference(value));
+ajv.addSchema(spdxSchema);
+ajv.addSchema(jsfSchema);
+ajv.addSchema(cryptoSchema);
+const schemaCheck = ajv.compile(bomSchema);
+export function validateBom(bom) {
+    guard(() => {
+        if (!schemaCheck(bom))
+            refuse();
+        const b = bom;
+        if (b.bomFormat !== 'CycloneDX' || b.specVersion !== '1.7')
+            refuse();
+        const refs = new Set();
+        for (const n of [...(b.components ?? []), ...(b.services ?? [])]) {
+            if (typeof n['bom-ref'] !== 'string' || refs.has(n['bom-ref']))
+                refuse();
+            refs.add(n['bom-ref']);
+        }
+        for (const d of b.dependencies ?? [])
+            if (!refs.has(d.ref) || d.dependsOn?.some((r) => !refs.has(r)))
+                refuse();
+    });
+}

package/dist/html.d.ts

@@ -0,0 +1,5 @@
+import type { ResearchRecord } from './contracts.js';
+/** The template is part of profile 0.1. Changing it requires a versioned reader. */
+export declare function renderResearchHtml(input: unknown): string;
+/** Extract only to verify; no DOM execution and no permissive HTML repair. */
+export declare function readResearchHtml(html: string): ResearchRecord;

package/dist/html.js

@@ -0,0 +1,74 @@
+import { decode, encode, decodeJsonValue } from './codec.js';
+import { checkSize, fail, canonical } from './portable.js';
+import { validateArtefact, verifyReferences } from './validate.js';
+import { renderBundleHtml } from './skill-presentation.js';
+const escape = (text) => text.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+function display(value) {
+    if (Array.isArray(value))
+        return value.length ? `<ol>${value.map(item => `<li>${display(item)}</li>`).join('')}</ol>` : '<p class="empty">No entries recorded.</p>';
+    if (value !== null && typeof value === 'object')
+        return `<dl>${Object.entries(value).map(([key, item]) => `<dt>${escape(key)}</dt><dd>${display(item)}</dd>`).join('')}</dl>`;
+    return `<span>${escape(typeof value === 'string' ? value : JSON.stringify(value))}</span>`;
+}
+/** The template is part of profile 0.1. Changing it requires a versioned reader. */
+export function renderResearchHtml(input) {
+    const record = validateArtefact(input);
+    if (record.contract !== 'n8r.research/0.1')
+        fail('$', 'HTML requires a research record');
+    const data = encode(record, 'json').trimEnd().replace(/[<>&\u2028\u2029]/g, c => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    const sections = Object.entries(record).filter(([key]) => key !== 'title').map(([key, value]) => `<section><h2>${escape(key)}</h2>${display(value)}</section>`).join('\n');
+    const html = `<!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'; base-uri 'none'; form-action 'none'">
+<title>${escape(record.title)}</title>
+<style>body{font:17px/1.55 system-ui,sans-serif;max-width:72rem;margin:3rem auto;padding:0 1.5rem;color:#18252d;background:#faf9f5}h1{line-height:1.2}h2{font-size:1.2rem;border-bottom:1px solid #b8c8c9;padding-bottom:.3rem}section{margin:2rem 0}dt{font-weight:650;color:#234c54}dd{margin:0 0 .6rem 1.3rem}li{margin:.75rem 0}span{white-space:pre-wrap;overflow-wrap:anywhere}.empty{color:#56656c;font-style:italic}header p{max-width:55rem}</style>
+</head>
+<body>
+<header><p>Research record · experimental 0.1</p><h1>${escape(record.title)}</h1><p>Source research describes possibilities. It does not establish a running integration. The embedded data owns the facts; visible edits require review before continuation.</p></header>
+${sections}
+<script type="application/json" id="n8r-record">${data}</script>
+</body>
+</html>
+`;
+    checkSize(html);
+    return html;
+}
+/** Extract only to verify; no DOM execution and no permissive HTML repair. */
+export function readResearchHtml(html) {
+    checkSize(html);
+    const blocks = [...html.matchAll(/<script type="application\/json" id="n8r-record">([\s\S]*?)<\/script>/g)];
+    if (blocks.length !== 1)
+        fail('$html', 'requires exactly one research data block');
+    const record = decode(blocks[0][1], 'json');
+    if (record.contract !== 'n8r.research/0.1')
+        fail('$html', 'requires research record');
+    if (html.includes('<meta name="n8r-presentation" content="1">')) {
+        const contexts = [...html.matchAll(/<script type="application\/json" id="n8r-context">([\s\S]*?)<\/script>/g)];
+        if (contexts.length !== 1)
+            fail('$html', 'requires exactly one presentation context');
+        const context = decodeJsonValue(contexts[0][1]);
+        if (!context || Object.keys(context).sort().join(',') !== 'dependencies,surface' || !Array.isArray(context.dependencies))
+            fail('$html', 'invalid presentation context');
+        const surface = validateArtefact(context.surface);
+        if (surface.contract !== 'n8r.surface/0.3')
+            fail('$html', 'requires Surface 0.3');
+        const dependencies = context.dependencies.map(validateArtefact);
+        const all = [record, surface, ...dependencies].filter((a, i, items) => {
+            const first = items.findIndex(x => x.id === a.id && x.revision.id === a.revision.id);
+            if (canonical(items[first]) !== canonical(a))
+                fail('$html', 'ambiguous presentation revision');
+            return first === i;
+        });
+        for (const item of all)
+            verifyReferences(item, all);
+        if (renderBundleHtml({ research: record, surface, dependencies }) !== html)
+            fail('$html', 'HTML/data conflict');
+        return record;
+    }
+    if (renderResearchHtml(record) !== html)
+        fail('$html', 'HTML/data conflict; preserve bytes and review the edit before regenerating');
+    return record;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type * from './contracts.js';
+export { validateArtefact, verifyReferences } from './validate.js';
+export { encode, decode } from './codec.js';
+export type { Encoding } from './codec.js';
+export { digest } from './portable.js';
+export { renderResearchHtml, readResearchHtml } from './html.js';
+export { verifySuccessor } from './revisions.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { validateArtefact, verifyReferences } from './validate.js';
+export { encode, decode } from './codec.js';
+export { digest } from './portable.js';
+export { renderResearchHtml, readResearchHtml } from './html.js';
+export { verifySuccessor } from './revisions.js';

package/dist/notes.d.ts

@@ -0,0 +1,52 @@
+export type Evidence = {
+    path: string;
+    digest: string;
+    inspectedAt: string;
+    startLine: number;
+    endLine: number;
+};
+export type NoteContext = {
+    researcher: {
+        version: string;
+        digest: string;
+    };
+    model: string;
+    evidence: Evidence[];
+};
+type Metadata = NoteContext & {
+    version: 1;
+    createdAt: string;
+    source: {
+        name: string;
+        kind: 'file' | 'directory';
+    };
+    predecessor?: {
+        file: string;
+        digest: string;
+    };
+};
+export type Note = {
+    path: string;
+    text: string;
+    digest: string;
+    metadata: Metadata;
+    modifiedAt: string;
+};
+/** Explicitly selected notes may live outside the vault; their folder becomes the save scope. */
+export declare function readNote(path: string): Note;
+/** Local folder metadata only; never infer identity from the latest filename. */
+export declare function latestNote(vault: string, source: string): Note | undefined;
+/** Synchronous bounded host writer. Directory topology must remain stable during each operation. */
+export declare class Notes {
+    readonly directory: string;
+    predecessor: Note | undefined;
+    private topic;
+    private stamps;
+    private source;
+    private sourceKind;
+    constructor(vault: string, source: string, predecessor?: Note);
+    private check;
+    next(): string;
+    save(path: string, markdown: string, context: NoteContext): Note;
+}
+export {};

package/dist/notes.js

@@ -0,0 +1,184 @@
+import fs from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { InspectionError, readBytes } from './settings.js';
+const LIMIT = 256 * 1024;
+const MARKER = '\n<!-- n8r-note-v1 -->\n';
+const namePattern = /^([a-z0-9]+(?:-[a-z0-9]+)*)-(\d{3,})\.md$/;
+const digest = (bytes) => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const slug = (source) => basename(source).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80) || 'source';
+const inside = (path, root) => { const p = relative(root, path); return !p || (p !== '..' && !p.startsWith(`..${sep}`) && !p.startsWith(sep)); };
+function folder(vault, source) { return join(fs.realpathSync(vault), 'research', slug(source)); }
+function validateMetadata(value) {
+    if (!value || value.version !== 1 || !value.source || !['file', 'directory'].includes(value.source.kind)
+        || typeof value.source.name !== 'string' || typeof value.createdAt !== 'string'
+        || typeof value.model !== 'string' || typeof value.researcher?.version !== 'string' || typeof value.researcher?.digest !== 'string'
+        || !Array.isArray(value.evidence) || value.evidence.length > 1000
+        || value.evidence.some((e) => !e || typeof e.path !== 'string' || !/^sha256:[a-f0-9]{64}$/.test(e.digest)
+            || typeof e.inspectedAt !== 'string' || !Number.isSafeInteger(e.startLine) || !Number.isSafeInteger(e.endLine))
+        || (value.predecessor !== undefined && (!namePattern.test(value.predecessor.file) || !/^sha256:[a-f0-9]{64}$/.test(value.predecessor.digest)))) {
+        throw new InspectionError('Invalid working-note metadata; preserve the host footer when editing');
+    }
+}
+/** Explicitly selected notes may live outside the vault; their folder becomes the save scope. */
+export function readNote(path) {
+    path = resolve(path);
+    if (!namePattern.test(basename(path)))
+        throw new InspectionError('Select a numbered working note such as research-001.md');
+    if (fs.lstatSync(path).isSymbolicLink())
+        throw new InspectionError('Note cannot be a symbolic link');
+    path = join(fs.realpathSync(dirname(path)), basename(path));
+    const bytes = readBytes(path, LIMIT);
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new InspectionError('Note is not UTF-8 text');
+    }
+    if (text.includes('\0'))
+        throw new InspectionError('Note contains binary data');
+    const marker = text.lastIndexOf(MARKER);
+    const footer = marker < 0 ? undefined : /^```json\n([\s\S]*?)\n```(?:\n|$)/.exec(text.slice(marker + MARKER.length));
+    if (!footer)
+        throw new InspectionError('Expected an n8r-surface working note with its host metadata footer');
+    let metadata;
+    try {
+        metadata = JSON.parse(footer[1]);
+    }
+    catch {
+        throw new InspectionError('Invalid working-note metadata JSON');
+    }
+    validateMetadata(metadata);
+    return { path, text, digest: digest(bytes), metadata, modifiedAt: fs.statSync(path).mtime.toISOString() };
+}
+/** Local folder metadata only; never infer identity from the latest filename. */
+export function latestNote(vault, source) {
+    const dir = folder(vault, source);
+    const scope = new Notes(vault, source); // validate ancestry, including a replaced research folder
+    scope.next();
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    if (entries.length > 10000)
+        throw new InspectionError('Too many notes; select an explicit filename');
+    const candidates = entries.filter(e => e.isFile() && namePattern.test(e.name))
+        .map(e => ({ path: join(dir, e.name), time: fs.statSync(join(dir, e.name)).mtimeMs }))
+        .sort((a, b) => b.time - a.time || a.path.localeCompare(b.path));
+    return candidates.length ? readNote(candidates[0].path) : undefined;
+}
+/** Synchronous bounded host writer. Directory topology must remain stable during each operation. */
+export class Notes {
+    directory;
+    predecessor;
+    topic;
+    stamps = new Map();
+    source;
+    sourceKind;
+    constructor(vault, source, predecessor) {
+        this.source = fs.realpathSync(source);
+        this.sourceKind = fs.statSync(this.source).isFile() ? 'file' : 'directory';
+        this.directory = predecessor ? dirname(predecessor.path) : folder(vault, this.source);
+        if (this.sourceKind === 'directory' && inside(this.directory, this.source))
+            throw new InspectionError('Notes cannot be saved inside the selected source');
+        this.predecessor = predecessor;
+        this.topic = predecessor ? namePattern.exec(basename(predecessor.path))[1] : 'research';
+        this.check();
+    }
+    check() {
+        const paths = [];
+        for (let p = this.directory;; p = dirname(p)) {
+            paths.unshift(p);
+            if (dirname(p) === p)
+                break;
+        }
+        for (const path of paths) {
+            let stat;
+            try {
+                stat = fs.lstatSync(path);
+            }
+            catch (error) {
+                if (error.code === 'ENOENT' && !this.stamps.has(path))
+                    continue;
+                throw new InspectionError('Note directory changed; reopen before saving');
+            }
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                throw new InspectionError('Note directory is occupied or a symbolic link');
+            const old = this.stamps.get(path);
+            if (old && (old.dev !== stat.dev || old.ino !== stat.ino))
+                throw new InspectionError('Note directory changed; reopen before saving');
+            this.stamps.set(path, { dev: stat.dev, ino: stat.ino });
+        }
+    }
+    next() {
+        this.check();
+        let names;
+        try {
+            names = fs.readdirSync(this.directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                names = [];
+            else
+                throw error;
+        }
+        if (names.length > 10000)
+            throw new InspectionError('Too many notes in this folder');
+        let n = 0;
+        for (const name of names) {
+            const match = namePattern.exec(name);
+            if (match?.[1] === this.topic)
+                n = Math.max(n, Number(match[2]));
+        }
+        if (!Number.isSafeInteger(n + 1))
+            throw new InspectionError('Note numbering limit reached');
+        return join(this.directory, `${this.topic}-${String(n + 1).padStart(3, '0')}.md`);
+    }
+    save(path, markdown, context) {
+        this.check();
+        if (dirname(path) !== this.directory || namePattern.exec(basename(path))?.[1] !== this.topic || path === this.source)
+            throw new InspectionError('Output outside authorized note scope');
+        if (typeof markdown !== 'string' || !markdown.trim() || Buffer.byteLength(markdown) > 192 * 1024 || markdown.includes(MARKER) || markdown.includes('\0'))
+            throw new InspectionError('Invalid or oversized Markdown draft');
+        const unchanged = () => {
+            if (this.predecessor && !readBytes(this.predecessor.path, LIMIT).equals(Buffer.from(this.predecessor.text)))
+                throw new InspectionError('Predecessor changed; reopen the edited note before saving');
+        };
+        unchanged();
+        const metadata = { ...context, version: 1, createdAt: new Date().toISOString(),
+            source: { name: basename(this.source), kind: this.sourceKind },
+            ...(this.predecessor ? { predecessor: { file: basename(this.predecessor.path), digest: this.predecessor.digest } } : {}) };
+        validateMetadata(metadata);
+        const predecessor = metadata.predecessor ? `Predecessor: [${metadata.predecessor.file}](${metadata.predecessor.file}) (${metadata.predecessor.digest}).\n\n` : '';
+        const bytes = Buffer.from(predecessor + markdown.trim() + '\n\n## Host provenance\n\nExperimental working-note metadata; not an AI Surface schema. Source paths are\nrelative to the explicitly selected source; hashes identify bytes, not truth.\n' + MARKER + '```json\n' + JSON.stringify(metadata, null, 2) + '\n```\n');
+        if (bytes.length > LIMIT)
+            throw new InspectionError('Saved note exceeds 256 KiB; narrow the research scope');
+        fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+        this.check();
+        const temporary = join(this.directory, `.note-${randomUUID()}.tmp`);
+        const fd = fs.openSync(temporary, 'wx', 0o600);
+        try {
+            fs.writeFileSync(fd, bytes);
+            fs.fsyncSync(fd);
+            this.check();
+            unchanged();
+            // Publish a complete file without replacing any existing file or symlink.
+            fs.linkSync(temporary, path);
+            const saved = readNote(path);
+            if (saved.digest !== digest(bytes))
+                throw new InspectionError('Saved note readback differs; inspect the output before retrying');
+            this.predecessor = saved;
+            return saved;
+        }
+        finally {
+            fs.closeSync(fd);
+            fs.unlinkSync(temporary);
+        }
+    }
+}

package/dist/portable.d.ts

@@ -0,0 +1,10 @@
+import type { Value } from './contracts.js';
+export declare const MAX_BYTES: number;
+export declare const MAX_DEPTH = 64;
+export declare function fail(path: string, message: string): never;
+export declare function checkSize(text: string): void;
+/** Reject before serialization: never invoke a getter or silently drop a value. */
+export declare function portable(value: unknown, path?: string, ancestors?: Set<object>, depth?: number): asserts value is Value;
+/** Object keys sorted by UTF-16 code units; arrays retain order; no whitespace. */
+export declare function canonical(value: unknown): string;
+export declare function digest(value: unknown): string;

package/dist/portable.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+export const MAX_BYTES = 2 * 1024 * 1024;
+export const MAX_DEPTH = 64;
+export function fail(path, message) { throw new Error(`${path}: ${message}`); }
+export function checkSize(text) {
+    if (Buffer.byteLength(text, 'utf8') > MAX_BYTES)
+        fail('$', 'exceeds 2 MiB limit');
+}
+/** Reject before serialization: never invoke a getter or silently drop a value. */
+export function portable(value, path = '$', ancestors = new Set(), depth = 0) {
+    if (depth > MAX_DEPTH)
+        fail(path, 'exceeds depth 64');
+    if (value === null || typeof value === 'boolean')
+        return;
+    if (typeof value === 'string') {
+        if (!value.isWellFormed())
+            fail(path, 'unpaired Unicode surrogate');
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isSafeInteger(value) || Object.is(value, -0))
+            fail(path, 'requires a safe integer (no negative zero)');
+        return;
+    }
+    if (typeof value !== 'object')
+        fail(path, 'unsupported portable value');
+    if (ancestors.has(value))
+        fail(path, 'object cycle; use identified graph edges');
+    const array = Array.isArray(value);
+    const prototype = Object.getPrototypeOf(value);
+    if (array && prototype !== Array.prototype)
+        fail(path, 'requires a plain array');
+    if (!array && prototype !== Object.prototype && prototype !== null)
+        fail(path, 'requires a plain object');
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(value);
+    if (array && (keys.length !== value.length + 1))
+        fail(path, 'sparse array or extra array properties');
+    ancestors.add(value);
+    for (const key of keys) {
+        if (array && key === 'length')
+            continue;
+        if (typeof key !== 'string')
+            fail(path, 'symbol key');
+        portable(key, path);
+        if (array && (!/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= value.length))
+            fail(path, 'extra array property');
+        const descriptor = descriptors[key];
+        if (!('value' in descriptor) || !descriptor.enumerable)
+            fail(`${path}.${key}`, 'requires enumerable data property');
+        portable(descriptor.value, `${path}.${key}`, ancestors, depth + 1);
+    }
+    ancestors.delete(value);
+}
+/** Object keys sorted by UTF-16 code units; arrays retain order; no whitespace. */
+export function canonical(value) {
+    portable(value);
+    const write = (v) => {
+        if (Array.isArray(v))
+            return `[${v.map(write).join(',')}]`;
+        if (v !== null && typeof v === 'object')
+            return `{${Object.keys(v).sort().map(k => `${JSON.stringify(k)}:${write(v[k])}`).join(',')}}`;
+        return JSON.stringify(v);
+    };
+    const text = write(value);
+    checkSize(text);
+    return text;
+}
+export function digest(value) {
+    return `sha256:${createHash('sha256').update(canonical(value), 'utf8').digest('hex')}`;
+}

package/dist/recent.d.ts

@@ -0,0 +1,9 @@
+export type RecentWork = {
+    id: string;
+    title: string;
+    source: string;
+    path: string;
+    model: string;
+};
+export declare function recentWork(home: string): RecentWork[];
+export declare function rememberWork(home: string, item: RecentWork): void;

package/dist/recent.js

@@ -0,0 +1,71 @@
+/** Local navigation metadata only; never included in portable research artifacts. */
+import fs from 'node:fs';
+import { join, resolve, relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { InspectionError, readBytes } from './settings.js';
+function location(home) {
+    const directory = join(fs.realpathSync(home), '.n8r');
+    try {
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new InspectionError('Recent-work folder is not a regular directory');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    return { directory, file: join(directory, 'recent.json') };
+}
+function valid(item) {
+    return item && ['id', 'title', 'source', 'path', 'model'].every(k => typeof item[k] === 'string' && item[k].length > 0 && item[k].length < 16000)
+        && resolve(item.source) === item.source && resolve(item.path) === item.path;
+}
+export function recentWork(home) {
+    const { file } = location(home);
+    let bytes;
+    try {
+        bytes = readBytes(file, 1024 * 1024);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return [];
+        throw e;
+    }
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new InspectionError('Recent-work list is damaged; saved research is unchanged');
+    }
+    if (!Array.isArray(value) || value.length > 100 || !value.every(valid))
+        throw new InspectionError('Invalid recent-work list; saved research is unchanged');
+    return value;
+}
+export function rememberWork(home, item) {
+    if (!valid(item))
+        throw new InspectionError('Invalid saved-work reference');
+    const { directory, file } = location(home);
+    const rel = relative(item.source, directory);
+    if (!rel || (!rel.startsWith(`..${sep}`) && rel !== '..' && !rel.startsWith(sep)))
+        throw new InspectionError('Recent-work list cannot be written inside the research source');
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const lock = file + '.lock';
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    const temporary = file + '.' + randomUUID();
+    try {
+        const previous = recentWork(home);
+        const next = [item, ...previous.filter(p => p.id !== item.id)].slice(0, 100);
+        fs.writeFileSync(temporary, JSON.stringify(next, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        // Check again while holding our lock; refuse user edits during this save.
+        if (JSON.stringify(recentWork(home)) !== JSON.stringify(previous))
+            throw new InspectionError('Recent-work list changed; saved research is unchanged');
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        fs.closeSync(fd);
+        fs.unlinkSync(lock);
+        if (fs.existsSync(temporary))
+            fs.unlinkSync(temporary);
+    }
+}

package/dist/revisions.d.ts

@@ -0,0 +1,2 @@
+/** Validate a proposed successor; persistence and complete history belong to the host. */
+export declare function verifySuccessor(previous: unknown, next: unknown): void;

package/dist/revisions.js

@@ -0,0 +1,60 @@
+import { validateArtefact } from './validate.js';
+import { canonical, digest, fail } from './portable.js';
+/** Validate a proposed successor; persistence and complete history belong to the host. */
+export function verifySuccessor(previous, next) {
+    const before = validateArtefact(previous), after = validateArtefact(next);
+    if (before.contract !== after.contract || before.id !== after.id)
+        fail('$revision', 'contract/artefact identity changed');
+    const parent = after.revision.parent;
+    if (!parent || parent.id !== before.id || parent.revision !== before.revision.id || parent.digest !== digest(before) || after.revision.id === before.revision.id)
+        fail('$revision', 'parent revision/digest mismatch or reused revision');
+    if (before.contract === 'n8r.surface/0.2' && after.contract === 'n8r.surface/0.2') {
+        if (before.kind !== after.kind)
+            fail('$revision', 'description kind changed');
+        for (const n of after.nodes) {
+            const old = before.nodes.find(x => x.id === n.id);
+            if (old && canonical(old.type) !== canonical(n.type))
+                fail('$revision', 'retained node type changed');
+        }
+        if (before.kind === 'capability' && after.kind === 'capability') {
+            for (const c of after.capabilities) {
+                const old = before.capabilities.find(x => x.id === c.id);
+                if (old && (old.from !== c.from || old.to !== c.to || canonical(old.type) !== canonical(c.type)))
+                    fail('$revision', 'retained capability endpoints/type changed');
+            }
+        }
+        if (before.kind === 'bound' && after.kind === 'bound') {
+            if (before.instance.id !== after.instance.id || before.capability.id !== after.capability.id)
+                fail('$revision', 'instance/capability identity changed');
+            for (const b of after.bindings) {
+                const old = before.bindings.find(x => x.id === b.id);
+                if (old && old.capability !== b.capability)
+                    fail('$revision', 'retained binding slot changed');
+            }
+        }
+    }
+    if (before.contract === 'n8r.surface/0.3' && after.contract === 'n8r.surface/0.3') {
+        if (before.kind !== after.kind)
+            fail('$revision', 'description kind changed');
+        for (const n of after.nodes) {
+            const old = before.nodes.find(x => x.id === n.id);
+            if (old && canonical(old.type) !== canonical(n.type))
+                fail('$revision', 'retained node type changed');
+        }
+        for (const edge of after.relationships) {
+            const old = before.relationships.find(x => x.id === edge.id);
+            if (old && (old.from !== edge.from || old.to !== edge.to || canonical(old.type) !== canonical(edge.type)))
+                fail('$revision', 'retained relationship endpoints/type changed');
+        }
+        if (before.kind === 'bound' && after.kind === 'bound' &&
+            (before.instance.id !== after.instance.id || before.capability.id !== after.capability.id))
+            fail('$revision', 'instance/capability identity changed');
+    }
+    if (before.contract === 'n8r.surface/0.1' && after.contract === 'n8r.surface/0.1') {
+        for (const edge of after.relationships) {
+            const old = before.relationships.find(x => x.id === edge.id);
+            if (old && (old.from !== edge.from || old.to !== edge.to || canonical(old.type) !== canonical(edge.type)))
+                fail(edge.id, 'retained relationship identity has different endpoints/type');
+        }
+    }
+}

package/dist/settings.d.ts

@@ -0,0 +1,23 @@
+/** Escape terminal controls and line/bidi separators in untrusted labels. */
+export declare function line(value: string): string;
+export declare class InspectionError extends Error {
+}
+export declare function problem(error: unknown): string;
+/** Do not block on special files, follow entry symlinks or read unbounded data. */
+export declare function readBytes(path: string, limit: number): Buffer;
+export interface Settings {
+    home: string;
+    file: string;
+    original: Buffer | undefined;
+    data: Record<string, unknown>;
+    vault: string | undefined;
+    root: string;
+    format: 'json' | 'yaml';
+    defaultRoot: boolean;
+    defaultFormat: boolean;
+    runner: boolean;
+    lab: boolean;
+}
+export declare function localPath(value: unknown, home: string, base: string): string;
+export declare function readLocal(path: string, limit: number): string;
+export declare function loadSettings(home?: string): Settings;