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

package/dist/validate.js

@@ -0,0 +1,482 @@
+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}`);
+}
+// Inspect only a data descriptor; never invoke an untrusted getter to dispatch.
+function isDescription(input) {
+    return input !== null && typeof input === 'object' &&
+        ['n8r.surface/0.2', 'n8r.surface/0.3'].includes(Object.getOwnPropertyDescriptor(input, 'contract')?.value);
+}
+export function validateArtefact(input) {
+    try {
+        return validate(input);
+    }
+    catch (error) {
+        if (isDescription(input))
+            fail('$description', 'invalid structure, identity, state or reference');
+        throw error;
+    }
+}
+function validate(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 if (data.contract === 'n8r.surface/0.2') {
+        validateDescription(input);
+    }
+    else if (data.contract === 'n8r.surface/0.3') {
+        validateGraph(input);
+    }
+    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) {
+    try {
+        verifyContext(input, context);
+    }
+    catch (error) {
+        if (isDescription(input))
+            fail('$description', 'invalid or unavailable evidence, capability or exclusive selection');
+        throw error;
+    }
+}
+function verifyContext(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.2' || a.contract === 'n8r.surface/0.3') {
+        verifyDescriptionContext(a, records);
+        return;
+    }
+    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);
+            }
+    }
+}
+const basis = shape({ record: id, revision: token, items: array(id, 1) });
+const descriptionType = shape({ vocabulary: id, term: text });
+const descriptionCommon = {
+    ...common, contract: oneOf('n8r.surface/0.2'), extensions: shape({}),
+    records: array(ref), vocabularies: array(shape({ id, version: token })),
+    nodes: array(shape({ id, label: text, type: descriptionType })),
+    coverage: array(text), gaps: array(text)
+};
+const capabilityShape = shape({
+    ...descriptionCommon, kind: oneOf('capability'),
+    capabilities: array(shape({ id, from: id, to: id, type: descriptionType,
+        state: oneOf('possible', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting'),
+        basis: array(basis), conditions: array(text), note: text })),
+    exclusiveGroups: array(shape({ id, members: array(id, 2) }))
+});
+const boundShape = shape({
+    ...descriptionCommon, kind: oneOf('bound'), capability: ref,
+    instance: shape({ id, label: text }),
+    bindings: array(shape({ id, capability: id,
+        state: oneOf('configured', 'unknown', 'omitted', 'redacted', 'out-of-scope', 'conflicting'),
+        claims: array(shape({ target: id, basis: array(basis, 1) })), decisions: array(basis), note: text }))
+});
+function descriptionBases(a) {
+    return a.kind === 'capability' ? a.capabilities.flatMap(c => c.basis) :
+        a.bindings.flatMap(b => [...b.decisions, ...b.claims.flatMap(c => c.basis)]);
+}
+function validateDescription(input) {
+    const data = object(input, '$');
+    (data.kind === 'capability' ? capabilityShape : boundShape)(input, '$');
+    const a = input;
+    const entries = a.kind === 'capability' ? [...a.capabilities, ...a.exclusiveGroups] : a.bindings;
+    unique([a.id, ...a.nodes.map(n => n.id), ...entries.map(e => e.id), ...(a.kind === 'bound' ? [a.instance.id] : [])], '$');
+    const nodes = new Set(a.nodes.map(n => n.id));
+    const vocab = unique(a.vocabularies.map(v => v.id), '$.vocabularies');
+    const records = unique(a.records.map(r => JSON.stringify([r.id, r.revision])), '$.records');
+    for (const n of a.nodes)
+        references([n.type.vocabulary], vocab, '$.nodes');
+    for (const b of descriptionBases(a)) {
+        references([JSON.stringify([b.record, b.revision])], records, '$.basis');
+        unique(b.items, '$.basis.items');
+    }
+    if (a.kind === 'capability') {
+        for (const c of a.capabilities) {
+            references([c.from], nodes, '$.capabilities.from');
+            references([c.to], nodes, '$.capabilities.to');
+            references([c.type.vocabulary], vocab, '$.capabilities.type');
+            if (['possible', 'absent', 'conflicting'].includes(c.state) && !c.basis.length)
+                fail('$', 'evidence required');
+        }
+        for (const group of a.exclusiveGroups)
+            references(group.members, new Set(a.capabilities.map(c => c.id)), '$.exclusiveGroups');
+    }
+    else {
+        unique(a.bindings.map(b => b.capability), '$.bindings.capability');
+        for (const b of a.bindings) {
+            const count = b.claims.length;
+            if (b.state === 'configured' ? count !== 1 : b.state === 'conflicting' ? count < 2 : count !== 0)
+                fail('$', 'state/claims mismatch');
+            references(b.claims.map(c => c.target), nodes, '$.bindings.targets');
+        }
+    }
+}
+function verifyDescriptionContext(a, context) {
+    const research = a.records.map(ref => {
+        const r = context.find(r => r.id === ref.id && r.revision.id === ref.revision);
+        if (!r || r.contract !== 'n8r.research/0.1' || digest(r) !== ref.digest)
+            fail('$', 'research revision/digest unavailable');
+        return r;
+    });
+    const items = (bases, decisions = false) => bases.flatMap(b => {
+        const r = research.find(r => r.id === b.record && r.revision.id === b.revision);
+        return b.items.map(id => {
+            const item = (decisions ? r.decisions : r.findings).find(f => f.id === id);
+            if (!item)
+                fail('$', 'wrong or missing evidence item kind');
+            return item;
+        });
+    });
+    const findings = (bases) => items(bases);
+    if (a.contract === 'n8r.surface/0.3')
+        verifyRelationshipDetails(a, research);
+    const verifySupport = (c) => {
+        const fs = findings(c.basis);
+        if (fs.some(f => f.subject !== c.from || f.property !== 'supports'))
+            fail('$', 'capability evidence subject/property mismatch');
+        if (c.state === 'possible' && (!fs.length || fs.some(f => f.state !== 'known' || f.claims.some(cl => cl.value !== c.to))))
+            fail('$', 'possible requires supported target evidence');
+        if (c.state === 'absent' && (!fs.length || fs.some(f => f.state !== 'absent' || f.claims.some(cl => cl.value !== c.to))))
+            fail('$', 'absent requires scoped absence evidence');
+        if (c.state === 'conflicting' && !fs.some(f => f.state === 'conflicting'))
+            fail('$', 'conflicting requires conflicting finding');
+    };
+    if (a.kind === 'capability') {
+        for (const c of capabilityEdges(a))
+            verifySupport(c);
+        return;
+    }
+    const ref = a.capability;
+    const c = context.find(c => c.id === ref.id && c.revision.id === ref.revision);
+    if (!c || (c.contract !== 'n8r.surface/0.2' && c.contract !== 'n8r.surface/0.3') || c.contract !== a.contract || c.kind !== 'capability' || digest(c) !== ref.digest)
+        fail('$', 'capability revision/digest unavailable');
+    verifyDescriptionContext(c, context);
+    // A shared node ID denotes the same component; an instance is a distinct identity.
+    if ([c.id, ...c.nodes.map(n => n.id), ...capabilityEdges(c).map(e => e.id)].includes(a.instance.id))
+        fail('$', 'instance identity reused');
+    for (const n of a.nodes) {
+        const old = c.nodes.find(x => x.id === n.id);
+        if (old && canonical(old.type) !== canonical(n.type))
+            fail('$', 'shared component type changed');
+    }
+    if (a.contract === 'n8r.surface/0.3') {
+        for (const edge of a.relationships) {
+            const base = capabilityEdges(c).find(x => x.id === edge.id);
+            if (!base || edge.from !== base.from || edge.to !== base.to || canonical(edge.type) !== canonical(base.type))
+                fail('$', 'relationship differs from pinned Capability');
+            verifySupport({ ...edge, state: base.state });
+        }
+    }
+    for (const b of boundBindings(a)) {
+        const capability = capabilityEdges(c).find(c => c.id === b.capability);
+        if (!capability)
+            fail('$', 'unknown capability');
+        if (b.state === 'configured' && capability.state !== 'possible')
+            fail('$', 'configured requires established possibility');
+        items(b.decisions, true);
+        const targets = new Set(b.claims.map(cl => cl.target));
+        if (b.claims.length) {
+            // Do not allow an author to hide contrary evidence by omitting a basis item.
+            // Only this Bound snapshot's records apply; the pinned Capability may use
+            // older research revisions which must not override the current binding.
+            const matching = research.flatMap(r => r.findings).filter(f => f.subject === a.instance.id && f.property === b.capability &&
+                ['known', 'conflicting'].includes(f.state));
+            for (const f of matching) {
+                if (f.claims.some(cl => typeof cl.value !== 'string' || !targets.has(cl.value)) ||
+                    (b.state === 'configured' && f.state === 'conflicting'))
+                    fail('$', 'omitted contradictory configuration evidence');
+            }
+        }
+        for (const claim of b.claims) {
+            const fs = findings(claim.basis);
+            for (const f of fs) {
+                if (f.subject !== a.instance.id || f.property !== b.capability ||
+                    !['known', 'conflicting'].includes(f.state) ||
+                    !f.claims.some(cl => cl.value === claim.target) ||
+                    f.claims.some(cl => typeof cl.value !== 'string' || !targets.has(cl.value)))
+                    fail('$', 'binding evidence mismatch or suppressed conflict');
+                if (b.state === 'configured' && f.state !== 'known')
+                    fail('$', 'conflict cannot establish configured');
+            }
+        }
+    }
+    for (const group of c.exclusiveGroups) {
+        if (boundBindings(a).filter(b => b.state === 'configured' && group.members.includes(b.capability)).length > 1)
+            fail('$', 'exclusive capabilities configured together');
+    }
+}
+function capabilityEdges(a) {
+    return a.contract === 'n8r.surface/0.3' ? a.relationships : a.capabilities;
+}
+function boundBindings(a) {
+    return a.contract === 'n8r.surface/0.3' ? a.relationships.map(e => ({ id: e.id, capability: e.id, ...e.binding })) : a.bindings;
+}
+const configLocation = (v, p) => {
+    text(v, p);
+    const s = v;
+    if (s.startsWith('/') || /[\\:?#%]/.test(s) || s.split('/').some(part => !part || part === '.' || part === '..'))
+        fail(p, 'requires safe relative documentation location');
+};
+const configReference = shape({ owner: id, mechanism: oneOf('environment-variable', 'file-key', 'argument', 'admin-setting', 'code'), key: text, location: configLocation });
+const detailShape = (check) => (v, p) => {
+    shape({ state: oneOf('known', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting'),
+        claims: array(shape({ value: check, basis: array(basis, 1) })), note: text })(v, p);
+    const d = v;
+    const count = d.claims.length;
+    if (d.state === 'known' || d.state === 'absent') {
+        if (count !== 1)
+            fail(p, 'known/absent requires one evidenced claim');
+    }
+    else if (d.state === 'conflicting') {
+        if (count < 2 || new Set(d.claims.map(c => canonical(c))).size !== count)
+            fail(p, 'conflicting requires distinct evidenced claims');
+    }
+    else if (count)
+        fail(p, 'non-value state cannot carry claims');
+};
+const sharedRelationship = { id, from: id, to: id, type: descriptionType,
+    basis: array(basis), conditions: array(text), note: text,
+    purpose: detailShape(text), integration: detailShape(text), configuration: detailShape(array(configReference)) };
+const bindingAnnotation = shape({
+    state: oneOf('configured', 'unknown', 'omitted', 'redacted', 'out-of-scope', 'conflicting'),
+    claims: array(shape({ target: id, basis: array(basis, 1) })), decisions: array(basis), note: text
+});
+const graphCommon = { ...descriptionCommon, contract: oneOf('n8r.surface/0.3') };
+const capabilityGraphShape = shape({ ...graphCommon, kind: oneOf('capability'),
+    relationships: array(shape({ ...sharedRelationship, state: oneOf('possible', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting') })),
+    exclusiveGroups: array(shape({ id, members: array(id, 2) })) });
+const boundGraphShape = shape({ ...graphCommon, kind: oneOf('bound'), capability: ref, instance: shape({ id, label: text }),
+    relationships: array(shape({ ...sharedRelationship, binding: bindingAnnotation })) });
+const detailNames = ['purpose', 'integration', 'configuration'];
+function validateGraph(input) {
+    const data = object(input, '$');
+    (data.kind === 'capability' ? capabilityGraphShape : boundGraphShape)(input, '$');
+    const a = input;
+    // Reuse the bounded 0.2 local state/identity checks without changing the input
+    // or the meaning/version of either serialized contract.
+    const legacy = a.kind === 'capability' ? {
+        ...a, contract: 'n8r.surface/0.2', capabilities: a.relationships.map(e => {
+            const { purpose, integration, configuration, ...core } = e;
+            return core;
+        })
+    } : { ...a, contract: 'n8r.surface/0.2', bindings: boundBindings(a) };
+    delete legacy.relationships;
+    validateDescription(legacy);
+    const nodes = new Set(a.nodes.map(n => n.id));
+    const vocab = new Set(a.vocabularies.map(v => v.id));
+    const records = new Set(a.records.map(r => JSON.stringify([r.id, r.revision])));
+    for (const e of a.relationships) {
+        references([e.from], nodes, '$.relationships.from');
+        references([e.to], nodes, '$.relationships.to');
+        references([e.type.vocabulary], vocab, '$.relationships.type');
+        const bases = [...e.basis, ...detailNames.flatMap(name => e[name].claims.flatMap(c => c.basis))];
+        for (const b of bases) {
+            references([JSON.stringify([b.record, b.revision])], records, '$.relationships.basis');
+            unique(b.items, '$.relationships.items');
+        }
+        for (const claim of e.configuration.claims)
+            for (const config of claim.value)
+                references([config.owner], nodes, '$.configuration.owner');
+    }
+}
+function verifyRelationshipDetails(a, research) {
+    for (const e of a.relationships)
+        for (const property of detailNames) {
+            const detail = e[property];
+            const values = new Set(detail.claims.map(c => canonical(c.value)));
+            const assertions = new Set();
+            for (const claim of detail.claims)
+                for (const b of claim.basis) {
+                    const r = research.find(r => r.id === b.record && r.revision.id === b.revision);
+                    for (const id of b.items) {
+                        const f = r.findings.find(f => f.id === id);
+                        if (!f || f.subject !== e.id || f.property !== property ||
+                            (detail.state === 'known' ? f.state !== 'known' : detail.state === 'absent' ? f.state !== 'absent' : !['known', 'absent', 'conflicting'].includes(f.state)) ||
+                            !f.claims.some(c => canonical(c.value) === canonical(claim.value)) ||
+                            f.claims.some(c => !values.has(canonical(c.value))))
+                            fail('$', 'relationship detail evidence mismatch');
+                        assertions.add(f.state);
+                    }
+                }
+            if (detail.state === 'conflicting' && values.size < 2 &&
+                !(assertions.has('known') && assertions.has('absent')))
+                fail('$', 'agreeing evidence does not establish conflict');
+            if (detail.claims.length) {
+                const matching = research.flatMap(r => r.findings).filter(f => f.subject === e.id && f.property === property);
+                for (const f of matching) {
+                    if (f.claims.some(c => !values.has(canonical(c.value))) ||
+                        (detail.state === 'known' && ['absent', 'conflicting'].includes(f.state)) ||
+                        (detail.state === 'absent' && ['known', 'conflicting'].includes(f.state)))
+                        fail('$', 'omitted contradictory relationship detail');
+                }
+            }
+        }
+}

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).