create-agdf 0.14.4 → 0.20.0

package/runtime/core/lib/mcp-tool-errors.js

@@ -0,0 +1,176 @@
+// Pure transport projection. Domain outcomes, receipts and eligibility stay with
+// their existing owners. No IO, SDK, private reader or mutable registry lives here.
+export const TOOL_ERROR_CONTRACT = 'agdf-tool-result/1';
+export const TOOL_RESULT_META = 'agdf/tool-result';
+const fields = ['schema_version', 'failed', 'code', 'category', 'effect_state', 'action', 'message', 'authorizes'];
+const actions = {
+  correct_input: ['input', ['invalid_input', 'dispatch_input_invalid', 'inspect_input_invalid', 'command_schema_invalid', 'decision_schema_invalid', 'operation_source_invalid']],
+  confirm_target: ['binding', ['target_unresolved', 'target_binding_mismatch', 'no_reliable_target', 'explicit_target_required', 'target_invalid']],
+  refresh_binding: ['binding', ['stale_revision', 'revision_mismatch', 'operation_binding_stale_or_invalid', 'artifact_revision_stale', 'decision_binding_changed', 'decision_binding_invalid', 'presentation_state_changed', 'presentation_version_decided', 'presentation_not_found', 'presentation_missing', 'operation_source_changed', 'session_expired', 'source_changed', 'snapshot_stale', 'run_missing', 'invalid_run', 'document_missing', 'read_unavailable', 'recovery_binding_invalid', 'run_path_invalid']],
+  obtain_authority: ['permission', ['resource_denied', 'host_ui_unsupported', 'app_only_mediation_not_qualified', 'approval_required', 'confirmation_required', 'command_group_disabled', 'permission_denied', 'closeout_not_ready']],
+  inspect_operation: ['uncertain', ['effect_unknown', 'recovery_required', 'original_operation_unconfirmed', 'operation_payload_conflict', 'another_pending_operation', 'decision_pending', 'decision_result_unknown', 'dispatch_timeout', 'dispatch_worker_termination_unconfirmed', 'generation_connection_lost', 'generation_response_unknown', 'generation_result_limit', 'command_result_budget_exceeded']],
+  retry_after_prerequisite: ['runtime', ['dispatch_busy', 'busy', 'dispatch_cancelled', 'cancelled', 'resource_limit', 'timeout', 'dispatch_output_too_large', 'inspect_output_too_large', 'lifecycle_ineligible', 'generation_unavailable', 'generation_capacity_protected', 'generation_input_limit', 'connection_closed', 'connection_control_unavailable', 'generation_route_capacity', 'generation_replacement_busy', 'connection_control_capacity']],
+  repair_runtime: ['runtime', ['runtime_version_mismatch', 'runtime_provenance_invalid']],
+  stop: ['unknown', ['dispatch_worker_failed', 'generation_runtime_failed', 'tool_result_invalid', 'unclassified_tool_failure', 'generation_manifest_incompatible']],
+};
+const causes = new Map(Object.entries(actions).flatMap(([action, [category, codes]]) => codes.map(code => [code, { action, category }])));
+const commandNames = new Set(['agdf_prepare', 'agdf_record', 'agdf_approve', 'agdf_revise', 'agdf_closeout', 'agdf_decision_action']);
+const commandOutcomes = new Set(['accepted', 'already_applied', 'rejected', 'recovery_required', 'effect_unknown']);
+const dispatchOutcomes = new Set(['invalid_input', 'target_unresolved', 'control_result', 'skill_continuation', 'intake_continuation', 'evaluator_error']);
+const inspectOutcomes = new Set(['invalid_input', 'target_unresolved', 'inspect_result', 'evaluator_error']);
+const exactReads = new Set(['presentation-document', 'presentation-preview', 'operation-contract', 'runtime-generations']);
+const reportReads = new Set(['doctor', 'gate-check', 'delivery-map', 'artifact-readiness', 'operation-status', 'native-qualification', 'contract']);
+const readStates = new Set(['available', 'empty', 'partial', 'invalid', 'missing', 'unsupported', 'blocked', 'stale', 'error']);
+const safeFields = new Set(['arguments', 'working_directory', 'primary_target', 'target_source', 'presentation_language', 'skill_id', 'run_id', 'expected_revision_id', 'operation_id', 'command', 'module', 'gate', 'cursor', 'operation', 'all_active', 'variant']);
+const plain = value => !!value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value));
+const invalid = () => { throw Object.assign(new Error('tool_result_invalid'), { code: 'tool_result_invalid', facts: { code: 'tool_result_invalid', dispatch: 'unknown' } }); };
+const textBytes = value => new TextEncoder().encode(JSON.stringify(value)).length;
+
+export function knownExecutionCode(code) { return causes.has(code) ? code : 'dispatch_worker_failed'; }
+export function validExecutionFacts(value) {
+  return plain(value) && Object.keys(value).every(key => ['code', 'dispatch', 'field', 'cause_code', 'worker_phase'].includes(key))
+    && causes.has(value.code) && ['not_dispatched', 'unknown'].includes(value.dispatch)
+    && (value.field === undefined || safeFields.has(value.field))
+    && (value.cause_code === undefined || value.code === 'dispatch_worker_termination_unconfirmed' && causes.has(value.cause_code))
+    && (value.worker_phase === undefined || value.code === 'dispatch_worker_termination_unconfirmed'
+      && ['worker_start', 'runtime_provenance', 'operation', 'result'].includes(value.worker_phase));
+}
+export function executionFacts(error, { phase = 'execute' } = {}) {
+  // Callers must establish the phase. An arbitrary exception's message/code is
+  // not a typed cause or evidence that a command did not execute.
+  const facts = validExecutionFacts(error?.facts) ? error.facts : null;
+  if (facts) return { ...facts };
+  return { code: 'dispatch_worker_failed', dispatch: phase === 'parse' || phase === 'setup' ? 'not_dispatched' : 'unknown' };
+}
+
+export function validateToolDomain(name, result) {
+  if (!plain(result) || result.schema_version !== '1' || result._meta !== undefined && !plain(result._meta)) invalid();
+  if (name === 'agdf_dispatch' || name === 'agdf_inspect') {
+    const outcomes = name === 'agdf_dispatch' ? dispatchOutcomes : inspectOutcomes;
+    if (result.contract_version !== 1 || !plain(result.runtime) || !plain(result.timing)
+      || !['wrapper_ms', 'input_ms', 'target_ms', 'control_ms', 'render_ms', 'total_ms'].every(key => Number.isFinite(result.timing[key]) && result.timing[key] >= 0)) invalid();
+    if (!outcomes.has(result.outcome) || result.authorizes !== false || typeof result.terminal !== 'boolean'
+      || !Array.isArray(result.diagnostics) || !result.diagnostics.every(plain)) invalid();
+    if (name === 'agdf_dispatch' && ['skill', 'control', 'continuation'].some(key => result[key] !== null && !plain(result[key]))) invalid();
+    if (name === 'agdf_inspect' && result.outcome === 'inspect_result' && !plain(result.report)) invalid();
+    if (!plain(result.host_action) || typeof result.host_action.mode !== 'string' || typeof result.host_action.source !== 'string'
+      || result.host_action.allow_surrounding_text !== undefined && typeof result.host_action.allow_surrounding_text !== 'boolean'
+      || result.host_action.may_request_run_or_evidence !== undefined && typeof result.host_action.may_request_run_or_evidence !== 'boolean'
+      || !(result.recovery === null || plain(result.recovery))
+      || !(result.target === null || plain(result.target)) || !(result.presentation === null || plain(result.presentation))) invalid();
+    if (name === 'agdf_inspect' && (!(result.operation === null || typeof result.operation === 'string')
+      || !(result.report === null || plain(result.report))
+      || result.outcome !== 'inspect_result' && result.report !== null
+      || result.outcome === 'inspect_result' && result.terminal !== false)) invalid();
+    if (['invalid_input', 'target_unresolved', 'evaluator_error'].includes(result.outcome)
+      && (result.terminal !== true || !['transmit_presentation_verbatim_and_stop', 'transmit_recovery_verbatim_and_stop'].includes(result.host_action.mode)
+        || typeof result.host_action.allow_surrounding_text !== 'boolean' || typeof result.host_action.may_request_run_or_evidence !== 'boolean'
+        || typeof result.recovery?.action !== 'string' || !result.recovery.action
+        || typeof result.host_action.text !== 'string' || !result.host_action.text)) invalid();
+  } else if (commandNames.has(name)) {
+    if (!commandOutcomes.has(result.outcome) || result.authorizes !== false) invalid();
+    if (['accepted', 'already_applied'].includes(result.outcome) ? !(result.receipt === null || plain(result.receipt)) : typeof result.reason !== 'string' || !result.reason) invalid();
+  } else if (name === 'agdf_cockpit' || name === 'agdf_cockpit_read') {
+    if (name === 'agdf_cockpit' && result.state === undefined && result.outcome === undefined) {
+      const view = result._meta?.agdf_cockpit;
+      if (result.authorizes !== false || !plain(result.target) || typeof result.target.target_id !== 'string'
+        || typeof result.target.display_path !== 'string' || !plain(view) || !plain(view.target)
+        || view.target.target_id !== result.target.target_id || view.target.display_path !== result.target.display_path
+        || typeof view.session_id !== 'string' || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(view.session_id)
+        || !Number.isSafeInteger(view.render_generation) || view.render_generation < 1) invalid();
+    } else if (name === 'agdf_cockpit_read' && result.state === 'available' && result.target === undefined && result.code === undefined) {
+      // Decision-session close and preview have existing minimal shapes,
+      // distinct from a Cockpit reader DTO with target/snapshot fields.
+      const preview = result.data?.preview;
+      const closed = plain(result.data) && Object.keys(result.data).join() === 'closed' && result.data.closed === true;
+      const rendered = plain(result.data) && Object.keys(result.data).join() === 'preview' && plain(preview)
+        && typeof preview.resource_id === 'string' && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(preview.resource_id)
+        && typeof preview.content === 'string' && /^sha256:[0-9a-f]{64}$/u.test(preview.content_digest)
+        && typeof preview.version === 'string' && preview.version.length > 0;
+      if (result.authorizes !== false || !closed && !rendered
+        || Object.keys(result).some(key => !['schema_version', 'state', 'data', 'authorizes', '_meta'].includes(key))) invalid();
+    } else if (result.outcome === 'rejected') { if (result.authorizes !== false || typeof result.reason !== 'string') invalid(); }
+    else if (!readStates.has(result.state) || !(result.code === null || typeof result.code === 'string')
+      || typeof result.retryable !== 'boolean' || !Object.hasOwn(result, 'data')
+      || !(result.target === null || plain(result.target)) || !Object.hasOwn(result, 'snapshot_id')) invalid();
+  } else invalid();
+  return result;
+}
+
+function isFailure(name, input, result) {
+  if (name === 'agdf_dispatch') return ['invalid_input', 'target_unresolved', 'evaluator_error'].includes(result.outcome);
+  if (name === 'agdf_inspect') {
+    if (result.outcome !== 'inspect_result') return true;
+    if (exactReads.has(input.operation)) return result.report.available !== true;
+    if (reportReads.has(input.operation)) return input.operation === 'native-qualification' && result.report.available === false;
+    invalid();
+  }
+  if (commandNames.has(name)) return !['accepted', 'already_applied'].includes(result.outcome);
+  if (result.outcome === 'rejected') return true;
+  // Freshness/changes legitimately report a stale snapshot. Nested run/resource
+  // states are never considered: only failure of this requested operation is.
+  if (['freshness', 'changes'].includes(input.operation) && result.state === 'stale') return false;
+  return ['invalid', 'missing', 'unsupported', 'blocked', 'stale', 'error'].includes(result.state);
+}
+
+export function describeToolResult(name, input, result, pack, facts) {
+  validateToolDomain(name, result);
+  const failed = isFailure(name, input, result);
+  const descriptor = { schema_version: '1', failed, code: null, category: null, effect_state: null, action: null, message: null, authorizes: false };
+  if (!failed) return descriptor;
+  const candidate = result.reason ?? result.code ?? result.diagnostics?.[0]?.code ?? result.report?.reason ?? result.target?.reason_code ?? result.outcome;
+  const code = causes.has(candidate) ? candidate : result.outcome === 'target_unresolved' ? 'target_unresolved'
+    : result.outcome === 'invalid_input' ? 'invalid_input' : result.report?.available === false ? 'read_unavailable' : 'unclassified_tool_failure';
+  const uncertain = ['effect_unknown', 'recovery_required'].includes(result.outcome);
+  let { action, category } = causes.get(code);
+  if (uncertain) { action = 'inspect_operation'; category = 'uncertain'; }
+  const effect = validExecutionFacts(facts) ? facts.dispatch : result.dispatch === 'not_dispatched' ? 'not_dispatched'
+    : commandNames.has(name) ? (uncertain ? 'unknown' : 'owner_reported') : 'owner_reported';
+  // A cancelled/disconnected write cannot be offered a blind retry.
+  if (commandNames.has(name) && effect === 'unknown') { action = 'inspect_operation'; category = 'uncertain'; }
+  const copy = pack?.mcpErrors;
+  if (!copy?.actions?.[action] || !copy?.effects?.[effect]) invalid();
+  const field = safeFields.has(facts?.field) ? facts.field : safeFields.has(result.diagnostics?.[0]?.field) ? result.diagnostics[0].field : null;
+  const ownerAction = !facts && result.outcome === 'invalid_input'
+    && typeof result.recovery?.action === 'string' && result.recovery.action.length <= 700
+    && !/[\0\x01-\x08]/u.test(result.recovery.action) ? result.recovery.action : null;
+  const workerDetails = validExecutionFacts(facts)
+    ? [facts.cause_code && `cause_code=${facts.cause_code}`, facts.worker_phase && `worker_phase=${facts.worker_phase}`].filter(Boolean) : [];
+  const message = `${copy.failure} ${code}${field ? ` (${field})` : ''}${workerDetails.length ? ` (${workerDetails.join(', ')})` : ''}. ${copy.effects[effect]} ${ownerAction ?? (action === causes.get(code).action ? copy.causes?.[code] : null) ?? copy.actions[action]}`;
+  return { ...descriptor, code, category, effect_state: effect, action, message };
+}
+
+export function validateToolDescriptor(value) {
+  if (!plain(value) || Object.keys(value).sort().join() !== [...fields].sort().join() || value.schema_version !== '1'
+    || typeof value.failed !== 'boolean' || value.authorizes !== false || textBytes(value) > 4096) invalid();
+  if (!value.failed) {
+    if (['code', 'category', 'effect_state', 'action', 'message'].some(key => value[key] !== null)) invalid();
+  } else if (!causes.has(value.code) || !['input', 'binding', 'permission', 'runtime', 'uncertain', 'unknown'].includes(value.category)
+    || !['not_dispatched', 'owner_reported', 'unknown'].includes(value.effect_state) || !Object.hasOwn(actions, value.action)
+    || typeof value.message !== 'string' || !value.message.trim() || value.message.length > 1200) invalid();
+  const expected = causes.get(value.code);
+  if (value.failed && !(value.action === expected.action && value.category === expected.category)
+    && !(value.action === 'inspect_operation' && value.category === 'uncertain' && value.effect_state === 'unknown')) invalid();
+  return value;
+}
+
+export function projectToolResult(name, input, result, pack, facts) {
+  const descriptor = validateToolDescriptor(describeToolResult(name, input, result, pack, facts));
+  return { ...result, _meta: { ...result._meta, [TOOL_RESULT_META]: descriptor } };
+}
+export function consumeToolResult(name, result) {
+  validateToolDomain(name, result);
+  const descriptor = validateToolDescriptor(result._meta?.[TOOL_RESULT_META]);
+  if ((!descriptor.failed && (commandNames.has(name) && !['accepted', 'already_applied'].includes(result.outcome)
+    || ['agdf_dispatch', 'agdf_inspect'].includes(name) && ['invalid_input', 'target_unresolved', 'evaluator_error'].includes(result.outcome)))
+    || descriptor.failed && (commandNames.has(name) && ['accepted', 'already_applied'].includes(result.outcome)
+    || name === 'agdf_dispatch' && ['control_result', 'skill_continuation', 'intake_continuation'].includes(result.outcome))) invalid();
+  if (['agdf_cockpit', 'agdf_cockpit_read'].includes(name) && !result.outcome
+    && (descriptor.failed && ['available', 'empty', 'partial'].includes(result.state)
+      || !descriptor.failed && ['invalid', 'missing', 'unsupported', 'blocked', 'error'].includes(result.state))) invalid();
+  if (name === 'agdf_inspect' && result.outcome === 'inspect_result' && exactReads.has(result.operation)
+    && descriptor.failed === (result.report.available === true)) invalid();
+  const { [TOOL_RESULT_META]: _private, ...metadata } = result._meta;
+  const { _meta, ...domain } = result;
+  return { domain, metadata, descriptor };
+}

