@entrorove/skill 0.1.51 → 0.1.53

package/local-scope-import-expressions.mjs

@@ -0,0 +1,80 @@
+import path from 'node:path';
+import ts from 'typescript';
+
+const limits = Object.freeze({ alternatives: 64, nodes: 512, depth: 32 });
+function unwrap(node) {
+  while (node && (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
+  return node;
+}
+function sourceChecker(source) {
+  const name = path.posix.resolve('/', source.fileName.replaceAll('\\', '/'));
+  const matches = value => path.posix.resolve('/', value.replaceAll('\\', '/')) === name;
+  const host = { getSourceFile: filename => matches(filename) ? source : undefined,
+    getDefaultLibFileName: () => '/entrorove-no-library.d.ts', writeFile: () => {},
+    getCurrentDirectory: () => '/', getDirectories: () => [], fileExists: matches,
+    readFile: filename => matches(filename) ? source.text : undefined,
+    getCanonicalFileName: filename => filename, useCaseSensitiveFileNames: () => true, getNewLine: () => '\n' };
+  return ts.createProgram([name], { noLib: true, noResolve: true, allowJs: true }, host).getTypeChecker();
+}
+function product(left, right) {
+  if (!left || !right || left.length * right.length > limits.alternatives) return null;
+  return [...new Set(left.flatMap(prefix => right.map(suffix => prefix + suffix)))];
+}
+/** Resolve literal alternatives without executing source, trusting type assertions, or reading other files. */
+export function createScopeImportResolver(source, suppliedChecker) {
+  let checker = suppliedChecker;
+  const resolve = expression => {
+    let nodes = 0;
+    const values = (raw, seen = new Set(), depth = 0) => {
+      const node = unwrap(raw);
+      if (!node || depth > limits.depth || ++nodes > limits.nodes) return null;
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return [node.text];
+      if (ts.isConditionalExpression(node)) {
+        const left = values(node.whenTrue, seen, depth + 1), right = values(node.whenFalse, seen, depth + 1);
+        return left && right && left.length + right.length <= limits.alternatives ? [...new Set([...left, ...right])] : null;
+      }
+      if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+        return product(values(node.left, seen, depth + 1), values(node.right, seen, depth + 1));
+      }
+      if (ts.isTemplateExpression(node)) {
+        let result = [node.head.text];
+        for (const span of node.templateSpans) {
+          result = product(result, values(span.expression, seen, depth + 1));
+          if (!result) return null;
+          result = result.map(value => value + span.literal.text);
+        }
+        return result;
+      }
+      if (!ts.isIdentifier(node)) return null;
+      checker ??= sourceChecker(source);
+      const declarations = checker.getSymbolAtLocation(node)?.declarations;
+      if (declarations?.length !== 1) return null;
+      const declaration = declarations[0];
+      if (seen.has(declaration) || declaration.getSourceFile() !== source) return null;
+      const next = new Set([...seen, declaration]);
+      if (ts.isVariableDeclaration(declaration) && ts.isVariableDeclarationList(declaration.parent)
+        && declaration.parent.flags & ts.NodeFlags.Const && declaration.initializer
+        && !(ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Ambient)
+        && !source.isDeclarationFile) return values(declaration.initializer, next, depth + 1);
+      return null;
+    };
+    const alternatives = values(expression);
+    if (alternatives?.some(value => !value || /[\u0000-\u001f\u007f]/.test(value))) {
+      throw Object.assign(new Error('module literal is empty or contains control characters'), { code: 'ENTROROVE_IMPORT_INVALID' });
+    }
+    return alternatives?.sort() ?? null;
+  };
+  return resolve;
+}
+
+export function unresolvedImportSite(source, expression) {
+  const node = unwrap(expression), position = source.getLineAndCharacterOfPosition((node ?? source).getStart(source));
+  const kind = node ? ts.SyntaxKind[node.kind] : 'MissingArgument';
+  const reason = node && ts.isIdentifier(node) ? 'import-binding-not-finite-constant'
+    : node && ts.isTemplateExpression(node) ? 'import-template-has-unbounded-substitution'
+      : node && ts.isBinaryExpression(node) ? 'import-concatenation-has-unbounded-operand'
+        : 'import-expression-not-statically-finite';
+  return { line: position.line + 1, column: position.character + 1, kind, reason,
+    message: `Cannot verify ${kind} import: only immutable literal alternatives (at most ${limits.alternatives}) are statically bounded; runtime values and mutable bindings remain unresolved` };
+}

package/local-scope-repository.mjs

@@ -13,6 +13,8 @@ import { observeBudgetScopeGit, scopeGitBudgetEnforced } from './local-scope-git
 import { scopeGitMetadata } from './local-scope-git-reads.mjs';
 import { scopeTsconfigImports } from './local-scope-config-imports.mjs';
 import { scopeGitExecutable } from './local-git-executable.mjs';
+import { createScopeImportResolver, unresolvedImportSite } from './local-scope-import-expressions.mjs';
+import { isTypeOnlyReference, isDynamicFunctionReference } from './local-typescript-function-reference.mjs';
 
 const execute = promisify(execFile);
 async function git(root, args, allowed = [], input = { repositoryRoot: root }) {
@@ -94,11 +96,6 @@ function staticString(expression) {
   if (!expression || (!ts.isStringLiteral(expression) && !ts.isNoSubstitutionTemplateLiteral(expression))) return null;
   return expression.text;
 }
-function moduleLiteral(expression) {
-  const value = staticString(expression);
-  if (value !== null && (!value || /[\u0000-\u001f\u007f]/.test(value))) scopeFail('ENTROROVE_IMPORT_INVALID', 'module literal is empty or contains control characters');
-  return value;
-}
 function globalObject(expression) {
   while (expression && (ts.isParenthesizedExpression(expression) || ts.isAsExpression(expression)
     || ts.isTypeAssertionExpression(expression) || ts.isNonNullExpression(expression) || ts.isSatisfiesExpression(expression))) expression = expression.expression;
@@ -106,12 +103,16 @@ function globalObject(expression) {
 }
 // The same pinned TypeScript parser as the cloud scope analyzer visits actual
 // expressions inside templates and JSX; literal bodies never become code.
-function scriptImports(source, filename) {
+function scriptImports(source, filename, context = {}) {
   const parsed = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true,
     scriptKinds.get(path.extname(filename).toLowerCase()) ?? ts.ScriptKind.TS);
   if (parsed.parseDiagnostics.length) scopeFail('ENTROROVE_IMPORT_INVALID', 'source has invalid or unterminated syntax');
-  const found = new Set(); let dynamic = false;
-  const add = expression => { const value = moduleLiteral(expression); if (value === null) dynamic = true; else found.add(value); };
+  const found = new Set(), unresolvedImports = [], resolve = createScopeImportResolver(parsed); let dynamic = false;
+  const add = expression => {
+    const values = resolve(expression);
+    if (values === null) { dynamic = true; unresolvedImports.push(unresolvedImportSite(parsed, expression)); }
+    else for (const value of values) found.add(value);
+  };
   const visit = node => {
     if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) { if (node.moduleSpecifier) add(node.moduleSpecifier); }
     else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) add(node.moduleReference.expression);
@@ -120,24 +121,29 @@ function scriptImports(source, filename) {
       const importer = node.expression.kind === ts.SyntaxKind.ImportKeyword;
       const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
       if (importer || requireCall) {
-        if (!node.arguments.length || node.arguments.length > (importer ? 2 : 1)) dynamic = true;
+        if (!node.arguments.length || node.arguments.length > (importer ? 2 : 1)) {
+          dynamic = true;
+          unresolvedImports.push({ ...unresolvedImportSite(parsed, node), reason: 'import-argument-list-not-supported',
+            message: 'Import inspection requires one module argument and at most one import-attributes argument' });
+        }
         else add(node.arguments[0]);
       }
     }
-    if (ts.isIdentifier(node)) {
-      if (dynamicNames.has(node.text)) dynamic = true;
+    const runtimeReference = !isTypeOnlyReference(node);
+    if (runtimeReference && ts.isIdentifier(node)) {
+      if (dynamicNames.has(node.text) && (node.text !== 'Function' || isDynamicFunctionReference(node, context))) dynamic = true;
       if (node.text === 'require' && !(ts.isCallExpression(node.parent) && node.parent.expression === node)
         && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node)
         && !(ts.isMethodDeclaration(node.parent) && node.parent.name === node)) dynamic = true;
     }
-    if (ts.isElementAccessExpression(node)) {
+    if (runtimeReference && ts.isElementAccessExpression(node)) {
       const member = staticString(node.argumentExpression);
       if (dynamicNames.has(member) || member === 'require' || member === null && globalObject(node.expression)) dynamic = true;
     }
-    if (ts.isPropertyAccessExpression(node) && node.name.text === 'require' && globalObject(node.expression)) dynamic = true;
+    if (runtimeReference && ts.isPropertyAccessExpression(node) && node.name.text === 'require' && globalObject(node.expression)) dynamic = true;
     ts.forEachChild(node, visit);
   };
-  visit(parsed); return { specifiers: [...found].sort(), dynamic };
+  visit(parsed); return { specifiers: [...found].sort(), dynamic, unresolvedImports };
 }
 function vueScripts(source, filename) {
   const { descriptor, errors } = parseVue(source, { filename, sourceMap: false,
@@ -152,7 +158,8 @@ function vueScripts(source, filename) {
     const language = block.lang ?? 'js';
     if (!['js', 'javascript', 'ts', 'typescript', 'jsx', 'tsx'].includes(language)) scopeFail('ENTROROVE_IMPORT_UNSUPPORTED', 'component script language is unsupported');
     const extension = { javascript: 'js', typescript: 'ts' }[language] ?? language;
-    scripts.push({ source: block.src ? `import ${JSON.stringify(block.src)};` : block.content, filename: `${filename}.${extension}` });
+    scripts.push({ source: block.src ? `import ${JSON.stringify(block.src)};` : block.content, filename: `${filename}.${extension}`,
+      lineOffset: block.loc.start.line - 1, vueComponent: true, vueSetup: block === descriptor.scriptSetup });
   }
   const seen = new WeakSet();
   const walk = node => {
@@ -172,10 +179,11 @@ function vueScripts(source, filename) {
 function importSpecifiers(content, filename) {
   try {
     const source = content.toString('utf8'), parts = path.extname(filename).toLowerCase() === '.vue' ? vueScripts(source, filename) : [{ source, filename }];
-    const specifiers = new Set(); let dynamic = false;
-    for (const part of parts) { const parsed = scriptImports(part.source, part.filename); dynamic ||= parsed.dynamic;
+    const specifiers = new Set(), unresolvedImports = []; let dynamic = false;
+    for (const part of parts) { const parsed = scriptImports(part.source, part.filename, part); dynamic ||= parsed.dynamic;
+      unresolvedImports.push(...parsed.unresolvedImports.map(site => ({ ...site, line: site.line + (part.lineOffset ?? 0) })));
       for (const specifier of parsed.specifiers) specifiers.add(specifier); }
-    return { specifiers: [...specifiers].sort(), dynamic };
+    return { specifiers: [...specifiers].sort(), dynamic, unresolvedImports };
   } catch (error) {
     if (typeof error?.code === 'string' && error.code.startsWith('ENTROROVE_')) throw error;
     if (error instanceof RangeError) scopeFail('ENTROROVE_SCOPE_LIMIT', 'dependency syntax exceeds the supported parser or traversal bound');
@@ -250,7 +258,7 @@ async function resolveLocalImport(root, relative, required = true) {
 export async function importGraph(root, originals, input = { repositoryRoot: root }, limits = {}) {
   const pending = originals.filter(file => file.exists !== false).map(file => file.path); const visited = new Map(); const edges = []; let dynamic = false;
   let sourceBytes = 0;
-  const dynamicSources = [];
+  const dynamicSources = [], unresolvedImports = [];
   const workspace = await workspaceIndex(root, input);
   const metadata = new Map(workspace.metadata.map(item => [item.path, item]));
   while (pending.length) {
@@ -273,6 +281,7 @@ export async function importGraph(root, originals, input = { repositoryRoot: roo
     for (const observed of aliases.observations) metadata.set(observed.path, observed);
     const declarations = declarationModules(read.content, relative);
     const imports = importSpecifiers(read.content, relative); dynamic ||= imports.dynamic;
+    unresolvedImports.push(...imports.unresolvedImports.map(site => ({ path: relative, ...site })));
     if (imports.dynamic) dynamicSources.push({ path: relative, sha256: read.sha256 });
     for (const specifier of imports.specifiers.sort()) {
       const target = await resolveImport(root, relative, specifier, workspace, input, aliases, configPath, declarations);
@@ -286,7 +295,8 @@ export async function importGraph(root, originals, input = { repositoryRoot: roo
   const workspaceMetadata = [...metadata.values()].sort((a, b) => a.path.localeCompare(b.path));
   await stableScope(root, workspaceMetadata, input);
   return { nodes, edges: edges.sort((a, b) => `${a.from}:${a.specifier}`.localeCompare(`${b.from}:${b.specifier}`)),
-    dynamic, complete: !dynamic, dynamicSources: dynamicSources.sort((a, b) => a.path.localeCompare(b.path)), workspaceMetadata };
+    dynamic, complete: !dynamic, dynamicSources: dynamicSources.sort((a, b) => a.path.localeCompare(b.path)), workspaceMetadata,
+    ...(unresolvedImports.length ? { unresolvedImports } : {}) };
 }
 export async function scopeCandidateImports(root, file, input = { repositoryRoot: root }) {
   const parsed = importSpecifiers(Buffer.from(file.content), file.path);
@@ -299,7 +309,8 @@ export async function scopeCandidateImports(root, file, input = { repositoryRoot
     const target = await resolveImport(root, file.path, specifier, workspace, input, aliases, context?.configPath, declarations);
     edges.push({ from: file.path, to: target, external: target === null, specifier });
   }
-  return { edges, dynamic: parsed.dynamic };
+  return { edges, dynamic: parsed.dynamic,
+    ...(parsed.unresolvedImports.length ? { unresolvedImports: parsed.unresolvedImports.map(site => ({ path: file.path, ...site })) } : {}) };
 }
 export async function collectScopeFacts(root, requested, baselineRef, knownFiles = [], input = { repositoryRoot: root }) {
   const selected = await scopeFiles(root, requested, knownFiles); const files = [];

package/local-typescript-function-reference.mjs

@@ -0,0 +1,98 @@
+import ts from 'typescript';
+
+const bindings = new WeakMap();
+const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : null;
+const wrapper = node => ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node)
+  || ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node);
+const unwrap = node => {
+  while (node && wrapper(node)) node = node.expression;
+  return node;
+};
+export function isTypeOnlyReference(node) {
+  for (let current = node; current?.parent; current = current.parent) {
+    const parent = current.parent;
+    if (ts.isExpressionWithTypeArguments(parent) && ts.isHeritageClause(parent.parent)) {
+      return parent.parent.token !== ts.SyntaxKind.ExtendsKeyword
+        || !(ts.isClassDeclaration(parent.parent.parent) || ts.isClassExpression(parent.parent.parent));
+    }
+    if (ts.isTypeNode(parent) || ts.isInterfaceDeclaration(parent) || ts.isTypeAliasDeclaration(parent)
+      || ts.isTypeParameterDeclaration(parent)) return true;
+    if ((ts.isImportClause(parent) || ts.isImportSpecifier(parent)) && parent.isTypeOnly) return true;
+  }
+  return false;
+}
+function bindingNames(node) {
+  if (ts.isIdentifier(node)) return [node.text];
+  if (ts.isObjectBindingPattern(node) || ts.isArrayBindingPattern(node)) {
+    return node.elements.flatMap(element => ts.isBindingElement(element) ? bindingNames(element.name) : []);
+  }
+  return [];
+}
+function sourceBindings(source) {
+  if (bindings.has(source)) return bindings.get(source);
+  const found = new Map();
+  const add = (name, api = null) => found.set(name, [...found.get(name) ?? [], api]);
+  const visit = node => {
+    if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node)) {
+      let declaration = node.parent;
+      while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
+      const vue = declaration && ts.isStringLiteral(declaration.moduleSpecifier) && declaration.moduleSpecifier.text === 'vue'
+        && !declaration.importClause?.isTypeOnly && !node.isTypeOnly;
+      add(node.name.text, vue ? ts.isNamespaceImport(node) ? '*' : (node.propertyName ?? node.name).text : null);
+    } else if (ts.isImportClause(node) && node.name) add(node.name.text);
+    else if (ts.isVariableDeclaration(node) || ts.isParameter(node)) bindingNames(node.name).forEach(name => add(name));
+    else if ((ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isClassDeclaration(node)
+      || ts.isClassExpression(node) || ts.isImportEqualsDeclaration(node) || ts.isEnumDeclaration(node)) && node.name) add(node.name.text);
+    ts.forEachChild(node, visit);
+  };
+  visit(source); bindings.set(source, found); return found;
+}
+function vueCall(node, api, context) {
+  if (!ts.isCallExpression(node) || node.arguments.length !== 1) return false;
+  const expression = unwrap(node.expression), found = sourceBindings(node.getSourceFile());
+  if (ts.isIdentifier(expression)) {
+    const declarations = found.get(expression.text) ?? [];
+    return declarations.length === 1 && declarations[0] === api
+      || api === 'defineProps' && context.vueSetup === true && expression.text === api && !declarations.length;
+  }
+  return ts.isPropertyAccessExpression(expression) && expression.name.text === api && ts.isIdentifier(expression.expression)
+    && found.get(expression.expression.text)?.length === 1 && found.get(expression.expression.text)[0] === '*';
+}
+function transparentParent(node) {
+  while (node.parent && wrapper(node.parent) && node.parent.expression === node) node = node.parent;
+  return node;
+}
+function vuePropsContainer(node, context) {
+  const value = transparentParent(node), parent = value.parent;
+  if (parent && vueCall(parent, 'defineProps', context) && parent.arguments[0] === value) return true;
+  if (!ts.isPropertyAssignment(parent) || propertyName(parent.name) !== 'props' || parent.initializer !== value) return false;
+  const component = transparentParent(parent.parent), owner = component.parent;
+  return context.vueComponent === true && ts.isExportAssignment(owner) && owner.expression === component
+    || owner && vueCall(owner, 'defineComponent', context) && owner.arguments[0] === component;
+}
+function vueFunctionMetadata(node, context) {
+  let value = transparentParent(node);
+  if (ts.isArrayLiteralExpression(value.parent)) value = transparentParent(value.parent);
+  const field = value.parent;
+  if (!ts.isPropertyAssignment(field) || field.initializer !== value) return false;
+  let props = field.parent;
+  if (ts.isObjectLiteralExpression(props) && vuePropsContainer(props, context)) return true;
+  if (propertyName(field.name) === 'type') {
+    const descriptor = transparentParent(props), property = descriptor.parent;
+    if (!ts.isPropertyAssignment(property) || property.initializer !== descriptor) return false;
+    props = property.parent;
+  }
+  return ts.isObjectLiteralExpression(props) && vuePropsContainer(props, context);
+}
+function declarationName(node) {
+  const parent = node.parent;
+  return parent?.name === node && (ts.isPropertyAssignment(parent) || ts.isPropertySignature(parent)
+    || ts.isMethodDeclaration(parent) || ts.isMethodSignature(parent) || ts.isPropertyDeclaration(parent)
+    || ts.isFunctionDeclaration(parent) || ts.isClassDeclaration(parent) || ts.isVariableDeclaration(parent)
+    || ts.isParameter(parent) || ts.isEnumDeclaration(parent) || ts.isEnumMember(parent)
+    || ts.isImportSpecifier(parent) || ts.isImportClause(parent));
+}
+export function isDynamicFunctionReference(node, context = {}) {
+  if (!ts.isIdentifier(node) || node.text !== 'Function') return false;
+  return !isTypeOnlyReference(node) && !declarationName(node) && !vueFunctionMetadata(node, context);
+}

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "entrorove.skill-manifest/1.0",
   "name": "entrorove",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "endpoint": "https://entrorove.com",
   "requestSchemaVersion": "entrorove.skill.request/2.0",
   "supportedRequestSchemaVersions": [

package/mutation-client.mjs

@@ -0,0 +1,290 @@
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { mutationId14, mutationPaths14, mutationTarget14, mutationFail14, privateMutationDirectory14,
+  readMutationJson14, atomicMutationJson14 } from './local-mutation-files.mjs';
+import { preparePreservedMutationSigner, preservedMutationLocation } from './local-preserved-mutation-signer.mjs';
+import { snapshotPlan14, snapshotVerify14 } from './local-mutation-snapshot.mjs';
+import { attestMutationSnapshot14 } from './local-mutation-binding.mjs';
+import { issueMutationPass14 } from './local-mutation-authority.mjs';
+import { readStoredMutationPass14 } from './local-mutation-pass-store.mjs';
+import { mutationChallenge14, mutationPass14 } from './local-mutation-wire.mjs';
+import { buildInvocation, invokeRemoteResult } from './remote-client.mjs';
+import { parseTransportResponse, requestTransport, trustedOrigin } from './remote-transport.mjs';
+import { acknowledgeAutomaticFeedback, verifyAutomaticFeedback, queryAutomaticFeedback } from './automatic-feedback-client.mjs';
+import { ideClientHeaders } from './ide-presentation.mjs';
+import { appendInvocation, readInvocations } from './local-invocations.mjs';
+import { bootstrapCloudMutationAuthority } from './cloud-mutation-authority.mjs';
+import { attestMutationConsumption14, preservedMutationConsumptionState } from './local-mutation-consumption.mjs';
+
+const schema = 'entrorove.mutation-connection-state/1.0';
+const fields = ['taskId', 'flowId', 'stepId', 'leaseId', 'generation', 'runnerId', 'paths'];
+const fail = message => mutationFail14('ENTROROVE_MUTATION_CONNECTION_BINDING', message);
+const unknown = requestId => Object.assign(new Error(`Mutation connection outcome is unknown; recover original requestId=${requestId} without repeating its POST`),
+  { outcomeUnknown: true, requestId });
+const notSent = requestId => Object.assign(new Error('Mutation operation was not transmitted; repair its local or discovery prerequisite and reuse the original input'),
+  { code: 'ENTROROVE_MUTATION_CONNECTION_NOT_SENT', requestId, knownBeforeTransmission: true });
+const save = (location, value) => atomicMutationJson14(location.file, value, { privateFrom: location.stateRoot, replace: true });
+function inputIdentity(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)
+    || canonical(Object.keys(input).sort()) !== canonical([...fields, ...['previousPassId'].filter(field => Object.hasOwn(input, field))].sort())
+    || !Number.isSafeInteger(input.generation) || input.generation < 1) {
+    mutationFail14('ENTROROVE_MUTATION_CONNECTION_INPUT', 'Mutation connection requires its exact original task, flow, step, lease, generation, runner and existing paths');
+  }
+  for (const field of fields.filter(field => !['generation', 'paths'].includes(field))) mutationId14(input[field], field);
+  if (Object.hasOwn(input, 'previousPassId')) mutationId14(input.previousPassId, 'previousPassId');
+  return { ...input, paths: mutationPaths14(input.paths) };
+}
+async function readConnection(location, identity) {
+  let value;
+  try { value = await readMutationJson14(location.file); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!value) return { schemaVersion: schema, identity };
+  if (value.schemaVersion !== schema || canonical(value.identity) !== canonical(identity)
+    || value.pending && (value.pending.requestId !== buildInvocation(value.pending.operation, value.pending.input).requestId
+      || !['mutation-snapshot-challenge', 'mutation-pass-issue', 'mutation-pass-settle'].includes(value.pending.operation))) {
+    fail('Mutation connection journal differs from the original repository, request or physical key');
+  }
+  return value;
+}
+async function recoverRemote(pending, dependencies) {
+  try {
+    const token = await dependencies.readCredential(dependencies.home), origin = trustedOrigin(dependencies.apiOrigin());
+    const response = await requestTransport(origin, `/api/skill/status/${pending.requestId}`, { headers: { authorization: `Bearer ${token}`, ...ideClientHeaders() } });
+    const result = await parseTransportResponse(response, 'original mutation connection status');
+    if (!response.ok || result?.output?.requestId !== pending.requestId || ['running', 'pending'].includes(result.output.status)) throw unknown(pending.requestId);
+    result.feedback ??= await queryAutomaticFeedback(pending.requestId, dependencies);
+    verifyAutomaticFeedback(result.feedback, pending.requestId, pending.requestId);
+    result.feedback = await acknowledgeAutomaticFeedback(result.feedback, origin, token, ideClientHeaders());
+    await appendInvocation({ kind: 'remote', operation: 'status', requestId: pending.requestId, event: 'status', usage: result.usage ?? [] }, dependencies.home);
+    return { response, result };
+  } catch { throw unknown(pending.requestId); }
+}
+async function knownNotSent(error, pending, home) {
+  if (error?.requestId && error.requestId !== pending.requestId || error?.retryableBeforeTransmission === true) return true;
+  try {
+    const records = (await readInvocations(home)).filter(value => value.kind === 'remote' && value.requestId === pending.requestId);
+    return !records.length || records.at(-1).event === 'not-sent';
+  } catch (cause) { return cause.code === 'ENOENT'; }
+}
+async function remote(stage, operation, input, state, location, dependencies) {
+  const requestId = buildInvocation(operation, input).requestId;
+  let response, result;
+  if (state.pending) {
+    if (state.pending.stage !== stage || state.pending.operation !== operation || canonical(state.pending.input) !== canonical(input)) {
+      fail('Recover the original mutation request before another operation or input');
+    }
+    ({ response, result } = await recoverRemote(state.pending, dependencies));
+  } else {
+    state.pending = { stage, operation, input, requestId };
+    try { await save(location, state); } catch { throw notSent(requestId); }
+    try { ({ response, result } = await invokeRemoteResult({ operation, input }, dependencies)); }
+    catch (error) {
+      if (await knownNotSent(error, state.pending, dependencies.home)) {
+        delete state.pending;
+        try { await save(location, state); } catch { throw notSent(requestId); }
+        throw notSent(requestId);
+      }
+      throw unknown(requestId);
+    }
+  }
+  delete state.pending;
+  if (!response.ok || !['succeeded', 'reported'].includes(result?.output?.status)) {
+    try { await save(location, state); } catch { throw unknown(requestId); }
+    throw Object.assign(new Error(result?.output?.message ?? `Mutation connection blocked at ${operation}`),
+      { code: result?.output?.code ?? 'ENTROROVE_MUTATION_CONNECTION_BLOCKED', output: result?.output, requestId });
+  }
+  state[stage] = result.output;
+  if (result.feedback) state.feedback = result.feedback;
+  try { await save(location, state); } catch { throw unknown(requestId); }
+  return result.output;
+}
+function challengeBinding(challenge, identity, mutator, options) {
+  mutationChallenge14(challenge, options);
+  if ([...fields, 'previousPassId'].some(field => canonical(challenge[field]) !== canonical(identity[field])) || challenge.repositoryDigest !== sha256(identity.repositoryRoot).slice(0, 32)
+    || challenge.newFilePaths.length || !challenge.writeDelegation
+    || challenge.writeDelegation.mutationKeyId !== mutator.mutationKeyId || challenge.writeDelegation.mutationPublicKey !== mutator.mutationPublicKey) {
+    fail('Mutation challenge must retain the original task, lease, physical repository, paths and separate M signer');
+  }
+}
+function passBinding(pass, challenge, attestation, options) {
+  mutationPass14(pass, options);
+  if (pass.challengeId !== challenge.challengeId || pass.challengeDigest !== sha256(canonical(challenge))
+    || pass.attestationDigest !== sha256(canonical(attestation)) || pass.snapshotDigest !== attestation.manifest.snapshotDigest
+    || [...fields, 'previousPassId'].some(field => canonical(pass[field]) !== canonical(challenge[field]))
+    || canonical(pass.writeDelegation) !== canonical(challenge.writeDelegation)) fail('Mutation pass differs from its original signed challenge or actual M snapshot');
+}
+async function snapshot(input, challenge, state, location) {
+  if (!state.planned) {
+    if (state.planStarted) {
+      const recovered = await snapshotVerify14(input);
+      state.planned = { snapshotId: recovered.receipt.snapshotId, snapshotDigest: recovered.receipt.snapshotDigest };
+    } else {
+      state.planStarted = true; await save(location, state);
+      try { state.planned = await snapshotPlan14({ ...input, paths: challenge.paths, contractDigest: challenge.scopeContractDigest }); }
+      catch (error) { delete state.planStarted; await save(location, state); throw error; }
+    }
+    await save(location, state);
+  }
+  const verified = await snapshotVerify14(input);
+  if (verified.verified !== true || verified.receipt.snapshotDigest !== state.planned.snapshotDigest
+    || canonical(verified.receipt.paths) !== canonical(challenge.paths) || verified.receipt.contractDigest !== challenge.scopeContractDigest) {
+    fail('Original mutation snapshot copies or paths failed their actual verification');
+  }
+  return verified;
+}
+async function authorizeCachedConnection(identity, pass, dependencies) {
+  const token = await dependencies.readCredential(dependencies.home), origin = trustedOrigin(dependencies.apiOrigin());
+  let response, status;
+  try {
+    response = await requestTransport(origin, `/api/skill/flows/${identity.flowId}/status`, {
+      headers: { authorization: `Bearer ${token}`, ...ideClientHeaders() },
+    });
+    status = await parseTransportResponse(response, 'original mutation flow status');
+  } catch {
+    mutationFail14('ENTROROVE_MUTATION_CONNECTION_AUTHORIZATION', 'Current account could not confirm the original active mutation flow');
+  }
+  if (!response.ok || status?.schemaVersion !== 'entrorove.flow-status/1.0' || status.flow?.flowId !== identity.flowId
+    || status.flow.ownerId !== pass.ownerId || status.flow.stepId !== identity.stepId || status.flow.status !== 'running'
+    || !['execute', 'merge', 'deliver'].includes(status.workflow?.phase) || status.workflow.terminalAt
+    || ['pending', 'declined'].includes(status.workflow.authorization)) {
+    mutationFail14('ENTROROVE_MUTATION_CONNECTION_AUTHORIZATION', 'Current account must retain the original owned active flow and business step');
+  }
+}
+async function connect(identity, local, mutator, location, dependencies) {
+  const state = await readConnection(location, identity);
+  const challenged = state.challenged ?? await remote('challenged', 'mutation-snapshot-challenge',
+    { ...Object.fromEntries(fields.map(field => [field, identity[field]])),
+      ...(identity.previousPassId ? { previousPassId: identity.previousPassId } : {}), mutationPublicKey: mutator.mutationPublicKey }, state, location, dependencies);
+  const challenge = challenged.challenge;
+  challengeBinding(challenge, identity, mutator, { live: !state.gatePassPath });
+  const input = { ...local, snapshotId: challenge.snapshotId };
+  if (state.gatePassPath) {
+    passBinding(state.issued.pass, challenge, state.attestation, { live: false });
+    const stored = await readStoredMutationPass14({ ...input, gatePassPath: state.gatePassPath }, { live: false });
+    if (canonical(stored) !== canonical(state.issued.pass)) fail('Installed mutation pass differs from its original connection');
+    await authorizeCachedConnection(identity, stored, dependencies);
+    const consumption = await preservedMutationConsumptionState({ ...input, gatePassPath: state.gatePassPath });
+    if (consumption.complete) return { schemaVersion: 'entrorove.mutation-connection/1.0', status: 'blocked', flowId: identity.flowId,
+      code: 'ENTROROVE_MUTATION_SETTLEMENT_REQUIRED', gatePassPath: state.gatePassPath,
+      message: 'Original physical writes are consumed; settle their actual M receipt with fresh S evidence before requesting the next restricted pass',
+      localAction: { command: 'npx @entrorove/skill mutation-settle <absolute repositoryRoot>',
+        input: { taskId: stored.taskId, flowId: stored.flowId, stepId: stored.stepId, gatePassPath: state.gatePassPath } } };
+    passBinding(state.issued.pass, challenge, state.attestation);
+    return connected(identity, state);
+  }
+  await snapshot(input, challenge, state, location);
+  if (!state.attestation) {
+    const observed = await attestMutationSnapshot14({ ...input, challenge, signerConfigPath: mutator.signerConfigPath });
+    if (observed.verified !== true || observed.attestation.keyId !== mutator.mutationKeyId) fail('Actual mutation snapshot was not signed by its separate M key');
+    state.attestation = observed.attestation; await save(location, state);
+  }
+  const issued = state.issued ?? await remote('issued', 'mutation-pass-issue',
+    { challengeId: challenge.challengeId, attestation: state.attestation }, state, location, dependencies);
+  passBinding(issued.pass, challenge, state.attestation);
+  await authorizeCachedConnection(identity, issued.pass, dependencies);
+  const installed = await issueMutationPass14({ ...input, mutationPass: issued.pass });
+  if (canonical(installed.pass) !== canonical(issued.pass) || typeof installed.gatePassPath !== 'string') fail('Mutation gate did not install its exact original server pass');
+  state.gatePassPath = installed.gatePassPath; await save(location, state);
+  return connected(identity, state);
+}
+function connected(identity, state) {
+  return { schemaVersion: 'entrorove.mutation-connection/1.0', status: 'succeeded', taskId: identity.taskId,
+    flowId: identity.flowId, stepId: identity.stepId, gatePassPath: state.gatePassPath, pass: state.issued.pass,
+    purpose: 'preserved-existing-modify', grantsExecutionAuthority: false, grantsValidatorAuthority: false,
+    ...(state.feedback ? { feedback: state.feedback } : {}) };
+}
+export async function connectMutation(repositoryRoot, input, dependencies) {
+  const original = inputIdentity(input);
+  const local = { repositoryRoot, home: dependencies.home, taskId: original.taskId, flowId: original.flowId, stepId: original.stepId };
+  const location = await preservedMutationLocation(local);
+  local.repositoryRoot = location.root;
+  for (const relative of original.paths) {
+    const target = await mutationTarget14(location.root, relative, true);
+    if (!target.exists || !target.stat.isFile()) fail('Mutation connection permits only concrete existing files');
+  }
+  await bootstrapCloudMutationAuthority(dependencies);
+  const mutator = await preparePreservedMutationSigner(local);
+  const identity = { ...original, repositoryRoot: location.root, apiOrigin: trustedOrigin(dependencies.apiOrigin()), mutationKeyId: mutator.mutationKeyId };
+  const directory = path.join(location.directory, 'connections'); await privateMutationDirectory14(directory, { privateFrom: location.stateRoot });
+  const file = path.join(directory, `${sha256(canonical(identity))}.json`), journal = { ...location, file };
+  return withStateLock(file, () => connect(identity, local, mutator, journal, dependencies));
+}
+function settlementBinding(output, pass, receipt, expectedSettlementId) {
+  if (output?.settled !== true || typeof output.settlementId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(output.settlementId)
+    || expectedSettlementId !== undefined && output.settlementId !== expectedSettlementId
+    || output.passId !== pass.passId || output.consumptionReceiptDigest !== sha256(canonical(receipt))
+    || output.claimsVerifiedExecution !== false || output.claimsCompletion !== false) fail('Mutation settlement must preserve its original actual M receipt without claiming independent validation or completion');
+}
+async function settleMutation(repositoryRoot, input, dependencies) {
+  const required = ['flowId', 'stepId', 'gatePassPath'], optional = ['taskId'].filter(field => Object.hasOwn(input ?? {}, field));
+  if (!input || canonical(Object.keys(input).sort()) !== canonical([...required, ...optional].sort())
+    || !path.isAbsolute(input.gatePassPath ?? '')) fail('Mutation settlement requires the exact original stored pass and task step');
+  for (const field of ['flowId', 'stepId', ...optional]) mutationId14(input[field], field);
+  await bootstrapCloudMutationAuthority(dependencies);
+  const local = { ...input, repositoryRoot, home: dependencies.home }, original = await preservedMutationConsumptionState(local);
+  const { pass, binding } = original;
+  await authorizeCachedConnection({ flowId: pass.flowId, stepId: pass.stepId }, pass, dependencies);
+  const directory = path.join(binding.directory, 'settlements'); await privateMutationDirectory14(directory, { privateFrom: binding.stateRoot });
+  const location = { ...binding, file: path.join(directory, `${pass.passId}.json`) };
+  const identity = { flowId: pass.flowId, stepId: pass.stepId, passDigest: sha256(canonical(pass)),
+    repositoryRoot: binding.root, apiOrigin: trustedOrigin(dependencies.apiOrigin()), mutationKeyId: binding.binding.keyId };
+  return withStateLock(location.file, async () => {
+    const state = await readConnection(location, identity);
+    if (!state.settled && !state.pending && (!state.consumptionReceipt || state.rejection?.effects === 'none'
+      && state.rejection.code === 'ENTROROVE_MUTATION_CONSUMPTION_EXPIRED')) {
+      const observed = await attestMutationConsumption14(local, { allowExpiredReplay: true, renewExpired: state.rejection?.effects === 'none'
+        && state.rejection.code === 'ENTROROVE_MUTATION_CONSUMPTION_EXPIRED' });
+      state.consumptionReceipt = observed.consumptionReceipt; delete state.rejection; await save(location, state);
+    }
+    if (!state.consumptionReceipt) fail('Original mutation settlement receipt is missing; recover its original request without signing another');
+    let output = state.settled;
+    if (!output) {
+      try { output = await remote('settled', 'mutation-pass-settle', { passId: pass.passId, consumptionReceipt: state.consumptionReceipt }, state, location, dependencies); }
+      catch (error) {
+        if (error.output?.effects === 'none') { state.rejection = { effects: 'none', code: error.output.code }; await save(location, state); }
+        throw error;
+      }
+    }
+    settlementBinding(output, pass, state.consumptionReceipt, state.settlementId);
+    if (state.settlementId === undefined) { state.settlementId = output.settlementId; await save(location, state); }
+    return { schemaVersion: 'entrorove.mutation-settlement/1.0', status: 'reported', settled: true,
+      flowId: pass.flowId, taskId: pass.taskId, passId: pass.passId, settlementId: output.settlementId,
+      consumptionReceiptDigest: output.consumptionReceiptDigest,
+      claimsVerifiedExecution: false, claimsCompletion: false, ...(state.feedback ? { feedback: state.feedback } : {}),
+      observationAction: { command: 'npx @entrorove/skill workflow-observe-step <absolute repositoryRoot>', independentValidation: 'pending',
+        input: { taskId: pass.taskId, flowId: pass.flowId, stepId: pass.stepId, leaseId: pass.leaseId,
+          generation: pass.generation, settlementId: output.settlementId } },
+      localAction: { command: 'npx @entrorove/skill mutation-connect <absolute repositoryRoot>',
+        input: { ...Object.fromEntries(fields.map(field => [field, pass[field]])), previousPassId: pass.passId } } };
+  });
+}
+async function runMutationClient(operation, repositoryRoot, input, dependencies, work) {
+  let preflight = true;
+  try {
+    await dependencies.install();
+    if (!await dependencies.agreementAccepted(dependencies.home)) return dependencies.agreementRequired(dependencies.home);
+    preflight = false;
+    return await work(repositoryRoot, input, dependencies);
+  }
+  catch (error) {
+    const requestId = /^[a-f0-9]{64}$/.test(error?.requestId ?? '') ? error.requestId : undefined;
+    if (error?.outcomeUnknown === true && requestId) return {
+      schemaVersion: 'entrorove.mutation-connection/1.0', status: 'blocked', flowId: input?.flowId, requestId,
+      code: 'ENTROROVE_MUTATION_CONNECTION_OUTCOME_UNKNOWN', outcomeUnknown: true, recoverable: true,
+      message: `Original mutation request outcome is unknown; rerun ${operation} with the same input to recover only its original GET, without repeating its POST`,
+      nextAction: { operation, requestId, method: 'GET', reuseOriginalInput: true, repeatPost: false },
+    };
+    const typed = typeof error?.code === 'string' && error.code.startsWith('ENTROROVE_');
+    const knownBeforeTransmission = preflight || error?.knownBeforeTransmission === true;
+    return { schemaVersion: 'entrorove.mutation-connection/1.0', status: 'blocked', flowId: input?.flowId,
+      code: typed ? error.code : 'ENTROROVE_MUTATION_CONNECTION_LOCAL_PREREQUISITE',
+      message: typed ? error.message : 'Mutation connection stopped at a local prerequisite; preserve its journal and repair before reusing the original input',
+      ...(requestId ? { requestId } : {}), ...(knownBeforeTransmission ? { knownBeforeTransmission: true } : {}),
+      recovery: { operation, reuseOriginalInput: true, preserveJournal: true,
+        ...(knownBeforeTransmission ? { remoteAttemptedThisRun: false } : {}) },
+      ...(error?.output ? { output: error.output } : {}) };
+  }
+}
+export const runMutationConnect = (repositoryRoot, input, dependencies) => runMutationClient('mutation-connect', repositoryRoot, input, dependencies, connectMutation);
+export const runMutationSettle = (repositoryRoot, input, dependencies) => runMutationClient('mutation-settle', repositoryRoot, input, dependencies, settleMutation);