@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/surfaces/render.js

@@ -0,0 +1,636 @@
+import { sha256Hex } from '../sha256.js';
+import { isAbsolute } from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { snapshotGeneratedJson, tryParseJson } from '../environment/contract.js';
+import { CustomHarness } from '../schema.js';
+import { safeSurfacePath as safePath } from './contract.js';
+import { GUARD_SURFACE_TARGETS, SURFACE_TARGETS, harnessFact } from './harness-registry.js';
+import { RULESYNC_VERSION } from './generator-adapter.js';
+import { stripDevelopmentMarkers } from './development-markers.js';
+import { captureOpenCodeRootMembers, classifySurfaceOwnership, } from './ownership.js';
+import { exactKeys } from '../exact-keys.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const MARKDOWN_PATHS = new Set(['AGENTS.md', 'CLAUDE.md']);
+const BUILT_INS = new Set(SURFACE_TARGETS);
+const NATIVE_BUILT_INS = new Set(GUARD_SURFACE_TARGETS);
+const SKILL_REFERENCE_PATH = /^references\/[a-z0-9]+(?:-[a-z0-9]+)*\.md$/;
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function object(value) {
+    return value !== undefined && value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function surfaceModelSha256(value) {
+    const captured = snapshotGeneratedJson(value);
+    return captured === undefined ? undefined : sha256Hex(JSON.stringify(captured));
+}
+function refuse(code, message, target) {
+    return { kind: 'refusal', diagnostic: { code, message, ...(target === undefined ? {} : { target }) } };
+}
+function validFileFields(value) {
+    return object(value) && safePath(value.path)
+        && typeof value.bytes === 'string' && Buffer.byteLength(value.bytes) <= 65_536
+        && typeof value.sha256 === 'string' && value.sha256 === sha256Hex(value.bytes);
+}
+function validFile(value) {
+    return object(value) && exactKeys(value, ['path', 'bytes', 'sha256']) && validFileFields(value);
+}
+function validEvidence(value) {
+    return object(value) && (value.kind === 'guide' || value.kind === 'mcp')
+        && exactKeys(value, ['kind', 'root', 'path', 'sha256', 'identity'])
+        && typeof value.root === 'string' && isAbsolute(value.root) && typeof value.path === 'string' && value.path.length > 0
+        && typeof value.identity === 'string' && value.identity.length > 0
+        && typeof value.sha256 === 'string' && SHA256.test(value.sha256);
+}
+function sorted(values) {
+    const result = [...new Set(values)].sort();
+    return result.length === 0 ? undefined : result;
+}
+function weakest(values) {
+    return values.includes('instructed') ? 'instructed' : 'enforced';
+}
+function sharedScope(contributions) {
+    const scopes = new Set(contributions.map(contribution => contribution.scope));
+    return scopes.size === 1 ? contributions[0]?.scope : undefined;
+}
+function frontmatter(base, fragment) {
+    if (!base.startsWith('---\n'))
+        return undefined;
+    const close = base.indexOf('\n---\n', 4);
+    if (close < 0 || !fragment.endsWith('\n'))
+        return undefined;
+    const key = fragment.startsWith('disallowedTools:') ? 'disallowedTools' : fragment.startsWith('permission:\n') ? 'permission' : undefined;
+    if (!key || new RegExp(`^${key}:`, 'm').test(base.slice(4, close)))
+        return undefined;
+    return `${base.slice(0, close)}\n${fragment}${base.slice(close + 1)}`;
+}
+/**
+ * The composition rule for a hook-registration settings file with several producers: every
+ * PreToolUse row is kept once, and every other top-level key and hook event must agree exactly.
+ * A refusal names the key so the producer that disagrees can be found.
+ */
+export function composeHookSettings(values) {
+    const result = {};
+    const hookEvents = {};
+    const rows = [];
+    const refusal = (key, reason) => ({ kind: 'refusal', key, reason });
+    for (const parsed of values) {
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return refusal('(root)', 'malformed');
+        const value = parsed;
+        const hooks = value.hooks;
+        if (hooks !== undefined && (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)))
+            return refusal('hooks', 'malformed');
+        const pre = hooks === undefined ? [] : hooks.PreToolUse ?? [];
+        if (!Array.isArray(pre))
+            return refusal('hooks.PreToolUse', 'malformed');
+        rows.push(...pre);
+        for (const [key, item] of Object.entries(value)) {
+            if (key === 'hooks')
+                continue;
+            if (Object.hasOwn(result, key) && JSON.stringify(result[key]) !== JSON.stringify(item))
+                return refusal(key, 'divergent');
+            result[key] = item;
+        }
+        for (const [key, item] of Object.entries(hooks ?? {})) {
+            if (key === 'PreToolUse')
+                continue;
+            if (Object.hasOwn(hookEvents, key) && JSON.stringify(hookEvents[key]) !== JSON.stringify(item))
+                return refusal(`hooks.${key}`, 'divergent');
+            hookEvents[key] = item;
+        }
+    }
+    const unique = [...new Map(rows.map(row => [JSON.stringify(row), row])).values()];
+    result.hooks = { ...hookEvents, PreToolUse: unique };
+    return { kind: 'complete', value: result };
+}
+function hookJson(contributions) {
+    const values = [];
+    for (const contribution of contributions) {
+        const value = tryParseJson(contribution.bytes);
+        if (value === undefined)
+            return undefined;
+        values.push(value);
+    }
+    const composed = composeHookSettings(values);
+    return composed.kind === 'complete' ? `${JSON.stringify(composed.value, null, 2)}\n` : undefined;
+}
+function customReceipts(harnesses, value) {
+    if (!Array.isArray(value) || value.length > 384)
+        return undefined;
+    const available = new Map();
+    for (const harness of harnesses)
+        for (const capability of harness.capabilities) {
+            if (capability.state !== 'unavailable')
+                available.set(`${harness.name}\0${capability.feature}`, capability);
+        }
+    const seen = new Set();
+    const contributions = [];
+    const evidence = [];
+    for (const candidate of value) {
+        if (!object(candidate) || !exactKeys(candidate, ['harness', 'feature', 'state', 'measuredOn', 'module', 'export', 'sourceSha256', 'resultSha256', 'files'])
+            || typeof candidate.harness !== 'string' || typeof candidate.feature !== 'string'
+            || candidate.state !== 'enforced' && candidate.state !== 'instructed' || typeof candidate.measuredOn !== 'string' || !DATE.test(candidate.measuredOn)
+            || typeof candidate.module !== 'string' || typeof candidate.export !== 'string'
+            || typeof candidate.sourceSha256 !== 'string' || !SHA256.test(candidate.sourceSha256)
+            || typeof candidate.resultSha256 !== 'string' || !SHA256.test(candidate.resultSha256)
+            || !Array.isArray(candidate.files) || candidate.files.length === 0)
+            return undefined;
+        const identity = `${candidate.harness}\0${candidate.feature}`;
+        const declaration = available.get(identity);
+        if (!declaration || seen.has(identity) || declaration.state !== candidate.state || declaration.measured_on !== candidate.measuredOn
+            || declaration.mechanism.module !== candidate.module || declaration.mechanism.export !== candidate.export)
+            return undefined;
+        const files = [];
+        for (const file of candidate.files) {
+            if (!object(file) || !exactKeys(file, ['path', 'bytes', 'sha256', 'scope']) || !validFileFields(file)
+                || file.scope !== 'always' && file.scope !== 'scoped')
+                return undefined;
+            files.push(file);
+        }
+        if (surfaceModelSha256(files) !== candidate.resultSha256)
+            return undefined;
+        const receipt = candidate;
+        for (const file of files)
+            contributions.push({ receipt, file });
+        evidence.push({ kind: 'custom-harness', harness: receipt.harness, feature: receipt.feature, state: receipt.state,
+            measuredOn: receipt.measuredOn, module: receipt.module, export: receipt.export,
+            sourceSha256: receipt.sourceSha256, resultSha256: receipt.resultSha256 });
+        seen.add(identity);
+    }
+    if ([...available.keys()].some(identity => !seen.has(identity)))
+        return undefined;
+    return { contributions, evidence };
+}
+function nativeFragments(value, expectedDigest, targets) {
+    if (!object(value) || !exactKeys(value, ['modelSha256', 'fragments']) || value.modelSha256 !== expectedDigest || !Array.isArray(value.fragments))
+        return undefined;
+    const result = [];
+    const seen = new Set();
+    for (const fragment of value.fragments) {
+        if (!object(fragment) || !exactKeys(fragment, ['target', 'path', 'baseSha256', 'bytes', 'sha256'])
+            || typeof fragment.target !== 'string' || !BUILT_INS.has(fragment.target) || !targets.has(fragment.target)
+            || typeof fragment.baseSha256 !== 'string' || !SHA256.test(fragment.baseSha256)
+            || !validFileFields(fragment) || seen.has(fragment.target))
+            return undefined;
+        seen.add(fragment.target);
+        result.push(fragment);
+    }
+    return seen.size === targets.size ? result : undefined;
+}
+function mergeNamedObject(left, right, replace) {
+    const first = snapshotGeneratedJson(left);
+    const second = snapshotGeneratedJson(right);
+    if (!object(first) || !object(second))
+        return undefined;
+    const merged = { ...first };
+    for (const [key, value] of Object.entries(second)) {
+        if (Object.hasOwn(merged, key) && key !== replace && JSON.stringify(merged[key]) !== JSON.stringify(value))
+            return undefined;
+        merged[key] = value;
+    }
+    return merged;
+}
+function mergeBrowserMcp(path, base, browser) {
+    try {
+        const first = snapshotGeneratedJson(path === '.codex/config.toml' ? parseToml(base) : JSON.parse(base));
+        const second = snapshotGeneratedJson(path === '.codex/config.toml' ? parseToml(browser) : JSON.parse(browser));
+        if (!object(first) || !object(second))
+            return undefined;
+        const key = path === '.mcp.json' ? 'mcpServers' : path === '.codex/config.toml' ? 'mcp_servers' : path === 'opencode.jsonc' ? 'mcp' : undefined;
+        if (!key)
+            return undefined;
+        const browserMembers = second[key];
+        if (!object(browserMembers) || Object.keys(browserMembers).some(name => name !== 'playwright'))
+            return undefined;
+        const members = mergeNamedObject(first[key], browserMembers, 'playwright');
+        if (!members || !Object.hasOwn(members, 'playwright'))
+            return undefined;
+        const additions = { ...second };
+        delete additions[key];
+        const merged = mergeNamedObject(first, additions);
+        if (merged)
+            merged[key] = members;
+        return merged ? path === '.codex/config.toml' ? stringifyToml(merged) : `${JSON.stringify(merged, null, 2)}\n` : undefined;
+    }
+    catch { /* unparseable input is malformed; the caller refuses it. */
+        return undefined;
+    }
+}
+export function renderSurfaceSet(input) {
+    const captured = snapshotGeneratedJson(input);
+    const required = ['configuredHarnesses', 'merge', 'generated', 'projection', 'mcp', 'restrictions', 'instructions', 'nativeMcp', 'nativeGrants', 'browser', 'browserReference', 'skillReferences', 'testing', 'customHarnesses', 'customReceipts', 'sourceEvidence'];
+    if (!object(captured) || !exactKeys(captured, required) || !Array.isArray(captured.configuredHarnesses)
+        || !Array.isArray(captured.customHarnesses) || !Array.isArray(captured.sourceEvidence)
+        || !object(captured.merge) || captured.merge.kind !== 'complete' || !Array.isArray(captured.merge.surfaces)
+        || !Array.isArray(captured.merge.overrides) || !Array.isArray(captured.merge.findings)
+        || !object(captured.generated) || !exactKeys(captured.generated, ['kind', 'status', 'diagnostics', 'mechanism', 'files', ...(Object.hasOwn(captured.generated, 'warnings') ? ['warnings'] : [])])
+        || captured.generated.kind !== 'complete' || captured.generated.status !== 0 || !Array.isArray(captured.generated.diagnostics)
+        || captured.generated.diagnostics.length !== 0 || !object(captured.generated.mechanism)
+        || !exactKeys(captured.generated.mechanism, ['package', 'version', 'role']) || captured.generated.mechanism.package !== 'rulesync'
+        || captured.generated.mechanism.version !== RULESYNC_VERSION || captured.generated.mechanism.role !== 'spelling'
+        || !Array.isArray(captured.generated.files)
+        || !object(captured.projection) || captured.projection.kind !== 'complete' || !Array.isArray(captured.projection.guides)
+        || !Array.isArray(captured.projection.grants)
+        || !object(captured.mcp) || captured.mcp.kind !== 'complete' || !object(captured.mcp.result)
+        || !Array.isArray(captured.mcp.result.servers) || !Array.isArray(captured.mcp.result.wrappers) || !Array.isArray(captured.mcp.result.harnesses)
+        || !object(captured.restrictions) || captured.restrictions.kind !== 'complete' || !validFile(captured.restrictions.sharedGuard)
+        || !Array.isArray(captured.restrictions.targets))
+        return refuse('SURFACE_INPUT_INVALID', 'surface render requires exact accepted leaf results');
+    const warnings = Object.hasOwn(captured.generated, 'warnings') ? captured.generated.warnings : [];
+    const generatedFiles = captured.generated.files;
+    let warningBytes = 0;
+    if (!Array.isArray(warnings) || warnings.length > 16 || warnings.some(warning => {
+        if (!object(warning) || !exactKeys(warning, ['severity', 'code', 'target', 'path', 'message'])
+            || warning.severity !== 'warning' || warning.code !== 'SURFACE_GENERATOR_TRUST_WARNING'
+            || warning.target !== 'claudecode' || warning.path !== '.claude/settings.json'
+            || typeof warning.message !== 'string' || warning.message.length === 0
+            || /[\u0000-\u001f\u007f]/u.test(warning.message))
+            return true;
+        const bytes = Buffer.byteLength(warning.message, 'utf8');
+        warningBytes += bytes;
+        return bytes > 4096 || warningBytes > 16384
+            || !generatedFiles.some(file => object(file) && file.target === warning.target && file.path === warning.path);
+    }))
+        return refuse('SURFACE_INPUT_INVALID', 'generator trust warnings must be bounded and name an emitted native settings file');
+    const configured = captured.configuredHarnesses;
+    if (configured.length === 0 || configured.some((value, index) => typeof value !== 'string' || index > 0 && configured[index - 1] >= value)) {
+        return refuse('SURFACE_INPUT_INVALID', 'configured harness identities must be sorted and unique');
+    }
+    const configuredSet = new Set(configured);
+    const parsedHarnesses = CustomHarness.array().safeParse(captured.customHarnesses);
+    const customNames = new Set(parsedHarnesses.success ? parsedHarnesses.data.map(harness => harness.name) : []);
+    // The listed built-in tools: any non-empty subset that includes a guarded one, as the schema admits.
+    const listedNative = new Set([...NATIVE_BUILT_INS].filter(target => configuredSet.has(target)));
+    if (!parsedHarnesses.success || parsedHarnesses.data.some(harness => !configuredSet.has(harness.name))
+        || [...configuredSet].some(name => !customNames.has(name) && !BUILT_INS.has(name))
+        || listedNative.size === 0)
+        return refuse('SURFACE_INPUT_INVALID', 'custom and built-in harness identities do not match the configured set');
+    const custom = customReceipts(parsedHarnesses.data, captured.customReceipts);
+    if (!custom)
+        return refuse('SURFACE_INPUT_INVALID', 'custom capability receipt is missing or does not match its authenticated declaration');
+    const browser = captured.browser === null ? null : object(captured.browser)
+        && exactKeys(captured.browser, ['rows', 'files', 'mcp', 'clients', 'graderBrowserAccess'])
+        && captured.browser.graderBrowserAccess === 'retained' && Array.isArray(captured.browser.rows)
+        && Array.isArray(captured.browser.files) && Array.isArray(captured.browser.clients)
+        && object(captured.browser.mcp) ? captured.browser : undefined;
+    if (browser === undefined || (browser === null) !== (captured.browserReference === null)
+        || captured.browserReference !== null && (typeof captured.browserReference !== 'string'
+            || Buffer.byteLength(captured.browserReference) === 0 || Buffer.byteLength(captured.browserReference) > 65_536)) {
+        return refuse('SURFACE_INPUT_INVALID', 'browser projection and authenticated reference must be paired bounded inputs');
+    }
+    const skillReferences = Array.isArray(captured.skillReferences) && captured.skillReferences.length <= 16
+        && captured.skillReferences.every(row => object(row) && exactKeys(row, ['skill', 'path', 'bytes'])
+            && typeof row.skill === 'string' && SKILL_NAME.test(row.skill) && typeof row.path === 'string' && SKILL_REFERENCE_PATH.test(row.path)
+            && typeof row.bytes === 'string' && Buffer.byteLength(row.bytes) > 0 && Buffer.byteLength(row.bytes) <= 65_536)
+        && new Set(captured.skillReferences.map(row => JSON.stringify([row.skill, row.path]))).size === captured.skillReferences.length
+        ? captured.skillReferences : undefined;
+    if (!skillReferences)
+        return refuse('SURFACE_INPUT_INVALID', 'skill references must be unique bounded references/<name>.md files owned by a named skill');
+    if (browser) {
+        const browserMcp = browser.mcp;
+        const browserServers = object(browserMcp) && browserMcp.kind === 'complete' && object(browserMcp.result)
+            && Array.isArray(browserMcp.result.servers) ? browserMcp.result.servers : undefined;
+        const projectedPlaywright = browserServers?.length === 1 && object(browserServers[0]) && browserServers[0].name === 'playwright'
+            ? browserServers[0] : undefined;
+        const sourcePlaywright = captured.mcp.result.servers.find(server => object(server) && server.name === 'playwright');
+        const unavailable = browserServers?.length === 0 && !sourcePlaywright
+            && Array.isArray(browser.rows) && Array.isArray(browser.files)
+            && browser.rows.every(row => object(row) && (row.transport !== 'mcp'
+                || row.declaration === 'unavailable' && row.callable === 'unavailable'))
+            && browser.files.every(row => object(row) && !['.mcp.json', '.codex/config.toml', 'opencode.jsonc'].includes(String(row.path)));
+        if (!unavailable && (!projectedPlaywright || !sourcePlaywright || JSON.stringify(projectedPlaywright) !== JSON.stringify(sourcePlaywright))) {
+            return refuse('SURFACE_INPUT_INVALID', 'browser MCP projection is not bound to the accepted Playwright declaration');
+        }
+    }
+    const testing = captured.testing === null ? null : object(captured.testing)
+        && exactKeys(captured.testing, ['tierGuide', 'nativeHooks']) && object(captured.testing.tierGuide)
+        && exactKeys(captured.testing.tierGuide, ['kind', 'bytes', 'lines', 'costs'])
+        && captured.testing.tierGuide.kind === 'complete' && typeof captured.testing.tierGuide.bytes === 'string'
+        && Buffer.byteLength(captured.testing.tierGuide.bytes) <= 65_536 && object(captured.testing.nativeHooks)
+        ? captured.testing : undefined;
+    if (testing === undefined)
+        return refuse('SURFACE_INPUT_INVALID', 'testing projection must be an exact bounded accepted leaf result');
+    const tierGuide = testing && object(testing.tierGuide) ? testing.tierGuide : null;
+    const nativeHooks = testing && object(testing.nativeHooks) ? testing.nativeHooks : null;
+    if (testing && (!tierGuide || !nativeHooks))
+        return refuse('SURFACE_INPUT_INVALID', 'testing projection must retain its validated objects');
+    if (tierGuide && (typeof tierGuide.bytes !== 'string' || typeof tierGuide.lines !== 'number' || !Number.isSafeInteger(tierGuide.lines) || tierGuide.lines < 1
+        || tierGuide.lines !== tierGuide.bytes.trimEnd().split('\n').length
+        || !Array.isArray(tierGuide.costs) || tierGuide.costs.length !== listedNative.size
+        || tierGuide.costs.some(cost => !object(cost) || !exactKeys(cost, ['target', 'status', 'metric', 'value', 'conditionalValue', 'cap', 'measuredOn', 'provenance', 'scopeSemantics'])
+            || typeof cost.target !== 'string' || !listedNative.has(cost.target) || cost.status !== 'within_cap'
+            || cost.metric !== 'lines' || typeof cost.value !== 'number' || !Number.isSafeInteger(cost.value) || cost.value < 0
+            || typeof cost.conditionalValue !== 'number' || !Number.isSafeInteger(cost.conditionalValue) || cost.conditionalValue < 0
+            || typeof cost.cap !== 'number' || !Number.isSafeInteger(cost.cap) || cost.cap < cost.value || typeof cost.measuredOn !== 'string' || !DATE.test(cost.measuredOn)
+            || typeof cost.provenance !== 'string' || cost.provenance.length === 0
+            || cost.scopeSemantics !== 'conditional' && cost.scopeSemantics !== 'full')
+        || new Set(tierGuide.costs.map(cost => object(cost) ? cost.target : undefined)).size !== listedNative.size)) {
+        return refuse('SURFACE_INPUT_INVALID', 'testing tier guide lost its bounded load-cost proof');
+    }
+    if (captured.instructions !== null && (typeof captured.instructions !== 'string' || captured.instructions.length === 0
+        || Buffer.byteLength(captured.instructions) > 65_536)) {
+        return refuse('SURFACE_INPUT_INVALID', 'consumer instructions must be absent or a bounded non-empty string');
+    }
+    const evidence = captured.sourceEvidence.length <= 512 && captured.sourceEvidence.every(validEvidence)
+        && new Set(captured.sourceEvidence.map(row => JSON.stringify(row))).size === captured.sourceEvidence.length
+        ? captured.sourceEvidence : undefined;
+    if (!evidence)
+        return refuse('SURFACE_INPUT_INVALID', 'guide and MCP evidence must be authenticated bounded data');
+    for (const guide of captured.projection.guides) {
+        if (!object(guide) || typeof guide.sourceGuidePath !== 'string' || typeof guide.sourceContentSha256 !== 'string'
+            || typeof guide.sourceContentIdentity !== 'string' || typeof guide.bytes !== 'string' || guide.bytes.length === 0
+            || !evidence.some(row => row.kind === 'guide' && row.path === guide.sourceGuidePath
+                && row.sha256 === guide.sourceContentSha256 && row.identity === guide.sourceContentIdentity)) {
+            return refuse('SURFACE_INPUT_INVALID', 'projection guide output is not bound to matching evidence');
+        }
+    }
+    for (const server of captured.mcp.result.servers) {
+        if (!object(server) || !Array.isArray(server.sources))
+            return refuse('SURFACE_INPUT_INVALID', 'MCP result is malformed');
+        for (const source of server.sources)
+            if (!object(source) || typeof source.path !== 'string' || typeof source.sha256 !== 'string'
+                || !evidence.some(row => row.kind === 'mcp' && row.path === source.path && row.sha256 === source.sha256)) {
+                return refuse('SURFACE_INPUT_INVALID', 'MCP output is not bound to matching source evidence');
+            }
+    }
+    const mcpTargets = new Set();
+    const mcpHarnesses = new Set();
+    for (const harness of captured.mcp.result.harnesses) {
+        if (!object(harness) || typeof harness.target !== 'string' || !BUILT_INS.has(harness.target)
+            || !configuredSet.has(harness.target) || !Array.isArray(harness.servers)
+            || mcpHarnesses.has(harness.target))
+            return refuse('SURFACE_INPUT_INVALID', 'MCP harness output is malformed');
+        mcpHarnesses.add(harness.target);
+        if (harness.servers.length > 0)
+            mcpTargets.add(harness.target);
+    }
+    // A remote server may fit none of the listed tools, and says so; a local one fits every tool.
+    if (captured.mcp.result.servers.some(server => object(server) && server.transport !== 'http') && mcpTargets.size === 0) {
+        return refuse('SURFACE_INPUT_INVALID', 'MCP model has no matching native transport');
+    }
+    const mcpModelDigest = surfaceModelSha256(captured.mcp.result);
+    if (!mcpModelDigest)
+        return refuse('SURFACE_BOUNDS', 'MCP model cannot be captured for native binding');
+    const mcpNative = captured.mcp.result.servers.length === 0 && object(captured.nativeMcp)
+        && captured.nativeMcp.modelSha256 === mcpModelDigest && Array.isArray(captured.nativeMcp.fragments) && captured.nativeMcp.fragments.length === 0
+        ? [] : nativeFragments(captured.nativeMcp, mcpModelDigest, mcpTargets);
+    if (!mcpNative)
+        return refuse('SURFACE_INPUT_INVALID', 'nonempty MCP model requires exact native fragments bound to the same approvals');
+    const grantTargets = new Set();
+    for (const grant of captured.projection.grants)
+        if (object(grant) && typeof grant.target === 'string')
+            grantTargets.add(grant.target);
+    const grantsDigest = surfaceModelSha256(captured.projection.grants);
+    if (!grantsDigest)
+        return refuse('SURFACE_BOUNDS', 'directory grants cannot be captured for native binding');
+    const grantNative = captured.projection.grants.length === 0 && object(captured.nativeGrants)
+        && captured.nativeGrants.modelSha256 === grantsDigest && Array.isArray(captured.nativeGrants.fragments) && captured.nativeGrants.fragments.length === 0
+        ? [] : nativeFragments(captured.nativeGrants, grantsDigest, grantTargets);
+    if (!grantNative)
+        return refuse('SURFACE_INPUT_INVALID', 'directory grants require exact native fragments bound to the same projection');
+    const whole = new Map();
+    const markdown = new Map();
+    const native = new Map();
+    const browserMcp = new Map();
+    const readonly = new Map();
+    const add = (map, path, contribution) => map.set(path, [...map.get(path) ?? [], contribution]);
+    for (const target of BUILT_INS)
+        if (configuredSet.has(target))
+            for (const reference of skillReferences) {
+                add(whole, `${harnessFact(target).outputs.skills}/${reference.skill}/${reference.path}`, {
+                    harnesses: [target], scope: 'always', capability: 'instructed', bytes: stripDevelopmentMarkers(reference.bytes),
+                });
+            }
+    for (const candidate of captured.generated.files) {
+        if (!object(candidate) || !exactKeys(candidate, ['target', 'path', 'bytes', 'sha256']) || typeof candidate.target !== 'string'
+            || !configuredSet.has(candidate.target) || !validFileFields(candidate))
+            return refuse('SURFACE_INPUT_INVALID', 'generated surface output is malformed');
+        const contribution = { harnesses: [candidate.target], scope: 'always', capability: 'instructed', bytes: stripDevelopmentMarkers(candidate.bytes) };
+        if (candidate.path !== 'CLAUDE.md') {
+            add(MARKDOWN_PATHS.has(candidate.path) ? markdown : whole, candidate.path, contribution);
+        }
+    }
+    if (browser && Array.isArray(browser.files))
+        for (const candidate of browser.files) {
+            if (!object(candidate) || !exactKeys(candidate, ['target', 'path', 'bytes', 'sha256']) || typeof candidate.target !== 'string'
+                || !NATIVE_BUILT_INS.has(candidate.target) || !configuredSet.has(candidate.target) || !validFileFields(candidate)) {
+                return refuse('SURFACE_INPUT_INVALID', 'browser surface output is malformed');
+            }
+            const path = candidate.path;
+            const contribution = { harnesses: [candidate.target], scope: 'always',
+                capability: 'instructed', bytes: stripDevelopmentMarkers(candidate.bytes) };
+            if (path.endsWith('/skills/cockpit-browser/SKILL.md')) {
+                add(whole, path, contribution);
+                add(whole, `${path.slice(0, -'SKILL.md'.length)}references/browser.md`, { ...contribution, bytes: stripDevelopmentMarkers(captured.browserReference) });
+            }
+            else if (['.mcp.json', '.codex/config.toml', 'opencode.jsonc'].includes(path)) {
+                if (browserMcp.has(path))
+                    return refuse('SURFACE_PATH_CONFLICT', 'browser emitted duplicate native MCP output', path);
+                browserMcp.set(path, contribution);
+            }
+            else
+                return refuse('SURFACE_INPUT_INVALID', 'browser emitted an unsupported physical path', path);
+        }
+    const instructionPaths = SURFACE_TARGETS.filter(target => configuredSet.has(target)).map(target => [target, 'AGENTS.md']);
+    if (configuredSet.has('claudecode'))
+        add(markdown, 'CLAUDE.md', { harnesses: ['claudecode'], scope: 'always', capability: 'instructed', bytes: '@AGENTS.md' });
+    if (typeof captured.instructions === 'string')
+        for (const [target, path] of instructionPaths) {
+            add(markdown, path, { harnesses: [target], scope: 'always', capability: 'instructed', bytes: captured.instructions });
+        }
+    if (testing && tierGuide && nativeHooks) {
+        for (const [target, path] of instructionPaths) {
+            add(markdown, path, { harnesses: [target], scope: 'always', capability: 'instructed', bytes: stripDevelopmentMarkers(tierGuide.bytes) });
+        }
+        const hooks = nativeHooks;
+        if (hooks.kind === 'complete') {
+            if (!exactKeys(hooks, ['kind', 'entries', 'cost', 'activation']) || !Array.isArray(hooks.entries) || hooks.entries.length !== 1) {
+                return refuse('SURFACE_INPUT_INVALID', 'native hook projection is malformed');
+            }
+            if (!object(hooks.cost) || !exactKeys(hooks.cost, ['kind', 'scope', 'executionSha256', 'limitMs', 'measuredMs'])
+                || hooks.cost.kind !== 'within-budget' || hooks.cost.scope !== 'supplied-execution-environment'
+                || typeof hooks.cost.executionSha256 !== 'string' || !SHA256.test(hooks.cost.executionSha256)
+                || typeof hooks.cost.limitMs !== 'number' || !Number.isSafeInteger(hooks.cost.limitMs) || hooks.cost.limitMs < 1
+                || typeof hooks.cost.measuredMs !== 'number' || !Number.isSafeInteger(hooks.cost.measuredMs) || hooks.cost.measuredMs < 0 || hooks.cost.measuredMs > hooks.cost.limitMs
+                || !object(hooks.activation) || !exactKeys(hooks.activation, ['kind', 'hooksPath', 'mode'])
+                || hooks.activation.kind !== 'explicit-native-install' || hooks.activation.hooksPath !== '.githooks'
+                || hooks.activation.mode !== 493)
+                return refuse('SURFACE_INPUT_INVALID', 'native hook projection is malformed');
+            const hook = hooks.entries[0];
+            if (!object(hook) || !exactKeys(hook, ['path', 'kind', 'ownership', 'harnesses', 'writer', 'schemaVersion', 'scope', 'capability', 'bytes', 'sha256'])
+                || hook.path !== '.githooks/pre-push' || hook.kind !== 'file' || hook.ownership !== 'whole-file'
+                || hook.writer !== 'cockpit' || hook.schemaVersion !== 1 || hook.scope !== 'scoped' || hook.capability !== 'instructed'
+                || !Array.isArray(hook.harnesses) || hook.harnesses.length === 0 || hook.harnesses.some(value => typeof value !== 'string' || !configuredSet.has(value))
+                || !validFileFields(hook))
+                return refuse('SURFACE_INPUT_INVALID', 'native hook projection is malformed');
+            add(whole, hook.path, { harnesses: hook.harnesses, scope: 'scoped', capability: 'instructed', bytes: hook.bytes });
+        }
+        else if ((hooks.kind !== 'not-installed' && hooks.kind !== 'ci-required' && hooks.kind !== 'refusal')
+            || !exactKeys(hooks, ['kind', 'reason']) || typeof hooks.reason !== 'string' || hooks.reason.length === 0
+            || Buffer.byteLength(hooks.reason) > 4_096)
+            return refuse('SURFACE_INPUT_INVALID', 'native hook projection is malformed');
+        else if (hooks.kind !== 'not-installed')
+            return refuse('SURFACE_INPUT_INVALID', hooks.reason, '.githooks/pre-push');
+    }
+    for (const fragment of [...mcpNative, ...grantNative])
+        native.set(fragment.path, [...native.get(fragment.path) ?? [], fragment]);
+    for (const wrapper of captured.mcp.result.wrappers) {
+        if (!validFile(wrapper))
+            return refuse('SURFACE_INPUT_INVALID', 'MCP wrapper output is malformed');
+        // A local server's wrapper starts it; a remote server's wrapper runs its headers helper.
+        const server = captured.mcp.result.servers.find(row => object(row) && typeof row.name === 'string'
+            && wrapper.path === `.cockpit/mcp/${sha256Hex(row.name)}${row.transport === 'http' ? '.headers' : ''}.sh`);
+        const harnesses = object(server) ? captured.mcp.result.harnesses.filter(row => object(row)
+            && Array.isArray(row.servers) && row.servers.some(transport => object(transport) && transport.name === server.name))
+            .map(row => row.target) : [];
+        if (harnesses.length === 0)
+            return refuse('SURFACE_INPUT_INVALID', 'MCP wrapper has no matching native transport');
+        add(whole, wrapper.path, { harnesses, scope: 'always', capability: 'instructed', bytes: wrapper.bytes });
+    }
+    // Every tool reads the root AGENTS.md, so the copied sibling guides follow cockpit's own instructions there.
+    for (const guide of captured.projection.guides)
+        for (const [target, path] of instructionPaths) {
+            add(markdown, path, { harnesses: [target], scope: 'always', capability: 'instructed', bytes: guide.bytes });
+        }
+    const restrictedHarnesses = captured.restrictions.targets.filter(row => object(row) && row.capability === 'instructed')
+        .map(row => row.target);
+    if (restrictedHarnesses.length > 0)
+        add(whole, captured.restrictions.sharedGuard.path, {
+            harnesses: restrictedHarnesses, scope: 'always', capability: 'instructed', bytes: captured.restrictions.sharedGuard.bytes,
+        });
+    for (const target of captured.restrictions.targets) {
+        if (!object(target) || typeof target.target !== 'string' || !configuredSet.has(target.target) || !Array.isArray(target.files) || !object(target.readonly)) {
+            return refuse('SURFACE_INPUT_INVALID', 'restriction output is malformed');
+        }
+        if (target.capability === 'unavailable') {
+            if (target.files.length !== 0 || target.readonly.fragment !== null)
+                return refuse('SURFACE_INPUT_INVALID', 'unavailable restriction target emitted output');
+            continue;
+        }
+        if (target.capability !== 'instructed')
+            return refuse('SURFACE_INPUT_INVALID', 'restriction capability was promoted');
+        for (const file of target.files) {
+            if (!validFile(file))
+                return refuse('SURFACE_INPUT_INVALID', 'restriction file is malformed');
+            add(whole, file.path, { harnesses: [target.target], scope: 'always', capability: 'instructed', bytes: file.bytes });
+        }
+        if (target.readonly.fragment !== null) {
+            const fragment = target.readonly.fragment;
+            if (!validFile(fragment))
+                return refuse('SURFACE_INPUT_INVALID', 'readonly fragment is malformed');
+            if (readonly.has(fragment.path))
+                return refuse('SURFACE_PATH_CONFLICT', 'readonly fragment conflicts', fragment.path);
+            readonly.set(fragment.path, fragment.bytes);
+        }
+    }
+    for (const { receipt, file } of custom.contributions)
+        add(MARKDOWN_PATHS.has(file.path) ? markdown : whole, file.path, {
+            harnesses: [receipt.harness], scope: file.scope, capability: receipt.state, bytes: file.bytes,
+        });
+    for (const [path, fragments] of native) {
+        const finalBytes = new Set(fragments.map(fragment => fragment.bytes));
+        if (finalBytes.size !== 1)
+            return refuse('SURFACE_PATH_CONFLICT', 'native fragments for one physical path diverge', path);
+        const contributions = whole.get(path) ?? [];
+        const replaced = new Set();
+        for (const fragment of fragments) {
+            const baseRow = captured.generated.files.find(row => object(row) && row.target === fragment.target && row.path === path);
+            if (baseRow === undefined) {
+                if (fragment.baseSha256 !== sha256Hex(''))
+                    return refuse('SURFACE_INPUT_INVALID', 'native fragment is not bound to an absent base', path);
+            }
+            else if (!object(baseRow) || baseRow.sha256 !== fragment.baseSha256) {
+                return refuse('SURFACE_INPUT_INVALID', 'native fragment base digest does not match generated output', path);
+            }
+            else
+                replaced.add(`${fragment.target}\0${baseRow.bytes}`);
+        }
+        const retained = contributions.filter(row => !row.harnesses.some(harness => replaced.has(`${harness}\0${row.bytes}`)));
+        whole.set(path, [...retained, { harnesses: fragments.map(fragment => fragment.target), scope: 'always', capability: 'instructed', bytes: fragments[0].bytes }]);
+    }
+    for (const [path, contribution] of browserMcp) {
+        const bases = whole.get(path);
+        if (!bases || bases.length !== 1)
+            return refuse('SURFACE_PATH_CONFLICT', 'browser MCP requires one existing native configuration', path);
+        const bytes = mergeBrowserMcp(path, bases[0].bytes, contribution.bytes);
+        if (!bytes)
+            return refuse('SURFACE_PATH_CONFLICT', 'browser MCP conflicts with an existing server', path);
+        whole.set(path, [{ harnesses: [...bases[0].harnesses, ...contribution.harnesses], scope: 'always',
+                capability: weakest([bases[0].capability, contribution.capability]), bytes }]);
+    }
+    for (const [path, fragment] of readonly) {
+        const bases = whole.get(path);
+        if (!bases || bases.length !== 1)
+            return refuse('SURFACE_PATH_CONFLICT', 'readonly fragment requires one generated agent file', path);
+        const combined = frontmatter(bases[0].bytes, fragment);
+        if (combined === undefined)
+            return refuse('SURFACE_PATH_CONFLICT', 'readonly frontmatter conflicts with the generated agent file', path);
+        whole.set(path, [{ ...bases[0], bytes: combined }]);
+    }
+    const entries = [];
+    for (const [path, contributions] of whole) {
+        if (path === 'opencode.jsonc')
+            continue;
+        const distinct = [...new Set(contributions.map(row => row.bytes))];
+        let bytes;
+        if (distinct.length === 1)
+            bytes = distinct[0];
+        else if (path === '.claude/settings.json' || path === '.codex/hooks.json')
+            bytes = hookJson(contributions);
+        if (bytes === undefined)
+            return refuse('SURFACE_PATH_CONFLICT', 'producers emitted divergent bytes without a purpose-built composition rule', path);
+        const harnesses = sorted(contributions.flatMap(row => row.harnesses));
+        if (!harnesses)
+            return refuse('SURFACE_INPUT_INVALID', 'physical output has no configured harness', path);
+        const scope = sharedScope(contributions);
+        if (!scope)
+            return refuse('SURFACE_PATH_CONFLICT', 'producers emitted inconsistent scopes for one physical path', path);
+        entries.push({ kind: 'file', path, harnesses, scope, capability: weakest(contributions.map(row => row.capability)), writer: 'cockpit', schemaVersion: 1,
+            ownership: 'whole-file', bytes, sha256: sha256Hex(bytes) });
+    }
+    for (const [path, contributions] of markdown) {
+        const generatorRows = path === 'CLAUDE.md' ? [] : captured.generated.files.filter(row => object(row) && row.path === path);
+        if (generatorRows.length > 1 && new Set(generatorRows.map(row => object(row) ? row.bytes : undefined)).size !== 1) {
+            return refuse('SURFACE_PATH_CONFLICT', 'shared generator instruction bases diverge', path);
+        }
+        const base = generatorRows.length > 0 && object(generatorRows[0]) ? stripDevelopmentMarkers(generatorRows[0].bytes) : '';
+        const additions = contributions.filter(row => row.bytes !== base).map(row => row.bytes);
+        const body = [base.replace(/\n+$/, ''), ...new Set(additions)].filter(Boolean).join('\n') + '\n';
+        const harnesses = sorted(contributions.flatMap(row => row.harnesses));
+        if (!harnesses)
+            return refuse('SURFACE_INPUT_INVALID', 'shared Markdown output has no configured harness', path);
+        const scope = sharedScope(contributions);
+        if (!scope)
+            return refuse('SURFACE_PATH_CONFLICT', 'producers emitted inconsistent scopes for one physical path', path);
+        entries.push({ kind: 'shared-region', path, harnesses, scope, capability: weakest(contributions.map(row => row.capability)), writer: 'cockpit', schemaVersion: 1,
+            ownership: 'shared-region', regionId: 'cockpit-instructions', region: { format: 'markdown-delimited',
+                begin: '<!-- cockpit:instructions:start -->', end: '<!-- cockpit:instructions:end -->', bytes: body, sha256: sha256Hex(body) } });
+    }
+    const openCode = whole.get('opencode.jsonc') ?? [];
+    if (openCode.length > 0) {
+        const distinct = [...new Set(openCode.map(row => row.bytes))];
+        if (distinct.length !== 1)
+            return refuse('SURFACE_PATH_CONFLICT', 'OpenCode native producers emitted divergent base bytes', 'opencode.jsonc');
+        const members = captureOpenCodeRootMembers(distinct[0]);
+        if (!members)
+            return refuse('SURFACE_OWNERSHIP_INVALID', 'OpenCode base must be strict JSON containing only admitted native root keys', 'opencode.jsonc');
+        const grouped = [...members].sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0);
+        const contributions = openCode;
+        const harnesses = sorted(contributions.flatMap(row => row.harnesses));
+        if (!harnesses)
+            return refuse('SURFACE_INPUT_INVALID', 'OpenCode output has no configured harness');
+        const scope = sharedScope(contributions);
+        if (!scope)
+            return refuse('SURFACE_PATH_CONFLICT', 'producers emitted inconsistent scopes for one physical path', 'opencode.jsonc');
+        entries.push({ kind: 'shared-region', path: 'opencode.jsonc', harnesses, scope, capability: weakest(contributions.map(row => row.capability)), writer: 'cockpit', schemaVersion: 1,
+            ownership: 'shared-region', regionId: 'cockpit-opencode-root-properties',
+            region: { format: 'opencode-json-root-properties', members: grouped, sha256: sha256Hex(JSON.stringify(grouped)) } });
+    }
+    entries.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const ownership = classifySurfaceOwnership({ configuredHarnesses: configured, entries });
+    if (ownership.kind === 'refusal')
+        return ownership;
+    const result = snapshotGeneratedJson({ kind: 'complete', entries: ownership.entries, warnings,
+        inputs: [...evidence, ...custom.evidence].sort((left, right) => JSON.stringify(left) < JSON.stringify(right) ? -1 : JSON.stringify(left) > JSON.stringify(right) ? 1 : 0) });
+    return result ? result : refuse('SURFACE_BOUNDS', 'surface render result exceeds the captured bounds');
+}