package/runtime/core/lib/repository-context-reader.js

@@ -0,0 +1,87 @@
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, isAbsolute, parse, relative, resolve, sep } from "node:path";
+
+function isInside(root, candidate) {
+  const path = relative(root, candidate);
+  return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+
+function repositoryMarker(directory) {
+  const marker = `${directory}${sep}.git`;
+  if (!existsSync(marker)) return false;
+  try {
+    const stats = lstatSync(marker);
+    if (stats.isSymbolicLink()) return false;
+    let gitDirectory;
+    if (stats.isDirectory()) gitDirectory = marker;
+    else if (stats.isFile()) {
+      const match = /^gitdir:\s*(.+)\s*$/u.exec(readFileSync(marker, "utf8"));
+      if (!match) return false;
+      gitDirectory = realpathSync(resolve(directory, match[1]));
+      const gitStats = lstatSync(gitDirectory);
+      if (!gitStats.isDirectory() || gitStats.isSymbolicLink()) return false;
+    } else return false;
+    const head = `${gitDirectory}${sep}HEAD`;
+    if (!existsSync(head)) return false;
+    const headStats = lstatSync(head);
+    if (!headStats.isFile() || headStats.isSymbolicLink()) return false;
+    const value = readFileSync(head, "utf8").trim();
+    return /^ref:\s+refs\/[A-Za-z0-9._\/-]+$/u.test(value) || /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u.test(value);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveRepositoryContextByMarker(workingDirectory) {
+  const rawPath = String(workingDirectory ?? "").trim();
+  if (!rawPath || !isAbsolute(rawPath) || !existsSync(rawPath)) {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: rawPath || "unavailable",
+      repository_root: "",
+      reason_code: "working_directory_unavailable",
+      authorizes: false,
+    });
+  }
+  let canonicalWorkingDirectory;
+  try {
+    canonicalWorkingDirectory = realpathSync(rawPath);
+    if (!statSync(canonicalWorkingDirectory).isDirectory()) throw new Error("not_directory");
+  } catch {
+    return Object.freeze({
+      context_state: "repo_less",
+      working_directory: rawPath,
+      repository_root: "",
+      reason_code: "working_directory_unavailable",
+      authorizes: false,
+    });
+  }
+
+  const filesystemRoot = parse(canonicalWorkingDirectory).root;
+  let candidate = canonicalWorkingDirectory;
+  while (true) {
+    if (repositoryMarker(candidate)) {
+      const repositoryRoot = realpathSync(candidate);
+      if (isInside(repositoryRoot, canonicalWorkingDirectory)) {
+        return Object.freeze({
+          context_state: "repository_bound",
+          working_directory: canonicalWorkingDirectory,
+          repository_root: repositoryRoot,
+          reason_code: "verified_git_marker",
+          authorizes: false,
+        });
+      }
+    }
+    if (candidate === filesystemRoot) break;
+    const parent = dirname(candidate);
+    if (parent === candidate) break;
+    candidate = parent;
+  }
+  return Object.freeze({
+    context_state: "repo_less",
+    working_directory: canonicalWorkingDirectory,
+    repository_root: "",
+    reason_code: "not_in_git_worktree",
+    authorizes: false,
+  });
+}

package/runtime/core/lib/resources/artefact-templates.js

@@ -0,0 +1,72 @@
+import { isAbsolute } from "node:path";
+import { lstatKindSync } from "../control-read/fs.js";
+import { containedRegularFile, hasSymlinkComponent } from "../control-state/contained-file.js";
+import { resources } from "./context.js";
+
+export const ARTEFACT_TEMPLATE_IDS = Object.freeze({
+  UR: "UR",
+  PRD: "PRD",
+  SD: "SD",
+  TP: "TP",
+  UX_INTENT_DEFINITION: "UX_INTENT_DEFINITION",
+  BROWNFIELD_REVIEW: "BROWNFIELD_REVIEW",
+  VERIFIED_CHANGE: "VERIFIED_CHANGE",
+  QA_REPORT: "QA_REPORT",
+  OR: "OR",
+});
+
+export const ARTEFACT_TEMPLATE_ERROR_CODES = Object.freeze([
+  "AGDF_ARTEFACT_TEMPLATE_UNSUPPORTED",
+  "AGDF_ARTEFACT_TEMPLATE_ROOT_UNAVAILABLE",
+  "AGDF_ARTEFACT_TEMPLATE_UNAVAILABLE",
+  "AGDF_ARTEFACT_TEMPLATE_UNSAFE",
+]);
+
+const TEMPLATE_FILES = Object.freeze({
+  [ARTEFACT_TEMPLATE_IDS.UR]: "UR.md",
+  [ARTEFACT_TEMPLATE_IDS.PRD]: "PRD.md",
+  [ARTEFACT_TEMPLATE_IDS.SD]: "SD.md",
+  [ARTEFACT_TEMPLATE_IDS.TP]: "TP.md",
+  [ARTEFACT_TEMPLATE_IDS.UX_INTENT_DEFINITION]: "UX_INTENT_DEFINITION.md",
+  [ARTEFACT_TEMPLATE_IDS.BROWNFIELD_REVIEW]: "BROWNFIELD_REVIEW.md",
+  [ARTEFACT_TEMPLATE_IDS.VERIFIED_CHANGE]: "VERIFIED_CHANGE.md",
+  [ARTEFACT_TEMPLATE_IDS.QA_REPORT]: "QA_REPORT.md",
+  [ARTEFACT_TEMPLATE_IDS.OR]: "OR.md",
+});
+
+function templateError(code) {
+  return Object.assign(new Error(code), { code });
+}
+
+function rootKind(root) {
+  try {
+    return lstatKindSync(root);
+  } catch (error) {
+    if (error.code === "ENOENT") throw templateError("AGDF_ARTEFACT_TEMPLATE_ROOT_UNAVAILABLE");
+    throw templateError("AGDF_ARTEFACT_TEMPLATE_UNSAFE");
+  }
+}
+
+// The root itself must be a real directory and no component below it may be a link;
+// ancestors are outside the plugin's ownership and are covered by realpath containment.
+export function resolveArtefactTemplatePath(templateId, context = resources) {
+  if (!Object.hasOwn(TEMPLATE_FILES, templateId)) {
+    throw templateError("AGDF_ARTEFACT_TEMPLATE_UNSUPPORTED");
+  }
+  const filename = TEMPLATE_FILES[templateId];
+  const root = context?.templatesRoot;
+  if (root === null || root === undefined || root === "") {
+    throw templateError("AGDF_ARTEFACT_TEMPLATE_ROOT_UNAVAILABLE");
+  }
+  if (typeof root !== "string" || !isAbsolute(root) || rootKind(root) !== "directory") {
+    throw templateError("AGDF_ARTEFACT_TEMPLATE_UNSAFE");
+  }
+  const relativePath = `artefacts/${filename}`;
+  if (hasSymlinkComponent(root, relativePath)) {
+    throw templateError("AGDF_ARTEFACT_TEMPLATE_UNSAFE");
+  }
+  const result = containedRegularFile(root, relativePath);
+  if (result.status === "valid") return result.path;
+  if (result.status === "missing") throw templateError("AGDF_ARTEFACT_TEMPLATE_UNAVAILABLE");
+  throw templateError("AGDF_ARTEFACT_TEMPLATE_UNSAFE");
+}

package/runtime/core/lib/resources/binding.js

@@ -0,0 +1,26 @@
+// Generated resource binding; canonical Core implementation bytes are copied unchanged.
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, sep } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+export const packageURL = new URL("../../../../", import.meta.url);
+export const generatedURL = new URL("generated/", packageURL);
+function readVersion(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")).version ?? null; } catch { return null; }
+}
+function directoryURL(path) {
+  return existsSync(path) ? pathToFileURL(`${path}${sep}`) : null;
+}
+// Only an absolute, exact-version-matched plugin root overlays the package-shipped resources.
+function trustedPluginRoot() {
+  const root = process.env.AGDF_DISPATCH_PLUGIN_ROOT;
+  if (!root || !isAbsolute(root)) return null;
+  const packageVersion = readVersion(fileURLToPath(new URL("package.json", packageURL)));
+  return packageVersion !== null && readVersion(join(root, "runtime", "runtime-manifest.json")) === packageVersion ? root : null;
+}
+const pluginRoot = trustedPluginRoot();
+export const contractsURL = new URL("plugins/agdf/meta/contracts/", generatedURL);
+export const templatesURL = (pluginRoot ? directoryURL(join(pluginRoot, "control", "templates")) : null)
+  ?? directoryURL(fileURLToPath(new URL("../../control/templates/", packageURL)))
+  ?? directoryURL(fileURLToPath(new URL("plugins/agdf/control/templates/", generatedURL)))
+  ?? null;

