create-agdf 0.20.2 → 0.30.0

package/runtime/core/lib/control-state/control-layout.js

@@ -0,0 +1,183 @@
+import { CURRENT_RUN_VERSION } from './run-identity.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { existsSync, lstatSync, mkdirSync, readdirSync, unlinkSync, openSync, writeFileSync, fsyncSync, closeSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { atomicWrite, fsyncDirectory, withOwnedFileLock } from '../owned-file-lock.js';
+import { hasSymlinkComponent, containedRegularFile } from './contained-file.js';
+import { exactObject, canonicalJson } from './approval-command-contract.js';
+import { REVISION_ID_PATTERN } from './run-identity.js';
+import { readContainedControlText } from '../control-read/snapshot.js';
+import { currentInputResolution, isOriginalInputResolution, bindInputResolution, resolutionRecord, recordedInputResolution } from './input-resolution.js';
+
+import { CURRENT_LAYOUT } from './run-identity.js';
+export { CURRENT_LAYOUT } from './run-identity.js';
+const CONFIG = '.agdf/control/config.json';
+const MAINTENANCE = '.agdf/control/maintenance';
+const CLAIMS = `${MAINTENANCE}/admission`;
+const active = new AsyncLocalStorage();
+export function markControlMutationEffect() {
+  const mutation = active.getStore();
+  if (mutation) mutation.effectStarted = true;
+}
+export const currentControlMutationId = () => active.getStore()?.operation_id ?? null;
+// Git scope checks may exclude only the active owner's exact transient claims.
+// Another operation's files, or replaced claim bytes, remain foreign evidence.
+export function currentOwnedMutationClaimPaths(root) {
+  const mutation = active.getStore();
+  if (mutation?.root !== root) return [];
+  const claims = mutation.claim ? [{ path: mutation.claim.path, digest: hash(mutation.claim.text) }] : mutation.recoveryClaims ?? [];
+  return claims.map(claim => {
+    if (hash(read(root, claim.path, 4096)) !== claim.digest) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+    return claim.path;
+  });
+}
+export function markControlMutationRollbackKnown(resource) {
+  const mutation = active.getStore();
+  if (mutation && (!resource || mutation.resource === resource)) mutation.effectStarted = false;
+}
+const hash = value => 'sha256:' + createHash('sha256').update(value).digest('hex');
+const fail = code => { throw Error(code); };
+
+function read(root, path, limit = 65536) {
+  if (hasSymlinkComponent(root, path) || containedRegularFile(root, path).status !== 'valid') fail('AGDF_CONTROL_PATH_INVALID');
+  return readContainedControlText(root, path, limit);
+}
+
+export function readControlLayout(root, { live = false } = {}) {
+  const captured = currentInputResolution()?.configuration;
+  const original = !live && isOriginalInputResolution() && captured?.root === root && captured.control === 'active' ? captured : null;
+  const originalSnapshot = () => {
+    if (original.control_layout !== CURRENT_LAYOUT) fail('AGDF_CONTROL_LAYOUT_UNSUPPORTED');
+    return Object.freeze({ layout: CURRENT_LAYOUT, generation: original.config_digest, config: null });
+  };
+  let text, config;
+  try { text = read(root, CONFIG); config = JSON.parse(text.replace(/^\uFEFF/u, '')); }
+  catch (error) { if (original) return originalSnapshot(); if (error.message === 'AGDF_CONTROL_PATH_INVALID') throw error; fail('AGDF_CONTROL_LAYOUT_INVALID'); }
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    if (original) return originalSnapshot(); fail('AGDF_CONTROL_LAYOUT_INVALID');
+  }
+  if (config.control_layout !== CURRENT_LAYOUT) { if (original) return originalSnapshot(); fail('AGDF_CONTROL_LAYOUT_UNSUPPORTED'); }
+  return Object.freeze({ layout: CURRENT_LAYOUT, generation: original ? originalSnapshot().generation : hash(text), config });
+}
+
+export function assertLayoutRunWrite(root, state) {
+  const layout = readControlLayout(root);
+  if (state.meta.control_state_version !== String(CURRENT_RUN_VERSION)) fail('AGDF_RUN_VERSION_UNSUPPORTED');
+  return layout;
+}
+
+function ensureDirectory(root, path) {
+  if (hasSymlinkComponent(root, path)) fail('AGDF_CONTROL_PATH_INVALID');
+  const file = join(root, path);
+  if (!existsSync(file)) {
+    try { mkdirSync(file, { mode: 0o700 }); fsyncDirectory(dirname(file)); }
+    catch (error) { if (error.code !== 'EEXIST') throw error; }
+  }
+  const stat = lstatSync(file);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) fail('AGDF_CONTROL_PATH_INVALID');
+}
+
+function ensureAdmission(root) {
+  ensureDirectory(root, MAINTENANCE); ensureDirectory(root, CLAIMS);
+}
+
+function publishClaim(root, relative, text) {
+  // Exclusive publication cannot replace an unknown pre-existing claim.
+  const path = join(root, relative), fd = openSync(path, 'wx', 0o600);
+  try { writeFileSync(fd, text); fsyncSync(fd); } finally { closeSync(fd); }
+  fsyncDirectory(dirname(path));
+}
+
+function retireClaim(root, claim) {
+  if (read(root, claim.path, 4096) !== claim.text) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  unlinkSync(join(root, claim.path)); fsyncDirectory(join(root, CLAIMS));
+}
+
+// Call after the resource lock, before publishing any product effect. Independent
+// claims have no shared exclusive lock. Nested owners retain the outer admission.
+export function withControlMutation(root, { resource, operation_id = null, checkpoint = () => {}, resume = false, proveOutcome } = {}, work) {
+  const inherited = active.getStore();
+  if (inherited?.root === root) return work(inherited.layout);
+  if (typeof resource !== 'string' || !resource || resource.length > 512) fail('AGDF_CONTROL_RESOURCE_INVALID');
+  if (operation_id !== null && !REVISION_ID_PATTERN.test(operation_id)) fail('AGDF_CONTROL_RESOURCE_INVALID');
+  ensureAdmission(root);
+  if (resume && operation_id && inspectMutationClaims(root, { strict: false }).some(row => row.resource === resource && row.operation_id === operation_id))
+    return withControlRecovery(root, { resource, operation_id, proveOutcome }, work);
+  const layout = readControlLayout(root);
+  checkpoint('before_claim');
+  const id = randomUUID(), path = `${CLAIMS}/${id}.json`;
+  const text = JSON.stringify({ schema_version: 1, id, resource, operation_id, generation: layout.generation, pid: process.pid }) + '\n';
+  const claim = { path, text };
+  publishClaim(root, path, text);
+  let admitted = false;
+  const mutation = { root, layout, claim, resource, operation_id, effectStarted: false };
+  try {
+    checkpoint('claim_published');
+    if (readControlLayout(root).generation !== layout.generation) fail('AGDF_CONTROL_MAINTENANCE_REQUIRED');
+    admitted = true;
+    checkpoint('admitted');
+    const result = active.run(mutation, () => work(layout));
+    if (result && typeof result.then === 'function') fail('AGDF_CONTROL_ASYNC_MUTATION_UNSUPPORTED');
+    const observed = result?.rejection ?? result;
+    if (mutation.effectStarted && (['recovery_required', 'effect_unknown'].includes(observed?.outcome)
+      || /recovery_required|effect_unknown/u.test(observed?.reason ?? ''))) {
+      return { ...result, admission_claim: { path, digest: hash(text) } };
+    }
+    retireClaim(root, claim);
+    return result;
+  } catch (error) {
+    // Known rollback/rejection may retire. An uncertain transaction keeps its claim
+    // until the original operation is explicitly recovered and its outcome proven.
+    const uncertain = admitted && mutation.effectStarted;
+    if (uncertain) error.admission_claim = { path, digest: hash(text) };
+    else retireClaim(root, claim);
+    throw error;
+  }
+}
+
+export function inspectMutationClaims(root, { strict = true } = {}) {
+  if (hasSymlinkComponent(root, CLAIMS)) fail('AGDF_CONTROL_PATH_INVALID');
+  if (!existsSync(join(root, CLAIMS))) return [];
+  if (!lstatSync(join(root, CLAIMS)).isDirectory()) fail('AGDF_CONTROL_PATH_INVALID');
+  const names = readdirSync(join(root, CLAIMS));
+  if (names.length > 4096) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  return names.sort().map(name => {
+    try {
+    if (!/^[0-9a-f-]{36}\.json$/u.test(name)) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+    const path = `${CLAIMS}/${name}`, text = read(root, path, 4096);
+    let claim; try { claim = JSON.parse(text); } catch { fail('AGDF_CONTROL_ADMISSION_UNKNOWN'); }
+    if (!exactObject(claim, ['schema_version', 'id', 'resource', 'operation_id', 'generation', 'pid']) || claim.schema_version !== 1
+      || !REVISION_ID_PATTERN.test(claim.id) || name !== `${claim.id}.json` || typeof claim.resource !== 'string'
+      || !claim.resource || claim.resource.length > 512 || !/^sha256:[a-f0-9]{64}$/u.test(claim.generation)
+      || claim.operation_id !== null && !REVISION_ID_PATTERN.test(claim.operation_id)
+      || !Number.isSafeInteger(claim.pid) || claim.pid <= 0) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+    return { ...claim, path, digest: hash(text) };
+    } catch (error) { if (strict) throw error; return null; }
+  }).filter(Boolean);
+}
+
+// An original admitted operation may finish while maintenance is draining it.
+// This does not admit new effects: the caller holds its resource lock and must
+// prove the original transaction's exact recorded or rolled-back outcome.
+export function withControlRecovery(root, { resource, operation_id, proveOutcome }, work) {
+  if (!REVISION_ID_PATTERN.test(operation_id) || typeof proveOutcome !== 'function') fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  const claims = inspectMutationClaims(root, { strict: false }).filter(row => row.resource === resource && row.operation_id === operation_id);
+  if (!claims.length) return withControlMutation(root, { resource, operation_id }, work);
+  const layout = readControlLayout(root);
+  if (claims.some(row => row.generation !== layout.generation)) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  const result = active.run({ root, layout, resource, operation_id, recoveryClaims: claims, effectStarted: false }, work);
+  if (result && typeof result.then === 'function' || proveOutcome(result) !== true) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  for (const claim of claims) retireRecoveredMutationClaim(root, { ...claim, proveOutcome: () => true });
+  return result;
+}
+
+// No timeout/liveness heuristic removes claims. The recovery owner supplies proof
+// of the original operation's known outcome and the exact inspected claim bytes.
+export function retireRecoveredMutationClaim(root, { path, digest, proveOutcome }) {
+  const observed = inspectMutationClaims(root, { strict: false }).find(row => row.path === path && row.digest === digest);
+  if (!observed || typeof proveOutcome !== 'function' || proveOutcome(observed) !== true) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  const text = read(root, path, 4096);
+  if (hash(text) !== digest) fail('AGDF_CONTROL_ADMISSION_UNKNOWN');
+  retireClaim(root, { path, text });
+}

