wowbagger 0.1.0-alpha.1

package/src/adapter/entrypoint-main.js

@@ -0,0 +1,335 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readBootstrapRequest, writeBootstrapResponse } from './bootstrap.js';
+import { CORE_COMMAND_ORDER, CORE_CONTRACT_VERSION } from './core-probe.js';
+import { ADAPTER_CONTRACT_VERSION, describeAdapter } from './describe.js';
+import { invokeAdapter } from './invoke.js';
+import { validateAdapterManifest } from './manifest.js';
+import { INVOKE_MESSAGES } from './messages.js';
+import { isSafeLogicalPath } from './paths.js';
+import { normalizeJsonValue, parseJsonRequest } from '../request.js';
+
+// The launch discipline every current adapter package shares: argv-array
+// core launch without a shell, guarded-relative workspace selection,
+// host-provided instructions, consumer-only trusted approval. Each adapter
+// still owns its declaration — it calls this factory and may override any
+// member before returning, so a harness whose guarantees genuinely differ
+// diverges deliberately instead of by missed edit.
+const STANDARD_LIMITS = Object.freeze({
+  max_request_bytes: 65536,
+  max_context_bytes: 65536,
+  max_stdout_bytes: 1048576,
+  max_stderr_bytes: 65536,
+  max_timeout_ms: 30000,
+});
+const PROBE_LIVE_CORE = Symbol('probe-live-core');
+
+export function standardDynamicResult(manifest, coreProbe) {
+  return {
+    ok: true,
+    bootstrap_wire_version: 1,
+    selected_adapter_contract_version: ADAPTER_CONTRACT_VERSION,
+    adapter_id: manifest.adapter_id,
+    adapter_version: manifest.adapter_version,
+    core: {
+      required_core_contract_version: CORE_CONTRACT_VERSION,
+      commands: [...CORE_COMMAND_ORDER],
+    },
+    host: {
+      command_execution: {
+        supported: true,
+        arguments_array: true,
+        shell: false,
+        stdio: true,
+        process_tree_containment: true,
+        orphan_detection: true,
+        timeout_enforcement: true,
+        stdout_limit: true,
+        stderr_limit: true,
+      },
+      filesystem: {
+        workspace_selection: 'guarded-relative',
+        no_follow_resolution: true,
+        stable_identity: true,
+        component_walk: true,
+      },
+      model_transport: { available: true, protocol: 'openai-compatible' },
+      instruction_input: { mode: 'host-provided', max_sources: 8, max_bytes: 65536 },
+      handoff: { supported: true, persistence: 'explicit-only' },
+      trusted_approval: { supported: true, sources: ['consumer'] },
+      integration_mechanisms: { hooks: false, slash_commands: false, mcp: false, daemon: false },
+    },
+    optional_features: { claims: coreProbe?.result?.operations?.work_claim?.supported === true, policy: false },
+    limits: { ...STANDARD_LIMITS },
+    platforms: manifest.platforms,
+  };
+}
+
+function appendBounded(chunks, state, chunk, limit, terminate) {
+  const remaining = Math.max(0, limit - state.length);
+  if (remaining > 0) chunks.push(chunk.subarray(0, remaining));
+  state.length += chunk.length;
+  if (state.length > limit && !state.exceeded) {
+    state.exceeded = true;
+    terminate();
+  }
+}
+
+export function launchCoreProcess({ executable, argv, cwd, input, limits }) {
+  return new Promise((resolve) => {
+    const detached = process.platform !== 'win32';
+    const child = spawn(process.execPath, [executable, ...argv], {
+      cwd,
+      detached,
+      shell: false,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    const stdoutState = { length: 0, exceeded: false };
+    const stderrState = { length: 0, exceeded: false };
+    let started = false;
+    let spawnError = false;
+    let timedOut = false;
+
+    const terminate = () => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      try {
+        if (detached && child.pid) process.kill(-child.pid, 'SIGKILL');
+        else child.kill('SIGKILL');
+      } catch {
+        child.kill('SIGKILL');
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminate();
+    }, limits.timeout_ms);
+
+    child.once('spawn', () => {
+      started = true;
+      child.stdin.end(input);
+    });
+    child.once('error', () => { spawnError = true; });
+    child.stdout.on('data', (chunk) => {
+      appendBounded(stdoutChunks, stdoutState, chunk, limits.stdout_bytes, terminate);
+    });
+    child.stderr.on('data', (chunk) => {
+      appendBounded(stderrChunks, stderrState, chunk, limits.stderr_bytes, terminate);
+    });
+    child.once('close', (code, signal) => {
+      clearTimeout(timer);
+      const outputExceeded = stdoutState.exceeded || stderrState.exceeded;
+      const deliberatelyTerminated = outputExceeded || timedOut;
+      resolve({
+        started: started && !spawnError,
+        process_tree_contained: true,
+        orphaned: false,
+        exit_code: deliberatelyTerminated || !Number.isInteger(code) ? null : code,
+        signal: deliberatelyTerminated ? null : signal,
+        timed_out: timedOut,
+        stdout_complete: !stdoutState.exceeded,
+        stderr_complete: !stderrState.exceeded,
+        stdout_base64: Buffer.concat(stdoutChunks).toString('base64'),
+        stderr_base64: Buffer.concat(stderrChunks).toString('base64'),
+      });
+    });
+  });
+}
+
+async function probeCore(coreExecutable, packageRoot) {
+  const observation = await launchCoreProcess({
+    executable: coreExecutable,
+    argv: ['capabilities', '--json'],
+    cwd: packageRoot,
+    input: Buffer.alloc(0),
+    limits: {
+      stdout_bytes: STANDARD_LIMITS.max_stdout_bytes,
+      stderr_bytes: STANDARD_LIMITS.max_stderr_bytes,
+      timeout_ms: STANDARD_LIMITS.max_timeout_ms,
+    },
+  });
+  if (!observation.started || observation.exit_code !== 0
+    || !observation.stdout_complete || !observation.stderr_complete) return undefined;
+  const parsed = parseJsonRequest(Buffer.from(observation.stdout_base64, 'base64'));
+  return parsed.issues.length === 0 ? normalizeJsonValue(parsed.value) : undefined;
+}
+
+// The installed package's own manifest file is read as bytes and parsed
+// with the same strict-JSON parser used for the wire request (section 3.1
+// declares the manifest is "strict JSON", the same standard section 10
+// holds the fixtures to). A missing/unreadable file, syntactically invalid
+// JSON, or a duplicate top-level member (e.g. a hostile second adapter_id
+// that a lenient last-wins parser would silently accept) all resolve to
+// `undefined` rather than throwing; `validateAdapterManifest(undefined)`
+// already refuses with `invalid-adapter-manifest`, so the caller does not
+// need a separate load-failure branch.
+async function loadManifest(manifestUrl) {
+  let bytes;
+  try {
+    bytes = await readFile(fileURLToPath(manifestUrl));
+  } catch {
+    return undefined;
+  }
+  const parsed = parseJsonRequest(bytes);
+  if (parsed.issues.length > 0) {
+    return undefined;
+  }
+  return normalizeJsonValue(parsed.value);
+}
+
+async function loadWorkspaceRoots(workspaceConfigUrl) {
+  if (!workspaceConfigUrl) return Object.create(null);
+  let parsed;
+  try {
+    parsed = parseJsonRequest(await readFile(fileURLToPath(workspaceConfigUrl)));
+  } catch {
+    return Object.create(null);
+  }
+  if (parsed.issues.length > 0) return Object.create(null);
+  const roots = normalizeJsonValue(parsed.value);
+  if (roots === null || typeof roots !== 'object' || Array.isArray(roots)) {
+    return Object.create(null);
+  }
+  return roots;
+}
+
+function logicalComponents(logicalPath) {
+  if (!isSafeLogicalPath(logicalPath) || logicalPath === '.') return [];
+  const segments = logicalPath.split('/');
+  return segments.map((_, index) => segments.slice(0, index + 1).join('/'));
+}
+
+async function pathSnapshot(absolutePath) {
+  try {
+    const stats = await lstat(absolutePath);
+    const kind = stats.isDirectory()
+      ? 'directory'
+      : stats.isSymbolicLink() ? 'symbolic-link' : stats.isFile() ? 'regular-file' : 'special';
+    return { kind, identity: { dev: stats.dev, ino: stats.ino } };
+  } catch {
+    return { kind: 'missing', identity: 'missing' };
+  }
+}
+
+async function captureWorkspace(root, request) {
+  const snapshot = { '.': await pathSnapshot(root) };
+  const components = new Set([
+    ...logicalComponents(request.workspace.cwd ?? '.'),
+    ...logicalComponents(request.core_request.ledger),
+  ]);
+  for (const component of components) {
+    snapshot[component] = await pathSnapshot(path.join(root, ...component.split('/')));
+  }
+  return snapshot;
+}
+
+async function invocationWorkspaces(request, workspaceRoots) {
+  if (request?.core_request?.command === 'capabilities' || !request?.workspace) return {};
+  const root = workspaceRoots[request.workspace.workspace_id];
+  if (typeof root !== 'string' || !path.isAbsolute(root)) return {};
+  const approvedRoot = path.resolve(root);
+  const before = await captureWorkspace(approvedRoot, request);
+  const after = await captureWorkspace(approvedRoot, request);
+  return {
+    [request.workspace.workspace_id]: { root: approvedRoot, before, after },
+  };
+}
+
+// The shared §3.3 entrypoint flow every adapter package runs: load and
+// validate its own manifest, read one bootstrap request, answer describe or
+// refuse. Each adapter supplies only its manifest location and its honest
+// host declaration through `dynamicResult(manifest)`.
+export async function runAdapterEntrypoint({
+  manifestUrl,
+  dynamicResult,
+  packageRoot = fileURLToPath(new URL('../../', manifestUrl)),
+  coreExecutable = fileURLToPath(new URL('../../bin/wowbagger.js', import.meta.url)),
+  workspaceConfigUrl,
+  coreProbe: suppliedCoreProbe = PROBE_LIVE_CORE,
+  launch: suppliedLaunch,
+  argv = process.argv,
+}) {
+  const [operation] = argv.slice(2);
+  const manifest = await loadManifest(manifestUrl);
+
+  // §3.1: the package's own manifest is validated before it is advertised.
+  const validated = validateAdapterManifest(manifest);
+  if (!validated.ok) {
+    await writeBootstrapResponse(process.stdout, { ok: false, error: { code: validated.error_code } });
+    return;
+  }
+
+  const coreProbe = suppliedCoreProbe === PROBE_LIVE_CORE
+    ? await probeCore(coreExecutable, packageRoot)
+    : suppliedCoreProbe;
+  const dynamic = dynamicResult(manifest, coreProbe);
+
+  // §3.3 (item 39): an unknown operation is refused without reading stdin.
+  // Reading would otherwise wait on a host that never closes stdin, and a
+  // malformed read would misreport as a describe error instead of an
+  // invalid-invocation. Only describe and invoke are valid bootstrap ops.
+  if (operation !== 'describe' && operation !== 'invoke') {
+    await writeBootstrapResponse(process.stdout, { ok: false, error: { code: 'invalid-invocation' } });
+    return;
+  }
+
+  // Both describe and invoke reads share the configured request byte ceiling
+  // (item 39, D1). describe was previously unbounded — the first call any
+  // host makes is the more exposed surface, so it must be bounded too.
+  const incoming = await readBootstrapRequest(process.stdin, {
+    maxBytes: dynamic.limits.max_request_bytes,
+    errorCode: operation === 'invoke' ? 'invalid-invocation' : 'invalid-describe-request',
+  });
+  if (!incoming.ok) {
+    const response = operation === 'invoke'
+      ? {
+          ok: false,
+          adapter_contract_version: ADAPTER_CONTRACT_VERSION,
+          request_id: null,
+          error: {
+            code: incoming.error_code,
+            message: INVOKE_MESSAGES[incoming.error_code]
+              ?? 'The adapter invocation is invalid.',
+            details: incoming.detail,
+          },
+        }
+      : { ok: false, error: { code: incoming.error_code } };
+    await writeBootstrapResponse(process.stdout, response);
+    return;
+  }
+
+  if (operation === 'describe') {
+    const described = describeAdapter(incoming.request, manifest, dynamic);
+    await writeBootstrapResponse(
+      process.stdout,
+      described.ok ? described.result : { ok: false, error: { code: described.error_code } },
+    );
+    return;
+  }
+
+  if (operation === 'invoke') {
+    const workspaceRoots = await loadWorkspaceRoots(workspaceConfigUrl);
+    const workspaces = await invocationWorkspaces(incoming.request, workspaceRoots);
+    const response = await invokeAdapter(incoming.bytes, {
+      max_request_bytes: dynamic.limits.max_request_bytes,
+      describe_request: {
+        bootstrap_wire_version: 1,
+        supported_adapter_contract_versions: [ADAPTER_CONTRACT_VERSION],
+        request_id: 'entrypoint-invoke-describe',
+      },
+      manifest,
+      dynamic,
+      core_probe: coreProbe,
+      platform: process.platform,
+      package_root: packageRoot,
+      workspaces,
+      launch: suppliedLaunch
+        ?? ((request) => launchCoreProcess({ executable: coreExecutable, ...request })),
+    });
+    await writeBootstrapResponse(process.stdout, response);
+    return;
+  }
+}

package/src/adapter/entrypoint-path.js

@@ -0,0 +1,103 @@
+import { hasControlCharacter, isSafeRelativeExecutable } from './manifest.js';
+
+function rejected() {
+  return { ok: false, error_code: 'path-rejected' };
+}
+
+function replaced() {
+  return { ok: false, error_code: 'path-replaced' };
+}
+
+// The package root plus every cumulative parent segment (directories), then
+// the full executable path (the final regular file), per contract section
+// 3.1 / 4: "the package root, every parent component, and the final regular
+// file are resolved no-follow and their stable identities are rechecked
+// immediately before launch."
+function componentsFor(executable) {
+  const segments = executable.split('/');
+  const components = ['.'];
+  for (let index = 1; index < segments.length; index += 1) {
+    components.push(segments.slice(0, index).join('/'));
+  }
+  components.push(executable);
+  return components;
+}
+
+function isControlFreeNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0 && !hasControlCharacter(value);
+}
+
+function isIdentityMember(value) {
+  return isControlFreeNonEmptyString(value) || (Number.isSafeInteger(value) && value >= 0);
+}
+
+// `identity` is a nonempty control-free opaque token, an exact POSIX
+// { dev, ino } object, or an exact Windows { volume_id, file_id } object.
+function isValidIdentity(identity) {
+  if (isControlFreeNonEmptyString(identity)) {
+    return true;
+  }
+  if (identity === null || typeof identity !== 'object' || Array.isArray(identity)) {
+    return false;
+  }
+  const members = Object.keys(identity).sort().join(',');
+  if (members === 'dev,ino') {
+    return isIdentityMember(identity.dev) && isIdentityMember(identity.ino);
+  }
+  if (members === 'file_id,volume_id') {
+    return isIdentityMember(identity.volume_id) && isIdentityMember(identity.file_id);
+  }
+  return false;
+}
+
+function identitiesEqual(a, b) {
+  if (typeof a === 'string' || typeof b === 'string') {
+    return a === b;
+  }
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => a[key] === b[key]);
+}
+
+// Every before/after snapshot is the exact object { kind, identity }. `kind`
+// is the required portable kind for that position: `directory` for the
+// package root and every parent, `regular-file` for the command executable.
+function isValidSnapshot(snapshot, expectedKind) {
+  if (snapshot === null || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    return false;
+  }
+  if (Object.keys(snapshot).sort().join(',') !== 'identity,kind') {
+    return false;
+  }
+  if (snapshot.kind !== expectedKind) {
+    return false;
+  }
+  return isValidIdentity(snapshot.identity);
+}
+
+export function resolveEntrypointPath({ package_root: packageRoot, executable, before, after }) {
+  if (typeof packageRoot !== 'string' || packageRoot === '') {
+    return rejected();
+  }
+  if (!isSafeRelativeExecutable(executable)) {
+    return rejected();
+  }
+  if (before === null || typeof before !== 'object' || after === null || typeof after !== 'object') {
+    return rejected();
+  }
+
+  const components = componentsFor(executable);
+  for (const component of components) {
+    const expectedKind = component === executable ? 'regular-file' : 'directory';
+    if (!isValidSnapshot(before[component], expectedKind) || !isValidSnapshot(after[component], expectedKind)) {
+      return rejected();
+    }
+  }
+
+  for (const component of components) {
+    if (!identitiesEqual(before[component].identity, after[component].identity)) {
+      return replaced();
+    }
+  }
+
+  return { ok: true, path: `${packageRoot}/${executable}` };
+}