package/runtime/core/lib/resources/context.js

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "../control-read/fs.js";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalizeLanguageTag, resolvePresentationLocale } from "../interaction-presentation.js";
+import { validateInteractionCatalog } from "../interaction-catalog-validation.js";
+import { packageURL, generatedURL, contractsURL, templatesURL } from "./binding.js";
+
+function freeze(value) {
+  if (value && typeof value === "object") { for (const entry of Object.values(value)) freeze(entry); Object.freeze(value); }
+  return value;
+}
+export function createResourceContext({ packageURL, generatedURL, contractsURL, templatesURL, expectedVersion } = {}) {
+  if (![packageURL, generatedURL, contractsURL].every(value => value instanceof URL && value.protocol === "file:")
+      || (templatesURL !== null && templatesURL !== undefined
+        && (!(templatesURL instanceof URL) || templatesURL.protocol !== "file:"))) throw new Error("runtime_resources_unavailable");
+  const packageRoot = fileURLToPath(packageURL), generatedRoot = fileURLToPath(generatedURL);
+  expectedVersion ??= JSON.parse(readFileSync(new URL("package.json", packageURL), "utf8")).version;
+  const pluginDefinition = JSON.parse(readFileSync(new URL("plugins/agdf/meta/agdf-plugin.definition.json", generatedURL), "utf8"));
+  const interactionLocales = JSON.parse(readFileSync(new URL("plugins/agdf/meta/agdf-interaction-locales.json", generatedURL), "utf8"));
+  if (typeof expectedVersion !== "string" || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(expectedVersion) || pluginDefinition.version !== expectedVersion
+      || !Array.isArray(pluginDefinition.runtimeContract?.modules) || !pluginDefinition.runtimeContract.modules.length
+      || new Set(pluginDefinition.runtimeContract.modules).size !== pluginDefinition.runtimeContract.modules.length
+      || pluginDefinition.runtimeContract.modules.some(path => !/^meta\/contracts\/[a-z0-9-]+\.md$/u.test(path))
+      || !Array.isArray(pluginDefinition.skillSet) || !interactionLocales.locales?.[interactionLocales.fallbackLocale]) throw new Error("runtime_resources_unavailable");
+  validateInteractionCatalog(interactionLocales);
+  return freeze({
+    packageRoot,
+    generatedRoot,
+    contractsRoot: fileURLToPath(contractsURL),
+    templatesRoot: templatesURL instanceof URL ? fileURLToPath(templatesURL) : null,
+    pluginDefinition,
+    interactionLocales,
+  });
+}
+export const resources = createResourceContext({ packageURL, generatedURL, contractsURL, templatesURL });
+export const { packageRoot, generatedRoot, pluginDefinition, interactionLocales } = resources;
+export function configuredLanguage(value, context = resources) {
+  const normalized = canonicalizeLanguageTag(value);
+  if (!normalized) return "";
+  const language = normalized.split("-")[0];
+  if (context.interactionLocales.locales[normalized] || context.interactionLocales.locales[language]) return resolvePresentationLocale(context.interactionLocales, normalized);
+  return normalized;
+}
+export function resolveConfiguredChatLanguage(targetDir, context = resources) {
+  const configPath = join(targetDir, ".agdf", "control", "config.json");
+  if (!existsSync(configPath)) return context.interactionLocales.fallbackLocale;
+  try { return resolvePresentationLocale(context.interactionLocales, JSON.parse(readFileSync(configPath, "utf8")).chat_language); }
+  catch { return context.interactionLocales.fallbackLocale; }
+}
+// Missing or invalid config means English artefacts.
+export function resolveConfiguredArtifactLanguage(targetDir) {
+  try { return canonicalizeLanguageTag(JSON.parse(readFileSync(join(targetDir, ".agdf", "control", "config.json"), "utf8")).artifact_language).split("-")[0] || "en"; }
+  catch { return "en"; }
+}
+
+// Shared by artefact authoring and approval rendering; the selected locale may override
+// the configured chat default, but never changes the persisted artefact language.
+export function resolveArtifactPresentationLanguages(targetDir, requestedLanguage, context = resources) {
+  const artifactLanguage = resolveConfiguredArtifactLanguage(targetDir);
+  const presentationLanguage = requestedLanguage
+    ? resolvePresentationLocale(context.interactionLocales, requestedLanguage)
+    : resolveConfiguredChatLanguage(targetDir, context);
+  const required = artifactLanguage !== presentationLanguage.split("-")[0];
+  return Object.freeze({
+    artifact_language: artifactLanguage,
+    presentation_language: presentationLanguage,
+    approval_summary_required: required,
+    approval_summary_heading: required ? `AGDF Approval Summary (${presentationLanguage}; source=${artifactLanguage})` : null,
+  });
+}