package/runtime/core/lib/control-state/decision-action-contract.js

@@ -1,4 +1,4 @@
-import { strictObject, schemaDiagnostics, RUN_COMMAND_LIMITS, RUN_COMMAND_GROUPS } from './run-command-contract.js';
+import { strictObject, schemaDiagnostics, RUN_COMMAND_LIMITS, RUN_COMMAND_GROUPS } from './run-command-schema.js';
 import { REVISION_ID_PATTERN } from './run-identity.js';
 import { canonicalJson, digest } from './approval-command-contract.js';
 
@@ -30,3 +30,12 @@ export function decisionActionDefinition(groups) {
     inputSchema: decisionActionSchema(actions), _meta: { ui: { resourceUri: DECISION_UI_URI, visibility: ['app'] } } });
 }
 export const decisionActionRequestDigest = (binding, input) => digest(`agdf-app-decision/1\0${canonicalJson({ binding, input })}`);
+
+export const DECISION_VIEW_SCHEMA = strictObject({ primary_target: { type: 'string', minLength: 1, maxLength: 4096 },
+  target_id: { type: 'string', pattern: '^sha256:[0-9a-f]{64}$' }, run_id: { type: 'string', pattern: '^[A-Za-z0-9_-]{1,128}$' },
+  expected_revision_id: uuid, gate: { enum: ['UR', 'PRD', 'SD', 'TP', 'QA', 'UAT'] }, presentation_id: uuid });
+export const DECISION_VIEW_DEFINITION = Object.freeze({ name: 'agdf_decision_view',
+  description: 'Optional non-primary preview of a prepared decision. Display is unconfirmed until the bound live view is observed. Then call presentation.deliver; absent current-surface proof selects Markdown.',
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false }, inputSchema: DECISION_VIEW_SCHEMA,
+  _meta: { ui: { resourceUri: DECISION_UI_URI, visibility: ['model', 'app'] } } });
+export function validateDecisionView(input) { return schemaDiagnostics(input, DECISION_VIEW_SCHEMA); }