package/src/adapter/handoff.js

@@ -0,0 +1,124 @@
+import { createHash } from 'node:crypto';
+
+import { normalizeJsonValue, parseJsonRequest } from '../request.js';
+import { hasExactMembers, isNonNegativeSafeInteger } from './schema-helpers.js';
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const WOWBAGGER_ID = /^wb_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+function refuse(error_code, detail = {}) {
+  return { ok: false, error_code, detail };
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function decodeCanonicalBase64(value) {
+  if (typeof value !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return null;
+  }
+  const bytes = Buffer.from(value, 'base64');
+  return bytes.toString('base64') === value ? bytes : null;
+}
+
+export function validateHandoffCarrier(carrier, options) {
+  if (!hasExactMembers(carrier, [
+    'handoff_carrier_version', 'workspace_id', 'content_encoding', 'content_base64',
+    'byte_length', 'sha256', 'resume_request',
+  ])
+    || carrier.handoff_carrier_version !== 1
+    || carrier.content_encoding !== 'base64'
+    || !isNonNegativeSafeInteger(carrier.byte_length)
+    || !DIGEST.test(carrier.sha256)) {
+    return refuse('invalid-handoff-carrier');
+  }
+  if (carrier.workspace_id !== options.workspace_id) {
+    return refuse('handoff-workspace-mismatch', { member: 'carrier.workspace_id' });
+  }
+  if (!hasExactMembers(carrier.resume_request, [
+    'item_id', 'expected_revision', 'instruction_set_digest',
+  ])
+    || !WOWBAGGER_ID.test(carrier.resume_request.item_id)
+    || !DIGEST.test(carrier.resume_request.expected_revision)
+    || !DIGEST.test(carrier.resume_request.instruction_set_digest)) {
+    return refuse('invalid-handoff-resume-request');
+  }
+
+  const bytes = decodeCanonicalBase64(carrier.content_base64);
+  if (bytes === null || bytes.length !== carrier.byte_length || digest(bytes) !== carrier.sha256) {
+    return refuse('invalid-handoff-bytes');
+  }
+  if (bytes.length > options.max_bytes) return refuse('handoff-limit-exceeded');
+  const parsed = parseJsonRequest(bytes);
+  if (parsed.issues.length > 0) return refuse('invalid-handoff-json');
+  const handoff = normalizeJsonValue(parsed.value);
+  if (!hasExactMembers(handoff, [
+    'handoff_version', 'workspace_id', 'instruction_set_digest', 'item',
+  ])
+    || handoff.handoff_version !== 1
+    || !DIGEST.test(handoff.instruction_set_digest)
+    || !hasExactMembers(handoff.item, ['id', 'revision'])
+    || !WOWBAGGER_ID.test(handoff.item.id)
+    || !DIGEST.test(handoff.item.revision)) {
+    return refuse('invalid-handoff-object');
+  }
+  if (handoff.workspace_id !== options.workspace_id || handoff.workspace_id !== carrier.workspace_id) {
+    return refuse('handoff-workspace-mismatch', { member: 'handoff.workspace_id' });
+  }
+  const request = carrier.resume_request;
+  if (request.item_id !== handoff.item.id
+    || request.expected_revision !== handoff.item.revision
+    || request.instruction_set_digest !== handoff.instruction_set_digest) {
+    return refuse('handoff-resume-binding-mismatch');
+  }
+  if (request.instruction_set_digest !== options.current.instruction_set_digest) {
+    return refuse('handoff-instruction-set-mismatch');
+  }
+  if (request.item_id !== options.current.item_id) return refuse('handoff-item-mismatch');
+  if (request.expected_revision !== options.current.revision) {
+    return refuse('handoff-stale-item-revision', {
+      expected: request.expected_revision,
+      current: options.current.revision,
+    });
+  }
+  return { ok: true, byte_length: bytes.length, handoff };
+}
+
+export function buildResumePlan(carrier, options) {
+  const validated = validateHandoffCarrier(carrier, options);
+  if (!validated.ok) return validated;
+  return {
+    ok: true,
+    must_invoke: ['describe', 'validate', 'inspect'],
+    must_compare: ['instruction-set-digest', 'item-revision'],
+    forbidden_automatic_actions: ['claim-renewal', 'create', 'git-commit', 'git-push', 'transition'],
+  };
+}
+
+export function validateHandoffResume({
+  handoff_bytes: handoffBytes,
+  handoff_digest: handoffDigest,
+  resume_request: resumeRequest,
+  current,
+  max_bytes: maxBytes,
+}) {
+  if (!(handoffBytes instanceof Uint8Array) || handoffBytes.length > maxBytes) {
+    return refuse('handoff-limit-exceeded');
+  }
+  if (digest(handoffBytes) !== handoffDigest) return refuse('handoff-digest-mismatch');
+  const parsedResumeBytes = parseJsonRequest(handoffBytes);
+  if (parsedResumeBytes.issues.length > 0) return refuse('invalid-handoff-json');
+  if (!WOWBAGGER_ID.test(resumeRequest?.item_id)) return refuse('invalid-handoff-resume-request');
+  if (resumeRequest.instruction_set_digest !== current.instruction_set_digest) {
+    return refuse('handoff-instruction-set-mismatch');
+  }
+  if (resumeRequest.item_id !== current.item_id) return refuse('handoff-item-mismatch');
+  if (resumeRequest.expected_revision !== current.revision) {
+    return refuse('handoff-stale-item-revision', {
+      expected: resumeRequest.expected_revision,
+      current: current.revision,
+    });
+  }
+  return { ok: true };
+}

package/src/adapter/instructions.js

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto';
+
+import { isSafeLogicalPath } from './paths.js';
+import { hasExactMembers, isNonNegativeSafeInteger } from './schema-helpers.js';
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const SAFE_ID = /^[A-Za-z0-9._-]{1,128}$/;
+const ORIGIN_PRECEDENCE = new Map([
+  ['consumer', 0],
+  ['repository', 1],
+  ['harness', 2],
+  ['user', 3],
+  ['adapter', 4],
+]);
+
+function refuse(error_code, detail = {}) {
+  return { ok: false, error_code, detail };
+}
+
+function digest(bytes) {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  if (value !== null && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function decodeCanonicalBase64(value) {
+  if (typeof value !== 'string' || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    return null;
+  }
+  const bytes = Buffer.from(value, 'base64');
+  return bytes.toString('base64') === value ? bytes : null;
+}
+
+export function validateInstructionInput(input, limits) {
+  if (!hasExactMembers(input, ['instruction_input_version', 'required', 'sources'])
+    || input.instruction_input_version !== 1
+    || typeof input.required !== 'boolean'
+    || !Array.isArray(input.sources)) {
+    return refuse('invalid-instruction-input');
+  }
+  if (input.required && input.sources.length === 0) {
+    return refuse('required-instruction-input-missing');
+  }
+  if (input.sources.length > limits.max_sources) {
+    return refuse('instruction-source-limit-exceeded');
+  }
+
+  const seen = new Set();
+  const summary = [];
+  const diagnostics = [];
+  let totalBytes = 0;
+  for (const [ordinal, source] of input.sources.entries()) {
+    if (!hasExactMembers(source, [
+      'source_id', 'origin', 'content_encoding', 'content_base64', 'sha256', 'byte_length',
+    ], ['logical_path'])
+      || typeof source.source_id !== 'string'
+      || !SAFE_ID.test(source.source_id)
+      || !ORIGIN_PRECEDENCE.has(source.origin)
+      || source.content_encoding !== 'base64'
+      || !DIGEST.test(source.sha256)
+      || !isNonNegativeSafeInteger(source.byte_length)
+      || (Object.hasOwn(source, 'logical_path') && !isSafeLogicalPath(source.logical_path))) {
+      return refuse('invalid-instruction-source', { source_id: source?.source_id ?? null });
+    }
+    if (seen.has(source.source_id)) {
+      return refuse('duplicate-instruction-source-id', { source_id: source.source_id });
+    }
+    seen.add(source.source_id);
+    const bytes = decodeCanonicalBase64(source.content_base64);
+    if (bytes === null || bytes.length !== source.byte_length || digest(bytes) !== source.sha256) {
+      return refuse('invalid-instruction-source', { source_id: source.source_id });
+    }
+    totalBytes += bytes.length;
+    const record = {
+      source_id: source.source_id,
+      origin: source.origin,
+      sha256: source.sha256,
+      byte_length: source.byte_length,
+    };
+    summary.push(record);
+    diagnostics.push({
+      ordinal,
+      source_id: source.source_id,
+      origin: source.origin,
+      precedence: ORIGIN_PRECEDENCE.get(source.origin),
+      logical_path: source.logical_path ?? null,
+      byte_length: source.byte_length,
+      sha256: source.sha256,
+    });
+  }
+  if (totalBytes > limits.max_bytes) return refuse('instruction-byte-limit-exceeded');
+
+  return {
+    ok: true,
+    ordered_sources: summary.map(({ source_id }) => source_id),
+    total_bytes: totalBytes,
+    instruction_set_digest: digest(Buffer.from(canonicalJson(summary))),
+    diagnostics,
+  };
+}