package/runtime/core/lib/resources/contracts.js

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { join, basename } from "node:path";
+import { createHash } from "node:crypto";
+import { resources } from "./context.js";
+export function runtimeContractModules(definition = resources.pluginDefinition) {
+  return definition.runtimeContract.modules.map(path => basename(path, ".md"));
+}
+export function readRuntimeContract(module, { context = resources } = {}) {
+  const modules = runtimeContractModules(context.pluginDefinition);
+  if (!modules.includes(module)) return Object.freeze({ ok: false, reason: "module_unknown", modules });
+  const path = join(context.contractsRoot, `${module}.md`);
+  try { return Object.freeze({ ok: true, module, path, content: readFileSync(path, "utf8") }); }
+  catch { return Object.freeze({ ok: false, reason: "module_unavailable", modules }); }
+}
+export function readSkillRuntimeContracts(skillId, { context = resources } = {}) {
+  const modules = context.pluginDefinition.skillSet.find(skill => skill.slug === skillId)?.runtimeContractModules;
+  if (!Array.isArray(modules) || !modules.length || new Set(modules).size !== modules.length) throw new Error("runtime_contracts_unavailable");
+  return Object.freeze(modules.map(module => {
+    const result = readRuntimeContract(module, { context });
+    if (!result.ok || !result.content.trim()) throw new Error("runtime_contracts_unavailable");
+    return Object.freeze({ module, content: result.content, sha256: createHash("sha256").update(result.content).digest("hex") });
+  }));
+}