package/runtime/core/lib/control-state/decision-action-service.js

@@ -1,3 +1,7 @@
+import { createInputResolution, withInputResolution } from './input-resolution.js';
+import { inspectRunInputResolution } from './run-input-resolution.js';
+import { resolveConfiguration } from '../resources/configuration.js';
+import { resources } from '../resources/context.js';
 import { withLiveControlReads } from '../control-read/fs.js';
 import { evaluateGateCheck } from '../control-evaluation/gate-check.js';
 import { executeApprovalCommand } from './approval-command.js';
@@ -31,20 +35,37 @@ export function createDecisionActionService({ enabledGroups = Object.keys(RUN_CO
     if (diagnostics.length) return { schema_version: '1', outcome: 'rejected', reason: 'decision_schema_invalid', diagnostics, authorizes: false };
     if (!actions.includes(input.action)) return result('rejected', 'command_group_disabled');
     if (!appOnlyMediationQualified) return result('rejected', 'app_only_mediation_not_qualified');
+    const target = resolveControlCommandTarget(root);
     if (input.presentation_id !== binding.presentation_id || input.expected_revision_id !== binding.expected_revision_id
-      || resolveControlCommandTarget(root).target_id !== binding.target_id) return result('rejected', 'decision_binding_invalid');
+      || target.target_id !== binding.target_id) return result('rejected', 'decision_binding_invalid');
+    root = target.root;
     const requestDigest = decisionActionRequestDigest(binding, input);
     let dispatched = false;
     try {
+      const publicInput = { schema_version: '1', assurance: 'cooperative_local', working_directory: root, primary_target: root,
+        target_source: 'explicit_target', target_id: binding.target_id, run_id: binding.run_id,
+        expected_revision_id: binding.expected_revision_id, operation_id: input.operation_id,
+        ...(binding.presentation_language ? { presentation_language: binding.presentation_language } : {}),
+        command: { kind: input.action === 'approve' ? 'approval.record' : 'presentation_decision.record', payload: {} } };
+      const original = inspectRunInputResolution(root, publicInput);
+      if (original?.known && (!original.resolution || original.resolution.logical_digest !== requestDigest)) return result('rejected', 'operation_payload_conflict');
+      const configuration = original?.resolution?.configuration ?? resolveConfiguration(root, resources.defaults,
+        binding.presentation_language ? { chat_language: binding.presentation_language } : {});
+      // The private App facade already owns a request digest over the held binding
+      // and complete gesture, including its inert comment. Retain that identity;
+      // the common current resolution codec binds the same project preferences.
+      const resolution = original?.resolution ?? { ...createInputResolution(publicInput,
+        { ...publicInput, presentation_language: configuration.values.chat_language }, configuration),
+        logical_digest: requestDigest, effective_digest: requestDigest };
       checkpoint('before_dispatch'); dispatched = true;
-      const family = input.action === 'approve'
+      const family = withInputResolution(resolution, () => input.action === 'approve'
         ? executeApprovalCommand(root, { schema_version: '1', action: 'record_gate_approval', target_id: binding.target_id, run_id: binding.run_id,
           expected_revision_id: binding.expected_revision_id, operation_id: input.operation_id, assurance: 'cooperative_local', gate: binding.gate,
           presentation_id: binding.presentation_id, response: `Approval: ${binding.gate}` }, { evaluateGateCheck, packageVersion, checkpoint,
           commandContext: { kind: 'approval.record', operation_id: input.operation_id, target_id: binding.target_id, request_digest: requestDigest } })
         : recordRunPresentationDecision(root, { runId: binding.run_id, gate: binding.gate, revisionId: binding.expected_revision_id,
           operationId: input.operation_id, presentationId: binding.presentation_id, action: input.action, comment: input.comment ?? '', requestDigest },
-        { evaluateGateCheck, packageVersion, afterWrite: checkpoint });
+        { evaluateGateCheck, packageVersion, afterWrite: checkpoint }), original?.known === true);
       checkpoint('before_result');
       return result(['accepted', 'recorded'].includes(family.outcome) ? 'accepted' : family.outcome === 'already_applied' ? 'already_applied'
         : ['retryable_failure', 'recovery_required'].includes(family.outcome) ? 'effect_unknown' : 'rejected', family.reason, family);

package/runtime/core/lib/control-state/decision-material-contract.js

@@ -1,10 +1,11 @@
+import { runDocumentPath } from './run-identity.js';
 import { canonicalJson, digest, DIGEST_PATTERN } from './approval-command-contract.js';
 
 export function validDecisionMaterial(sources, runId) {
   return Array.isArray(sources) && sources.length > 0 && sources.length <= 12
     && new Set(sources.map(s => s?.type)).size === sources.length
     && sources.every(s => s && Object.keys(s).sort().join(',') === 'digest,path,type' && typeof s.type === 'string'
-      && typeof s.path === 'string' && s.path.startsWith(`.agdf/control/artefacts/${runId}/`)
+      && typeof s.path === 'string' && s.path.startsWith(`${runDocumentPath(runId, '')}/`)
       && !s.path.includes('..') && DIGEST_PATTERN.test(s.digest ?? ''));
 }
 

package/runtime/core/lib/control-state/evidence-bindings.js

@@ -1,9 +1,11 @@
+import { runDocumentPath, runEvidencePath } from './run-identity.js';
 import { createHash } from 'node:crypto';
 import { canonicalJson, digest, exactObject, DIGEST_PATTERN, COOPERATIVE_ASSURANCE } from './approval-command-contract.js';
 import { RUN_ID_PATTERN, REVISION_ID_PATTERN } from './run-identity.js';
 import { isSafeControlRelativePath } from './contained-file.js';
 
 export const EVIDENCE_PREREQUISITES = Object.freeze({
+  'Verified Change': ['UR'],
   ur: [], route: ['UR'], 'Brownfield Review': ['UR'], 'UX Intent Definition': ['UR', 'Brownfield Review'],
   'Brownfield Analysis': ['UR', 'PRD', 'SD', 'TP', 'Brownfield Review', 'UX Intent Definition'],
   'CD+Tests': ['UR', 'PRD', 'SD', 'TP', 'Brownfield Analysis'],
@@ -13,21 +15,19 @@ export const EVIDENCE_PREREQUISITES = Object.freeze({
 });
 // Reviews a structured closeout requires (closeout-readiness.js). Gate order and late
 // recording use the same list, so no route can be approved into an unclosable state.
-export const STRUCTURED_REQUIRED_REVIEWS = Object.freeze(['TP Review', 'Clean Implementation Review']);
-// `Clean Review` is the supported legacy name of the Clean Implementation Review row.
-export const reviewArtefactType = (state, step) => step === 'Clean Implementation Review' && !state.artefacts.get(step)?.path
-  && state.artefacts.get('Clean Review')?.path ? 'Clean Review' : step;
+export { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType } from "../control-evaluation/gate-policy-inputs.js";
+import { STRUCTURED_REQUIRED_REVIEWS, reviewArtefactType } from "../control-evaluation/gate-policy-inputs.js";
 // Reviews whose normalized findings closeout inspects; at OR they may be recorded again only
 // to correct invalid rows (run-operation-proof.js, presentation-decision.js).
 export const CORRECTABLE_REVIEWS = Object.freeze([...STRUCTURED_REQUIRED_REVIEWS, 'CR']);
 export const evidenceSourceSetDigest = sources => digest(`agdf-operation-sources/1\0${canonicalJson(sources)}`);
 export const canonicalEvidenceDigest = text => 'sha256:' + createHash('sha256').update(String(text).replace(/\r\n?/gu, '\n').replace(/^\uFEFF/u, '')).digest('hex');
 const hash = value => typeof value === 'string' && DIGEST_PATTERN.test(value);
-const ownPath = (value, runId) => isSafeControlRelativePath(value) && value.startsWith(`.agdf/control/artefacts/${runId}/`);
+const ownPath = (value, runId) => isSafeControlRelativePath(value) && [runDocumentPath(runId, ''), runEvidencePath(runId, '')].some(prefix => value.startsWith(`${prefix}/`));
 export function validEvidenceBinding(row) {
   return exactObject(row, ['schema_version', 'run_id', 'operation_id', 'action', 'step', 'report', 'sources', 'source_set_digest', 'producer', 'assurance'])
-    && row.schema_version === '1' && RUN_ID_PATTERN.test(row.run_id ?? '') && REVISION_ID_PATTERN.test(row.operation_id ?? '')
-    && ['step.record', 'artefact.record'].includes(row.action) && Object.hasOwn(EVIDENCE_PREREQUISITES, row.step)
+    && row.schema_version === (row.action === 'ur_draft.replace' ? '2' : '1') && RUN_ID_PATTERN.test(row.run_id ?? '') && REVISION_ID_PATTERN.test(row.operation_id ?? '')
+    && ['step.record', 'ur_draft.replace', 'artefact.record'].includes(row.action) && (row.action !== 'ur_draft.replace' || row.step === 'ur') && Object.hasOwn(EVIDENCE_PREREQUISITES, row.step)
     && exactObject(row.report, ['path', 'digest']) && ownPath(row.report.path, row.run_id) && hash(row.report.digest)
     && Array.isArray(row.sources) && row.sources.length === EVIDENCE_PREREQUISITES[row.step].length
     && row.sources.every((s, i) => exactObject(s, ['type', 'path', 'digest', 'status']) && s.type === EVIDENCE_PREREQUISITES[row.step][i]

package/runtime/core/lib/control-state/git-identity.js

@@ -0,0 +1,86 @@
+import { readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+
+// Pure read of the local Git identity for a cooperative confirmation statement. No child
+// process, no include or includeIf directive; an identity found nowhere is recorded unknown.
+// Precedence as in Git: repository config, then ~/.gitconfig, then the XDG config file.
+const CONFIG_LIMIT = 1048576;
+function readText(path) {
+  try { const stat = statSync(path); return stat.isFile() && stat.size <= CONFIG_LIMIT ? readFileSync(path, 'utf8') : null; } catch { return null; }
+}
+const isDirectory = path => { try { return statSync(path).isDirectory(); } catch { return false; } };
+const isFile = path => { try { return statSync(path).isFile(); } catch { return false; } };
+
+// The repository config of the nearest .git directory, or of a .git file's gitdir and its commondir.
+function repositoryConfig(root) {
+  for (let directory = resolve(root); ; directory = dirname(directory)) {
+    const dotGit = join(directory, '.git');
+    let gitDir = isDirectory(dotGit) ? dotGit : null;
+    if (!gitDir && isFile(dotGit)) {
+      const target = readText(dotGit)?.match(/^gitdir:[ \t]*(.+?)[ \t]*\r?$/mu)?.[1];
+      if (target) gitDir = resolve(directory, target);
+    }
+    if (gitDir) {
+      const common = readText(join(gitDir, 'commondir'))?.trim();
+      return join(common ? resolve(gitDir, common) : gitDir, 'config');
+    }
+    if (dirname(directory) === directory) return null;
+  }
+}
+
+export function gitConfigPaths(root, { env = process.env, home = homedir() } = {}) {
+  const xdg = env.XDG_CONFIG_HOME && isAbsolute(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : home ? join(home, '.config') : null;
+  return [repositoryConfig(root), home ? join(home, '.gitconfig') : null, xdg ? join(xdg, 'git', 'config') : null].filter(Boolean);
+}
+
+// Value grammar: leading blanks skipped, double quotes group, \\ \" \n \t \b escapes,
+// # or ; outside quotes start a comment, trailing blanks outside quotes are dropped.
+function configValue(raw) {
+  let value = '', quoted = false, pending = '';
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    if (char === '\\') {
+      const next = raw[++i];
+      value += pending + ({ n: '\n', t: '\t', b: '\b', '"': '"', '\\': '\\' }[next] ?? ''); pending = ''; continue;
+    }
+    if (char === '"') { value += pending; pending = ''; quoted = !quoted; continue; }
+    if (!quoted && (char === '#' || char === ';')) break;
+    if (!quoted && (char === ' ' || char === '\t')) { if (value) pending += char; continue; }
+    value += pending + char; pending = '';
+  }
+  return value;
+}
+
+// Last assignment within one file wins, as in Git; sections other than plain [user] are ignored.
+export function parseGitIdentity(text) {
+  const found = {};
+  let section = null;
+  for (const rawLine of String(text ?? '').replace(/^/u, '').split(/\r?\n/u)) {
+    let line = rawLine.trim();
+    const header = line.match(/^\[([^\]"]+?)(?:\s+"(?:[^"\\]|\\.)*")?\]/u);
+    if (header) {
+      section = /\s+"/u.test(line.slice(0, header[0].length)) ? null : header[1].trim().toLowerCase();
+      line = line.slice(header[0].length).trim();
+    }
+    if (section !== 'user' || !line || line.startsWith('#') || line.startsWith(';')) continue;
+    const pair = line.match(/^([A-Za-z][A-Za-z0-9-]*)\s*=(.*)$/u);
+    const key = pair?.[1].toLowerCase();
+    if (key === 'name' || key === 'email') found[key] = configValue(pair[2]);
+  }
+  return found;
+}
+
+const clean = value => {
+  const text = String(value ?? '').replace(/[\u0000-\u001f\u007f]+/gu, ' ').replaceAll('|', '/').replace(/\s+/gu, ' ').trim().slice(0, 256).trim();
+  return text || null;
+};
+export function readGitIdentity(root, options = {}) {
+  const identity = {};
+  for (const path of gitConfigPaths(root, options)) {
+    const values = parseGitIdentity(readText(path));
+    for (const key of ['name', 'email']) if (!Object.hasOwn(identity, key) && Object.hasOwn(values, key)) identity[key] = clean(values[key]);
+  }
+  return identity.name || identity.email
+    ? { name: identity.name ?? null, email: identity.email ?? null, statement: 'cooperative' } : { statement: 'unknown' };
+}

package/runtime/core/lib/control-state/index.js

@@ -2,7 +2,6 @@ export * from "./run-state-parser.js";
 export * from "./run-state-repository.js";
 export * from "./run-state-resolver.js";
 export * from "./run-state-writer.js";
-export * from "./legacy-migration.js";
 export * from "./aggregate.js";
 export * from "./gate-approval-validator.js";
 export * from "./run-seal.js";

package/runtime/core/lib/control-state/input-resolution.js

@@ -0,0 +1,99 @@
+import { CURRENT_LAYOUT } from './run-identity.js';
+// Shared representation, not a file owner or replay ledger. Existing operation
+// families alone validate, persist and recover their versioned records.
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { isAbsolute } from 'node:path';
+import { canonicalJson, exactObject, DIGEST_PATTERN } from './approval-command-contract.js';
+import { runCommandRequestDigest } from './run-command-schema.js';
+import { canonicalizeLanguageTag } from '../interaction-presentation.js';
+
+const context = new AsyncLocalStorage();
+const FORMAT = 'resolved/1';
+const paths = ['presentation_language', 'working_directory', 'schema_version', 'assurance', 'variant', 'command.payload.route'];
+const preferenceKeys = ['chat_language', 'artifact_language', 'presentation_route', 'gate_check_variant'];
+const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const hash = value => typeof value === 'string' && DIGEST_PATTERN.test(value);
+const tag = value => typeof value === 'string' && value.length > 0 && value.length <= 64 && canonicalizeLanguageTag(value) === value;
+const get = (value, path) => path.split('.').reduce((v, key) => v?.[key], value);
+function set(value, path, selected) {
+  const keys = path.split('.'); let parent = value;
+  for (const key of keys.slice(0, -1)) parent = parent[key];
+  parent[keys.at(-1)] = selected;
+}
+export const currentInputResolution = () => context.getStore()?.resolution ?? null;
+export const isOriginalInputResolution = () => context.getStore()?.original === true;
+export const withInputResolution = (resolution, action, original = false) => context.run({ resolution: resolution ?? null, original }, action);
+export function createInputResolution(original, effective, configuration) {
+  return { schema_version: 1, logical_digest: runCommandRequestDigest(original), effective_digest: runCommandRequestDigest(effective),
+    operation_id: original.operation_id ?? null, kind: original.command?.kind ?? null,
+    fields: Object.fromEntries(paths.filter(path => get(original, path) === undefined && get(effective, path) !== undefined).map(path => [path, get(effective, path)])), configuration };
+}
+export function validInputResolution(value) {
+  if (!exactObject(value, ['schema_version', 'logical_digest', 'effective_digest', 'operation_id', 'kind', 'fields', 'configuration']) || value.schema_version !== 1
+    || !(value.operation_id === null || typeof value.operation_id === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u.test(value.operation_id))
+    || !(value.kind === null || typeof value.kind === 'string' && /^[a-z_]+\.[a-z_]+$/u.test(value.kind) && value.kind.length <= 64)
+    || !hash(value.logical_digest) || !hash(value.effective_digest) || !plain(value.fields) || !plain(value.configuration)
+    || Buffer.byteLength(canonicalJson(value)) > 8192 || Object.keys(value.fields).some(key => !paths.includes(key))) return false;
+  const f = value.fields, c = value.configuration;
+  if (Object.hasOwn(f, 'presentation_language') && !tag(f.presentation_language)
+    || Object.hasOwn(f, 'working_directory') && (typeof f.working_directory !== 'string' || !isAbsolute(f.working_directory) || f.working_directory.length > 4096)
+    || Object.hasOwn(f, 'schema_version') && f.schema_version !== '1'
+    || Object.hasOwn(f, 'assurance') && f.assurance !== 'cooperative_local'
+    || Object.hasOwn(f, 'variant') && !['status-card', 'approval-envelope'].includes(f.variant)
+    || Object.hasOwn(f, 'command.payload.route') && !['markdown', 'automatic', 'fallback'].includes(f['command.payload.route'])) return false;
+  if (!exactObject(c, ['root', 'control', 'config_digest', 'values', 'sources', 'defaults_digest', 'control_layout'])
+    || (c.control === 'active' ? c.control_layout !== CURRENT_LAYOUT : c.control_layout !== null)
+    || !(c.root === null || typeof c.root === 'string' && isAbsolute(c.root) && c.root.length <= 4096) || !['inactive', 'active'].includes(c.control)
+    || !(c.config_digest === null || hash(c.config_digest)) || !hash(c.defaults_digest)
+    || !exactObject(c.values, preferenceKeys) || !exactObject(c.sources, preferenceKeys)
+    || !tag(c.values.chat_language) || !tag(c.values.artifact_language)
+    || !['markdown', 'automatic', 'fallback'].includes(c.values.presentation_route)
+    || ![null, 'status-card', 'approval-envelope'].includes(c.values.gate_check_variant)) return false;
+  if (c.control === 'active' && (c.root === null || c.config_digest === null)
+    || c.control === 'inactive' && c.config_digest !== null
+    || Object.hasOwn(f, 'presentation_language') && f.presentation_language !== c.values.chat_language
+    || Object.hasOwn(f, 'variant') && f.variant !== c.values.gate_check_variant
+    || Object.hasOwn(f, 'command.payload.route') && f['command.payload.route'] !== c.values.presentation_route) return false;
+  return preferenceKeys.every(key => {
+    const source = c.sources[key];
+    return exactObject(source, ['kind']) && source.kind === 'explicit'
+      || exactObject(source, ['kind', 'path', 'digest']) && (source.kind === 'plugin' && source.path === 'meta/agdf-defaults.json'
+        && source.digest === c.defaults_digest || source.kind === 'project' && source.path === '.agdf/control/config.json'
+        && c.control === 'active' && source.digest === c.config_digest) && hash(source.digest);
+  });
+}
+export function restoreResolvedInput(original, resolution) {
+  if (!validInputResolution(resolution) || runCommandRequestDigest(original) !== resolution.logical_digest) throw Error('AGDF_OPERATION_PAYLOAD_CONFLICT');
+  const effective = structuredClone(original);
+  for (const [path, value] of Object.entries(resolution.fields)) set(effective, path, value);
+  if (runCommandRequestDigest(effective) !== resolution.effective_digest) throw Error('AGDF_OPERATION_PAYLOAD_CONFLICT');
+  return effective;
+}
+export function bindInputResolution(record) {
+  const resolution = currentInputResolution();
+  // Dispatch/read inputs have no typed command UUID or command digest. Their
+  // per-call preferences may flow to rendering, never into a family receipt.
+  if (!resolution?.kind || !resolution.operation_id) throw Error('input_resolution_required');
+  if (!validInputResolution(resolution)) throw Error('input_resolution_invalid');
+  return { ...record, schema_version: FORMAT, input_resolution: { ...resolution, record_version: record.schema_version } };
+}
+export function resolutionRecord(record) {
+  if (record?.schema_version !== FORMAT) return null;
+  const { input_resolution: extension, ...body } = record;
+  if (!plain(extension)) return null;
+  const { record_version, ...resolution } = extension;
+  if (!['string', 'number'].includes(typeof record_version) || !validInputResolution(resolution)) return null;
+  // Pending journals retain the owning family's digest (approval/revision have
+  // their own domain digest). The committed receipt binds the full command and
+  // journal recovery cross-checks both retained resolutions below that owner.
+  const storedDigest = Object.hasOwn(body, 'old_run_digest') || body.kind === 'lifecycle_close.record'
+    ? undefined : body.command_digest ?? body.operation?.request_digest ?? body.request_digest;
+  if (storedDigest !== undefined && storedDigest !== resolution.effective_digest) return null;
+  return { ...body, schema_version: record_version };
+}
+export const resolutionRecordVersion = record => resolutionRecord(record)?.schema_version;
+export function recordedInputResolution(record) {
+  if (record?.schema_version !== FORMAT || !resolutionRecord(record)) return null;
+  const { record_version, ...resolution } = record.input_resolution;
+  return resolution;
+}