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

package/dist/html.js

@@ -0,0 +1,50 @@
+import { decode, encode } from './codec.js';
+import { checkSize, fail } from './portable.js';
+import { validateArtefact } from './validate.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 (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/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,18 @@
+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.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;

package/dist/settings.js

@@ -0,0 +1,100 @@
+import { constants, openSync, closeSync, fstatSync, readSync, lstatSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** Escape terminal controls and line/bidi separators in untrusted labels. */
+export function line(value) {
+    return value.replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, c => `\\u${c.codePointAt(0).toString(16).padStart(4, '0')}`);
+}
+export class InspectionError extends Error {
+}
+export function problem(error) {
+    if (error instanceof InspectionError)
+        return error.message;
+    const code = error?.code;
+    return typeof code === 'string' && /^[A-Z0-9_]+$/.test(code) ? code : 'Read failed';
+}
+/** Do not block on special files, follow entry symlinks or read unbounded data. */
+export function readBytes(path, limit) {
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            throw new InspectionError('Not a regular file');
+        if (stat.size > limit)
+            throw new InspectionError(`File exceeds ${limit} bytes`);
+        const buffer = Buffer.alloc(limit + 1);
+        let bytes = 0;
+        while (bytes < buffer.length) {
+            const count = readSync(fd, buffer, bytes, buffer.length - bytes, null);
+            if (!count)
+                break;
+            bytes += count;
+        }
+        if (bytes > limit)
+            throw new InspectionError(`File exceeds ${limit} bytes`);
+        return buffer.subarray(0, bytes);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function settings(text, home, file) {
+    let data = { version: 1 };
+    if (text !== undefined) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new InspectionError('Invalid JSON; repair the existing file');
+        }
+    }
+    if (!object(data) || data.version !== 1)
+        throw new InspectionError('Expected settings object with version 1');
+    const path = localPath(data.artefactRoot === undefined ? '~/n8r/artefacts' : data.artefactRoot, home, dirname(file));
+    const vault = data.vaultRoot === undefined ? undefined : localPath(data.vaultRoot, home, dirname(file));
+    const format = data.surfaceFormat === undefined ? 'json' : data.surfaceFormat;
+    if (format !== 'json' && format !== 'yaml')
+        throw new InspectionError('surfaceFormat must be json or yaml');
+    for (const key of ['runner', 'lab']) {
+        if (data[key] !== undefined && data[key] !== null && !object(data[key]))
+            throw new InspectionError(`${key} must be an object or null`);
+    }
+    return {
+        home, file, original: undefined, data, vault, root: path,
+        format, defaultRoot: data.artefactRoot === undefined, defaultFormat: data.surfaceFormat === undefined,
+        runner: object(data.runner), lab: object(data.lab)
+    };
+}
+export function localPath(value, home, base) {
+    if (typeof value !== 'string' || !value.trim() || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value) || /^[a-z][a-z0-9+.-]*:/i.test(value) || (value.startsWith('~') && !value.startsWith('~/'))) {
+        throw new InspectionError('Expected a local path, optionally starting with ~/');
+    }
+    return value.startsWith('~/') ? resolve(home, value.slice(2)) : resolve(base, value);
+}
+export function readLocal(path, limit) {
+    return readBytes(path, limit).toString('utf8');
+}
+export function loadSettings(home = homedir()) {
+    const file = join(home, '.n8r/n8r-surface.json');
+    let original;
+    try {
+        original = readBytes(file, 64 * 1024);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        // A dangling symlink is not an absent settings file.
+        try {
+            lstatSync(file);
+            throw new InspectionError('Settings is not a regular file');
+        }
+        catch (entryError) {
+            if (entryError.code !== 'ENOENT')
+                throw entryError;
+        }
+    }
+    return { ...settings(original?.toString('utf8'), home, file), original };
+}

package/dist/setup.d.ts

@@ -0,0 +1,9 @@
+import { type Settings } from './settings.js';
+export declare function chooseVault(value: string, home: string, cwd: string): string;
+/** Read-only validation: missing folders need consent, occupied paths are errors. */
+export declare function inspectVault(root: string): {
+    root: string;
+    missing: boolean;
+};
+/** Called only after explicit acceptance. See startup.md for the writer boundary. */
+export declare function saveSetup(snapshot: Settings, selected: string, cwd: string): string;