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

package/dist/surface-instructions.d.ts

@@ -0,0 +1,2 @@
+/** Content fields mirror the existing experimental contracts; host metadata is omitted. */
+export declare const surfaceInstructions = "\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";

package/dist/surface-instructions.js

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

package/dist/surface-store.d.ts

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

package/dist/surface-store.js

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

package/dist/validate.d.ts

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

package/dist/validate.js

@@ -0,0 +1,184 @@
+import { canonical, digest, fail, portable } from './portable.js';
+const text = (v, p) => { if (typeof v !== 'string' || !v.trim())
+    fail(p, 'requires nonempty string'); };
+const match = (pattern, label) => (v, p) => { text(v, p); if (!pattern.test(v))
+    fail(p, label); };
+const id = match(/^[a-z][a-z0-9+.-]*:[^\s]+$/i, 'requires namespaced identifier');
+const token = match(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'requires revision/version token');
+const hash = match(/^sha256:[a-f0-9]{64}$/, 'requires SHA-256 digest');
+const time = (v, p) => {
+    text(v, p);
+    if (!/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ$/.test(v) || !Number.isFinite(Date.parse(v)) || new Date(v).toISOString() !== v.replace('Z', '.000Z'))
+        fail(p, 'requires real UTC timestamp with seconds');
+};
+const oneOf = (...values) => (v, p) => { if (!values.includes(v))
+    fail(p, `expected ${values.join('|')}`); };
+const array = (check, min = 0) => (v, p) => {
+    if (!Array.isArray(v) || v.length < min)
+        fail(p, `requires array with at least ${min} entries`);
+    v.forEach((x, i) => check(x, `${p}[${i}]`));
+};
+function object(v, p) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v))
+        fail(p, 'requires object');
+    return v;
+}
+const shape = (required, optional = {}) => (v, p) => {
+    const data = object(v, p);
+    for (const [key, check] of Object.entries(required)) {
+        if (!Object.hasOwn(data, key))
+            fail(`${p}.${key}`, 'required');
+        check(data[key], `${p}.${key}`);
+    }
+    for (const key of Object.keys(data)) {
+        if (Object.hasOwn(required, key))
+            continue;
+        if (!Object.hasOwn(optional, key))
+            fail(`${p}.${key}`, 'unsupported field; preserve additions in extensions');
+        optional[key](data[key], `${p}.${key}`);
+    }
+};
+const dictionary = (keyCheck, valueCheck) => (v, p) => {
+    for (const [k, value] of Object.entries(object(v, p))) {
+        keyCheck(k, `${p} key`);
+        valueCheck(value, `${p}.${k}`);
+    }
+};
+const value = (v, p) => portable(v, p);
+const state = oneOf('known', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope');
+const ref = shape({ id, revision: token, digest: hash });
+const revision = shape({ id: token, parent: (v, p) => { if (v !== null)
+        ref(v, p); }, createdAt: time, author: text, reason: text });
+const common = { id, title: text, revision, scope: text, extensions: dictionary(id, value) };
+const evidence = shape({ source: id, locator: text });
+const location = (v, p) => {
+    text(v, p);
+    const s = v;
+    if (/^https?:\/\//.test(s)) {
+        const url = new URL(s);
+        if (url.username || url.password)
+            fail(p, 'credentials in source URL');
+        return;
+    }
+    if (s.startsWith('urn:')) {
+        id(v, p);
+        return;
+    }
+    if (s.startsWith('/') || /[\\:?#%]/.test(s) || s.split('/').some(part => !part || part === '.' || part === '..'))
+        fail(p, 'requires portable relative path or http(s)/urn reference');
+};
+const finding = (v, p) => {
+    shape({ id, subject: id, property: text, state: oneOf('known', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting'), note: text,
+        claims: array(shape({ value, evidence: array(evidence, 1) })) })(v, p);
+    const f = v;
+    const distinct = new Set(f.claims.map(c => canonical(c.value))).size;
+    if ((f.state === 'known' || f.state === 'absent') && distinct !== 1)
+        fail(p, 'known/absent requires one agreed claim value');
+    if (f.state === 'conflicting' && distinct < 2)
+        fail(p, 'conflicting requires differing sourced claims');
+    if (['unknown', 'omitted', 'redacted', 'out-of-scope'].includes(f.state) && f.claims.length)
+        fail(p, 'non-value state must not carry claims');
+};
+const research = shape({
+    ...common, contract: oneOf('n8r.research/0.1'),
+    sources: array(shape({ id, location, version: text, digest: hash, inspectedAt: time,
+        coverage: array(shape({ path: text, status: oneOf('inspected', 'missing', 'unreadable', 'excluded', 'truncated', 'unsupported'), note: text }), 1) })),
+    findings: array(finding),
+    alternatives: array(shape({ id, title: text, findings: array(id), requirements: array(text) })),
+    decisions: array(shape({ id, alternative: id, choice: oneOf('selected', 'rejected', 'deferred'), reason: text, by: text, at: time })),
+    questions: array(shape({ id, text, findings: array(id) })),
+    notes: array(shape({ by: text, at: time, text }))
+});
+const fact = (v, p) => {
+    shape({ state, note: text }, { value })(v, p);
+    const f = object(v, p);
+    if ((f.state === 'known') !== Object.hasOwn(f, 'value'))
+        fail(p, 'only known facts require a value');
+};
+const entity = { id, type: shape({ vocabulary: id, term: text }), attributes: dictionary(text, fact),
+    basis: array(shape({ record: id, revision: token, items: array(id, 1) })), requirements: array(id) };
+const surface = shape({
+    ...common, contract: oneOf('n8r.surface/0.1'), kind: oneOf('definition'), records: array(ref),
+    vocabularies: array(shape({ id, version: token })),
+    nodes: array(shape({ ...entity, label: text })),
+    relationships: array(shape({ ...entity, from: id, to: id, claim: oneOf('declared') })),
+    requirements: array(shape({ id, kind: oneOf('secret', 'resource', 'configuration'), description: text, state })),
+    coverage: array(text), gaps: array(text)
+});
+function unique(ids, p) {
+    if (new Set(ids).size !== ids.length)
+        fail(p, 'duplicate identity/reference');
+    return new Set(ids);
+}
+function references(ids, available, p) {
+    unique(ids, p);
+    for (const item of ids)
+        if (!available.has(item))
+            fail(p, `unresolved reference ${item}`);
+}
+export function validateArtefact(input) {
+    canonical(input); // checks portable values, depth and logical size before field access
+    const data = object(input, '$');
+    if (data.contract === 'n8r.research/0.1') {
+        research(input, '$');
+        const r = input;
+        unique([r.id, ...r.sources.map(x => x.id), ...r.findings.map(x => x.id), ...r.alternatives.map(x => x.id), ...r.decisions.map(x => x.id), ...r.questions.map(x => x.id)], '$');
+        const sources = new Set(r.sources.map(x => x.id)), findings = new Set(r.findings.map(x => x.id)), alternatives = new Set(r.alternatives.map(x => x.id));
+        for (const f of r.findings)
+            for (const c of f.claims)
+                for (const e of c.evidence)
+                    references([e.source], sources, f.id);
+        for (const a of [...r.alternatives, ...r.questions])
+            references(a.findings, findings, a.id);
+        for (const d of r.decisions)
+            references([d.alternative], alternatives, d.id);
+        unique(r.decisions.map(d => d.alternative), '$.decisions'); // one current decision per option; old decisions stay in prior revisions
+    }
+    else if (data.contract === 'n8r.surface/0.1') {
+        surface(input, '$');
+        const s = input;
+        unique([s.id, ...s.nodes.map(x => x.id), ...s.relationships.map(x => x.id), ...s.requirements.map(x => x.id)], '$');
+        const nodes = new Set(s.nodes.map(x => x.id)), vocab = unique(s.vocabularies.map(x => x.id), '$.vocabularies');
+        const requirements = new Set(s.requirements.map(x => x.id));
+        const records = unique(s.records.map(x => JSON.stringify([x.id, x.revision])), '$.records');
+        for (const e of [...s.nodes, ...s.relationships]) {
+            references([e.type.vocabulary], vocab, e.id);
+            references(e.requirements, requirements, e.id);
+            for (const b of e.basis) {
+                references([JSON.stringify([b.record, b.revision])], records, e.id);
+                unique(b.items, e.id);
+            }
+        }
+        for (const e of s.relationships) {
+            references([e.from], nodes, e.id);
+            references([e.to], nodes, e.id);
+        }
+    }
+    else
+        fail('$.contract', 'unsupported contract/version');
+    const a = input;
+    if (a.revision.parent && (a.revision.parent.id !== a.id || a.revision.parent.revision === a.revision.id))
+        fail('$.revision.parent', 'requires earlier revision of the same artefact');
+    return a;
+}
+/** Explicit offline bundle verification. Missing external context is an error here. */
+export function verifyReferences(input, context) {
+    const a = validateArtefact(input);
+    const records = context.map(validateArtefact);
+    unique(records.map(r => JSON.stringify([r.id, r.revision.id])), '$context');
+    if (a.contract !== 'n8r.surface/0.1')
+        return;
+    for (const ref of a.records) {
+        const r = records.find(x => x.id === ref.id && x.revision.id === ref.revision);
+        if (!r || r.contract !== 'n8r.research/0.1')
+            fail(ref.id, 'research revision unavailable');
+        if (digest(r) !== ref.digest)
+            fail(ref.id, 'research digest mismatch');
+        const items = new Set([...r.findings, ...r.alternatives, ...r.decisions, ...r.questions].map(x => x.id));
+        for (const e of [...a.nodes, ...a.relationships])
+            for (const b of e.basis) {
+                if (b.record === ref.id && b.revision === ref.revision)
+                    references(b.items, items, e.id);
+            }
+    }
+}

package/docs/n8r-surface/README.md

@@ -0,0 +1,133 @@
+# n8r-surface capability map
+
+`n8r-surface` is the proposed standalone tool for researching software and
+authoring partial AI Surface Model descriptions with a human. Researcher is its
+shared discovery skill. The tool can run independently and later exchange work
+with n8r-labs.
+
+The [shareable skill](researcher-skill.md) has bounded existing-harness evidence.
+On 5 November 2026 the user prioritized standalone AI integration, then complete
+save/reopen/continue verification, then npm distribution. Later n8r-labs adaptation
+uses the same core in that separate repository.
+
+**Status, 5 November 2026:** #15 supplies experimental artefact contracts,
+JSON/YAML codecs, HTML ownership checks and synthetic cases. The command implements
+[bare startup and vault setup](startup.md), plus a
+[bounded Codex conversation](codex-research-verification.md). Saved continuation,
+complete structured research and Lab integration remain outstanding.
+[Skill verification](researcher-skill-verification.md) distinguishes instruction
+trials from the pending Work-mode lifecycle trial. This is unreleased work;
+the remaining map describes intended capabilities.
+
+- [Experimental contracts and checks](contracts.md)
+- [Command intent, outcomes and verification](command-outcomes.md)
+- [Library verification evidence and remaining limits](verification.md)
+- [Bare-startup installed-command evidence](startup-verification.md)
+- [Synthetic acceptance cases](../../examples/researcher/README.md)
+- [Host boundary and Lab review](host-contract.md)
+- [Implementation decisions](implementation-decisions.md)
+- [Next work and critical path](critical-path.md)
+- [Design requirements and open choices](design.md)
+- [Tracking issue #13](https://github.com/injectionator/n8r-surface/issues/13)
+- [Map and planning issue #14](https://github.com/injectionator/n8r-surface/issues/14)
+
+## Capability map
+
+The diagram shows the intended capabilities across hosts, not the delivery order.
+The current skill produces working notes; structured artefacts remain later work.
+
+```mermaid
+flowchart TD
+    Sources[Repository, folder or supplied documents] --> Read[Scoped source reading]
+    Human[Human questions and choices] --> Researcher[Researcher shared skill]
+    Read --> Researcher
+
+    subgraph Hosts[Entry points]
+        CLI[n8r-surface CLI]
+        Chat[Skill in a supported chat harness]
+    end
+    CLI --> Researcher
+    Chat --> Researcher
+    AI[One supported AI runner per host] --> Researcher
+    MoreAI[Additional AI runners] -.-> AI
+    Setup[Local setup and preferences] --> CLI
+
+    Researcher --> Record[HTML research record]
+    Record --> Compose[Select and refine a composition]
+    Human --> Compose
+    Compose --> Model[Partial AI Surface Model description]
+    Model --> JSON[JSON encoding]
+    Model --> YAML[YAML encoding]
+    Model -.-> Other[MessagePack and other mappings]
+
+    Record --> Corpus[Configurable artefact folder and recoverable revisions]
+    JSON --> Corpus
+    YAML --> Corpus
+    Corpus --> Resume[Find, read and continue saved work]
+    Resume --> Researcher
+
+    Corpus -.-> Exchange[Explicit import, export and handoff]
+    Exchange -.-> Lab[n8r-labs application: separate project]
+    Lab -.-> Exchange
+    Lab -.-> Researcher
+```
+
+The AI runner and the destination for results are independent choices. A user
+can research locally with their chosen supported AI, save files and later send
+selected work to a Lab. A Lab connection is optional for standalone authoring.
+
+## Delivery boundaries
+
+| Capability | Delivery position | Evidence required |
+| --- | --- | --- |
+| HTML research record and partial graph contract | Experimental implementation: [#15](https://github.com/injectionator/n8r-surface/issues/15) | Synthetic examples have explicit sources, decisions, gaps and stable references. |
+| JSON and YAML representations | Codec and contract in #15; AI-authored output in #17 | Supported meanings survive conversion, including relationship attributes and unknowns. |
+| TypeScript CLI with npm/npx distribution | Agreed; implement in #16 | Installed package and bundled assets work on supported Node.js versions without the source checkout or Bun. |
+| Startup, source access and safe artefact tools | Paused remaining work: [#16](https://github.com/injectionator/n8r-surface/issues/16) | Setup, path handling, conflict detection and recovery work in temporary folders. |
+| Researcher shared skill | First: [#17](https://github.com/injectionator/n8r-surface/issues/17) | Installed skill invocation, evidence-backed notes, human correction and save/reopen. |
+| Standalone CLI runner | After skill and Lab adaptation | Real discovery, human correction, guarded save/resume and model output work without a Lab. |
+| ChatGPT desktop / Work with supplied sources | First lifecycle-test host, in #17 | The same core skill produces usable records and descriptions in the actual host. |
+| More AI runners and external harnesses | Later | Each adapter has demonstrated authentication, tool use and continuation. |
+| Standalone executables | Later distribution option | Each supported platform runs the packaged tool and required assets without a separate Node.js installation. |
+| MessagePack and additional encodings | Later, when a consumer needs them | A bounded mapping preserves meanings or reports unsupported information. |
+| Researcher in n8r-labs and artefact exchange | Application stage after the skill trial, before standalone CLI | The application uses the versioned core and passes shared import/continuation cases. |
+| Optional remote Researcher execution | Later integration | Source access, authentication and session scope are demonstrated against a named endpoint version. |
+| Rich editing, automatic synchronisation and advanced corpus search | Outside the first path | A concrete use case justifies extending the simple folder workflow. |
+
+## Repository ownership
+
+This repository owns the standalone CLI, portable Researcher skill, artefact
+contracts, model encodings and consumer-side integration. The AI Surface Model
+remains the one model; the CLI name does not rename it.
+
+The n8r-labs project owns its application assistant, attachment UI, source access,
+Lab sessions, storage, permissions and API/MCP endpoints. This repository
+maintains the versioned Researcher core, artefact contracts and shared examples.
+The application later consumes an identified revision through its own adapters;
+it does not need to host the CLI or adopt its local folder layout.
+
+Keep the [compatibility contract](design.md#compatibility-contract) current as
+the tool develops. Review Lab requirements during #15 and carry the same
+acceptance examples into application integration. Compatibility remains a goal
+until a named application version passes those cases. Do not copy private
+application prompts or operational records here.
+
+## Keeping the map useful
+
+Issue #13 is the overview, this page is the capability map, and
+[critical-path.md](critical-path.md) names the next delivery gate. Detailed
+requirements live in [design.md](design.md); implementation issues carry their
+own acceptance checks.
+
+Update these documents in the PR that changes a capability or delivery decision.
+Record implemented behaviour only with its verification evidence. Keep later
+ideas on this map until they are ready to become bounded issues. A draft PR,
+passing fixture checks and a working live integration are distinct states.
+
+Use [State X → Input Y → verified Outcome Z](command-outcomes.md) as the acceptance
+structure for each command increment. Attempt and repeat the actual product path,
+and verify changed state independently. The current fixture/library checks do not
+establish a successful repository-research command.
+
+Related: [model overview](../../README.md), [draft concepts](../../spec/README.md),
+[model roadmap](../roadmap.md), [interoperability](../interoperability.md).

package/docs/n8r-surface/codex-research-transcript.md

@@ -0,0 +1,51 @@
+# Installed Codex conversation transcript
+
+Agent rehearsal, 5 November 2026. Synthetic source only; the displayed absolute
+source path is replaced with `<selected-source>`. Other conversation text is
+retained. This is not human acceptance. See [environment and readback](codex-research-verification.md).
+
+```text
+Research source: <selected-source>/lumen-guide.md (one file)
+Inspected source text and your messages will be sent to OpenAI through Codex using ChatGPT sign-in.
+Source access is read-only. Saving and reopening are not available yet.
+Start research with OpenAI using Codex ChatGPT sign-in? [y/N] y
+
+Connecting to Codex…
+Connected: ChatGPT sign-in; model gpt-6-astra.
+Researcher 0.1.8; sha256:8af29c3073df9b8210a7dd94ced9700379b0a98f76bd3a2902f9430b93c98a2a
+Ask about your source. /exit ends the chat; Ctrl-C cancels.
+You> Describe the AI-relevant components and connections in the supplied source, citing file lines and distinguishing selected connections from options. Keep it concise.
+
+I’m using `n8r-surface:research 0.1.8` to map the supplied source, separating selected connections from documented options.
+[source_list] .
+[source_read] lumen-guide.md sha256:98d3374c79c166b37f0debb4ffb5e457eda1385dd7847b042cbad674cac98693
+## Partial AI Surface
+
+Scope: fictional **Lumen Desk**, guide revision `fixture-1`; not a real installation (`lumen-guide.md:1–4`).
+
+| Connection | Status and purpose | Evidence |
+|---|---|---|
+| Lumen Desk → inference endpoint | **Declared configured:** generates summaries. Model and version unspecified. | `lumen-guide.md:8–9` |
+| Lumen Desk → external OIDC service | **Supported option**, not an established selection: identity service. | `lumen-guide.md:9` |
+| Lumen Desk → archive service | **Delivery option:** summary documents and audit events use separate HTTP routes on one service. Schema/authentication require agreement; no tested Harbor Archive integration. Document batches capped at 10. | `lumen-guide.md:13–16` |
+| Archive → callback receiver | **Optional, disabled until selected and configured:** receives archive notifications. Validation, retries and tested protocol unspecified. | `lumen-guide.md:20–22` |
+
+**Limits:** Input sources and processing steps before inference are unknown. No deployment or runtime observations establish selected installation connections or exercised behavior (`lumen-guide.md:26–28`).
+
+Entire supplied file inspected, without truncation. SHA-256: `98d3374c79c166b37f0debb4ffb5e457eda1385dd7847b042cbad674cac98693`.
+
+Research stays in this conversation; no save capability is available.
+You> For this investigation I choose not to use external OIDC. Retain that as my decision, not a change to the guide. Which authentication facts remain unknown?
+
+**Human decision — 2026-11-05:** External OIDC is not selected for this investigation. The guide still describes it as a supported option (`lumen-guide.md:9`).
+
+**Authentication facts still unknown:**
+- **Lumen user access:** whether authentication is required and what, if anything, replaces external OIDC.
+- **Inference endpoint:** authentication mechanism and caller identity; the guide only declares a configured endpoint (`lumen-guide.md:8–9`).
+- **Archive delivery, if selected:** authentication configuration and service identity remain unspecified and require agreement (`lumen-guide.md:13–15`).
+- **Callbacks, if enabled:** sender authentication and notification validation are unspecified; callbacks remain optional (`lumen-guide.md:20–22`).
+- **Effective runtime configuration:** no deployment or runtime observations are supplied (`lumen-guide.md:26–28`).
+
+Not selecting OIDC does **not** establish that access is unauthenticated. Your decision is retained here separately from source facts.
+You> /exit
+```