package/runtime/core/lib/runtime/distribution-profile-history.js

@@ -0,0 +1,173 @@
+import { createHash } from "node:crypto";
+
+const SHA256 = /^[a-f0-9]{64}$/;
+const RELEASE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const TOP_LEVEL_KEYS = ["contracts", "releases", "schema_version"];
+const CONTRACT_KEYS = ["contract_digest", "distribution_profiles"];
+const RELEASE_KEYS = ["contract_id", "entry_digest", "profile_id", "provenance_schema_version", "status"];
+
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+  return value;
+}
+
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+function digest(value) {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+
+function exactKeys(value, expected) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && JSON.stringify(Object.keys(value).sort()) === JSON.stringify(expected);
+}
+
+function sortedKeys(value) {
+  const keys = Object.keys(value);
+  return JSON.stringify(keys) === JSON.stringify([...keys].sort());
+}
+
+function invalid(reason) {
+  return { status: "invalid", reason };
+}
+
+export function canonicalDistributionProfileDigest(distributionProfiles) {
+  return digest(distributionProfiles);
+}
+
+export function canonicalDistributionProfileEntryDigest({
+  version,
+  contract_id,
+  contract_digest,
+  provenance_schema_version = 1,
+  profile_id = "runtime-plugin",
+  status = "supported",
+}) {
+  return digest({
+    version,
+    contract_id,
+    contract_digest,
+    provenance_schema_version,
+    profile_id,
+    status,
+  });
+}
+
+export function validateDistributionProfileHistory(catalogue) {
+  if (!exactKeys(catalogue, TOP_LEVEL_KEYS)
+      || catalogue.schema_version !== 1
+      || !catalogue.contracts || typeof catalogue.contracts !== "object" || Array.isArray(catalogue.contracts)
+      || !catalogue.releases || typeof catalogue.releases !== "object" || Array.isArray(catalogue.releases)
+      || !sortedKeys(catalogue.contracts)
+      || !sortedKeys(catalogue.releases)
+      || Object.keys(catalogue.contracts).length === 0
+      || Object.keys(catalogue.releases).length === 0) {
+    return invalid("profile_history_invalid");
+  }
+
+  const contractDigests = new Set();
+  for (const contract of Object.values(catalogue.contracts)) {
+    if (!exactKeys(contract, CONTRACT_KEYS)
+        || !contract.distribution_profiles
+        || typeof contract.distribution_profiles !== "object"
+        || Array.isArray(contract.distribution_profiles)
+        || !SHA256.test(contract.contract_digest ?? "")
+        || canonicalDistributionProfileDigest(contract.distribution_profiles) !== contract.contract_digest) {
+      return invalid("profile_history_invalid");
+    }
+    if (contractDigests.has(contract.contract_digest)) return invalid("profile_history_invalid");
+    contractDigests.add(contract.contract_digest);
+  }
+
+  const referencedContracts = new Set();
+  for (const [version, release] of Object.entries(catalogue.releases)) {
+    const contract = catalogue.contracts[release?.contract_id];
+    if (!RELEASE_VERSION.test(version)
+        || !exactKeys(release, RELEASE_KEYS)
+        || !contract
+        || release.provenance_schema_version !== 1
+        || release.profile_id !== "runtime-plugin"
+        || release.status !== "supported"
+        || !SHA256.test(release.entry_digest ?? "")) {
+      return invalid("profile_history_invalid");
+    }
+    referencedContracts.add(release.contract_id);
+    const expectedDigest = canonicalDistributionProfileEntryDigest({
+      version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      provenance_schema_version: release.provenance_schema_version,
+      profile_id: release.profile_id,
+      status: release.status,
+    });
+    if (release.entry_digest !== expectedDigest) return invalid("profile_history_invalid");
+  }
+  if (referencedContracts.size !== Object.keys(catalogue.contracts).length) {
+    return invalid("profile_history_invalid");
+  }
+
+  return { status: "matched", reason: "profile_history_valid" };
+}
+
+export function classifyHistoricalDistributionProfile({ catalogue, version, distributionProfiles }) {
+  const validation = validateDistributionProfileHistory(catalogue);
+  if (validation.status !== "matched") {
+    return {
+      status: "invalid",
+      reason: "profile_history_invalid",
+      release_version: null,
+      contract_id: null,
+      contract_digest: null,
+      entry_digest: null,
+    };
+  }
+  const release = Object.hasOwn(catalogue.releases, version) ? catalogue.releases[version] : null;
+  if (!release) {
+    return {
+      status: "unsupported",
+      reason: "historical_contract_unsupported",
+      release_version: null,
+      contract_id: null,
+      contract_digest: null,
+      entry_digest: null,
+    };
+  }
+  const contract = catalogue.contracts[release.contract_id];
+  if (!distributionProfiles || typeof distributionProfiles !== "object" || Array.isArray(distributionProfiles)) {
+    return {
+      status: "invalid",
+      reason: "historical_contract_invalid",
+      release_version: version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      entry_digest: release.entry_digest,
+    };
+  }
+  const observedDigest = canonicalDistributionProfileDigest(distributionProfiles);
+  if (observedDigest !== contract.contract_digest
+      || canonicalJson(distributionProfiles) !== canonicalJson(contract.distribution_profiles)) {
+    return {
+      status: "invalid",
+      reason: "historical_contract_invalid",
+      release_version: version,
+      contract_id: release.contract_id,
+      contract_digest: contract.contract_digest,
+      entry_digest: release.entry_digest,
+    };
+  }
+  return {
+    status: "matched",
+    reason: "historical_contract_matched",
+    release_version: version,
+    contract_id: release.contract_id,
+    contract_digest: contract.contract_digest,
+    entry_digest: release.entry_digest,
+  };
+}