@entrorove/skill 0.1.52 → 0.1.54

package/local-preserved-mutation-protection.mjs

@@ -0,0 +1,51 @@
+import { promises as fs } from 'node:fs';
+import { canonical } from './local-integrity.mjs';
+import { scopeRead, scopeTarget } from './local-scope-files.mjs';
+import { readDisciplineSnapshot } from './local-discipline-snapshot.mjs';
+import { preservedMutationDelegation, preservedMutationFail } from './local-preserved-mutation-wire.mjs';
+import { preservedMutationProtectedFiles } from './local-preserved-mutation-state.mjs';
+import { scopeCandidateImports } from './local-scope-repository.mjs';
+
+function unknownTarget(path, site) {
+  const reason = typeof site?.reason === 'string' && /^[a-z-]+$/.test(site.reason) ? site.reason : 'unknown-import-source';
+  throw Object.assign(new Error(`Preserved mutation cannot modify unknown dependency source ${JSON.stringify(path)}: ${reason}`),
+    { code: 'ENTROROVE_MUTATION_DELEGATION_INVALID', path, reason });
+}
+
+async function observe(input, root, expected) {
+  const before = await scopeTarget(root, expected.path, false, true), resolvedPath = await fs.realpath(before.target);
+  const read = await scopeRead(root, expected.path, input), after = await scopeTarget(root, expected.path, false, true);
+  if (read.sha256 !== expected.sha256 || before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino
+    || before.stat.mode !== after.stat.mode || resolvedPath !== await fs.realpath(after.target)) {
+    preservedMutationFail(`Preserved mutation dependency ${JSON.stringify(expected.path)} changed bytes, permissions or physical identity`);
+  }
+  return { ...expected, mode: after.stat.mode & 0o777, resolvedPath };
+}
+export async function capturePreservedMutationProtection(input, root, authority, snapshot) {
+  const delegation = preservedMutationDelegation(authority), review = await readDisciplineSnapshot(snapshot);
+  for (const expected of delegation.targetFiles) {
+    const file = snapshot.manifest.files.find(item => item.path === expected.path);
+    if (!file?.exists || file.sha256 !== expected.sha256) preservedMutationFail('Preserved mutation target must retain its exact existing gate baseline');
+    const imports = await scopeCandidateImports(root, { path: expected.path,
+      content: (await scopeRead(root, expected.path, input)).content.toString('utf8') }, input);
+    const declared = delegation.targetImports.find(item => item.path === expected.path);
+    if (imports.dynamic) unknownTarget(expected.path, imports.unresolvedImports?.[0]);
+    if (canonical([...new Set(imports.edges.map(edge => edge.specifier))].sort()) !== canonical(declared.specifiers)) {
+      preservedMutationFail('Preserved mutation targets cannot contain unknown or changed imports');
+    }
+  }
+  const unknown = review.analysis.unresolved.find(item => authority.paths.includes(item.path) && /(?:^import-|dynamic-import|dynamic-reference)/.test(item.reason));
+  if (unknown) unknownTarget(unknown.path, unknown);
+  const result = [];
+  for (const expected of delegation.protectedFiles) result.push(await observe(input, root, expected));
+  return result;
+}
+export async function assertPreservedMutationProtection(input, root, authority) {
+  const delegation = preservedMutationDelegation(authority), original = await preservedMutationProtectedFiles(input, authority);
+  if (canonical(original.map(({ path, sha256 }) => ({ path, sha256 }))) !== canonical(delegation.protectedFiles)) {
+    preservedMutationFail('Preserved mutation protected file manifest differs from its signed delegation');
+  }
+  for (const expected of original) {
+    if (canonical(await observe(input, root, expected)) !== canonical(expected)) preservedMutationFail(`Preserved mutation dependency ${JSON.stringify(expected.path)} changed permissions or physical identity`);
+  }
+}

package/local-preserved-mutation-signer.mjs

@@ -0,0 +1,81 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationHome14, mutationRoot14, mutationStateRoot14, mutationId14, privateMutationDirectory14,
+  readMutationJson14, atomicMutationJson14, mutationTarget14 } from './local-mutation-files.mjs';
+import { preservedMutationFail, preservedMutationPublicKey } from './local-preserved-mutation-wire.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { regular } from './local-task-handoff-storage.mjs';
+
+export async function preservedMutationLocation(input) {
+  const root = await mutationRoot14(input.repositoryRoot), home = await mutationHome14(input.home);
+  const relative = path.relative(root, home);
+  if (!relative || relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    preservedMutationFail('Preserved mutation signer home must be outside the repository');
+  }
+  const stateRoot = await mutationStateRoot14({ ...input, home });
+  const repositoryDigest = sha256(root).slice(0, 32), flowId = mutationId14(input.flowId, 'flowId');
+  const directory = path.join(stateRoot, 'mutation-delegates', repositoryDigest, flowId);
+  await privateMutationDirectory14(directory, { privateFrom: stateRoot });
+  return { root, home, stateRoot, repositoryDigest, flowId, directory, bindingPath: path.join(directory, 'binding.json'),
+    signerConfigPath: path.join(directory, 'signer.json'), fencePath: path.join(directory, 'fence.json') };
+}
+export async function readPreservedMutationBinding(input) {
+  const location = await preservedMutationLocation(input), binding = await readMutationJson14(location.bindingPath);
+  const publicKey = preservedMutationPublicKey(binding.publicKey);
+  if (canonical(Object.keys(binding).sort()) !== canonical(['schemaVersion', 'flowId', 'repositoryDigest', 'home', 'keyId', 'publicKey'].sort())
+    || binding.schemaVersion !== 'entrorove.mutation-delegate-binding/1.0' || binding.flowId !== location.flowId
+    || binding.repositoryDigest !== location.repositoryDigest || binding.home !== location.home || binding.keyId !== publicKey.keyId) {
+    preservedMutationFail('Preserved mutation signer lost its original repository, home or flow binding');
+  }
+  return { ...location, binding };
+}
+export async function preparePreservedMutationSigner(input) {
+  const location = await preservedMutationLocation(input);
+  return withStateLock(path.join(location.directory, 'prepare'), () => prepareSigner(input, location));
+}
+async function prepareSigner(input, location) {
+  try { await mutationTarget14(location.directory, 'binding.json'); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    const pair = generateKeyPairSync('ed25519'), publicKey = pair.publicKey.export({ format: 'der', type: 'spki' }).toString('base64');
+    const stage = path.join(location.directory, `.prepare-${randomUUID()}`);
+    await privateMutationDirectory14(stage, { exclusive: true, privateFrom: location.stateRoot });
+    const privateKeyPath = path.join(location.directory, 'private.pem');
+    try {
+      await fs.writeFile(path.join(stage, 'private.pem'), pair.privateKey.export({ format: 'pem', type: 'pkcs8' }), { flag: 'wx', mode: 0o600 });
+      await atomicMutationJson14(path.join(stage, 'signer.json'), { schemaVersion: 'entrorove.mutation-delegate-signer/1.0',
+        privateKeyPath, keyId: sha256(Buffer.from(publicKey, 'base64')), receiptTtlMs: 60_000 }, { privateFrom: location.stateRoot });
+      await atomicMutationJson14(path.join(stage, 'binding.json'), { schemaVersion: 'entrorove.mutation-delegate-binding/1.0',
+        flowId: location.flowId, repositoryDigest: location.repositoryDigest, home: location.home,
+        publicKey, keyId: sha256(Buffer.from(publicKey, 'base64')) }, { privateFrom: location.stateRoot });
+      const fence = { schemaVersion: 'entrorove.preserved-mutation-fence/1.0', epoch: 0, identity: null, grants: [] };
+      await atomicMutationJson14(path.join(stage, 'fence.json'), { ...fence,
+        signature: sign(null, Buffer.from(canonical(fence)), pair.privateKey).toString('base64url') }, { privateFrom: location.stateRoot });
+      for (const file of ['private.pem', 'signer.json', 'binding.json', 'fence.json']) await fs.link(path.join(stage, file), path.join(location.directory, file));
+    } finally { await fs.rm(stage, { recursive: true, force: true }); }
+  }
+  const actual = await readPreservedMutationBinding(input);
+  await mutationTarget14(actual.directory, 'fence.json');
+  await loadPreservedMutationSigner(input, actual.signerConfigPath, actual.binding.keyId);
+  return { schemaVersion: 'entrorove.local-execution/1.0', status: 'reported', purpose: 'preserved-existing-modify',
+    mutationPublicKey: actual.binding.publicKey, mutationKeyId: actual.binding.keyId, keyId: actual.binding.keyId, signerConfigPath: actual.signerConfigPath };
+}
+export async function loadPreservedMutationSigner(input, file, keyId) {
+  const location = await readPreservedMutationBinding(input);
+  if (file !== location.signerConfigPath || location.binding.keyId !== keyId) preservedMutationFail('Preserved mutation signer differs from the delegated physical key');
+  const config = await readMutationJson14(file);
+  if (canonical(Object.keys(config).sort()) !== canonical(['schemaVersion', 'privateKeyPath', 'keyId', 'receiptTtlMs'].sort())
+    || config.schemaVersion !== 'entrorove.mutation-delegate-signer/1.0' || config.keyId !== keyId
+    || config.privateKeyPath !== path.join(location.directory, 'private.pem') || !Number.isSafeInteger(config.receiptTtlMs)
+    || config.receiptTtlMs < 1 || config.receiptTtlMs > 90_000) preservedMutationFail('Preserved mutation signer configuration is invalid');
+  const target = await mutationTarget14(location.directory, 'private.pem'), { bytes, stat } = await regular(target.target, 16 * 1024);
+  try {
+    if (stat.nlink !== 1 || process.platform !== 'win32' && (stat.mode & 0o077)
+      || process.getuid && stat.uid !== process.getuid()) preservedMutationFail('Preserved mutation signer must be an owned private file');
+    const privateKey = createPrivateKey(bytes), der = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+    if (privateKey.asymmetricKeyType !== 'ed25519' || sha256(der) !== keyId) preservedMutationFail('Preserved mutation signer key fingerprint is invalid');
+    return { privateKey, config };
+  } finally { bytes.fill(0); }
+}

package/local-preserved-mutation-state.mjs

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { sign, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { withStateLock } from './local-state-lock.mjs';
+import { readMutationJson14, atomicMutationJson14 } from './local-mutation-files.mjs';
+import { readPreservedMutationBinding, loadPreservedMutationSigner } from './local-preserved-mutation-signer.mjs';
+import { preservedMutationDelegation, preservedMutationFail, preservedMutationPublicKey } from './local-preserved-mutation-wire.mjs';
+
+const identity = authority => Object.fromEntries(['flowId', 'taskId', 'ownerId', 'taskDigest', 'chainDigest',
+  'repositoryDigest', 'runnerKeyId', 'runnerId', 'repositoryId', 'receiverDigest'].map(field => [field, authority[field]]));
+async function rejectGenericHistory(location) {
+  const anchor = process.env.ENTROROVE_TASK_HANDOFF_STATE_DIRECTORY;
+  if (!anchor) return;
+  const file = path.join(anchor, 'flows', location.repositoryDigest, location.flowId, 'fence.json');
+  try {
+    await fs.lstat(file);
+    preservedMutationFail('Preserved mutation cannot replace an existing generic task execution or handoff history');
+  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+}
+export async function preservedMutationOriginalBinding(input, authority) {
+  const location = await readPreservedMutationBinding(input), delegation = preservedMutationDelegation(authority);
+  if (authority.flowId !== input.flowId || authority.stepId !== input.stepId || authority.repositoryDigest !== location.repositoryDigest
+    || input.taskId !== undefined && input.taskId !== authority.taskId || input.generation !== undefined && input.generation !== authority.generation
+    || input.leaseId !== undefined && input.leaseId !== authority.leaseId || input.executionAttemptNonce !== undefined
+    || delegation.mutationKeyId !== location.binding.keyId || delegation.mutationPublicKey !== location.binding.publicKey) {
+    preservedMutationFail('Preserved mutation lost its original physical signer, task, lease or repository binding');
+  }
+  await rejectGenericHistory(location);
+  let state;
+  try { state = await readMutationJson14(location.fencePath); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; preservedMutationFail('Preserved mutation fence history is missing; automatic reinitialization is forbidden'); }
+  if (state) {
+    const { signature, ...core } = state, bytes = typeof signature === 'string' ? Buffer.from(signature, 'base64url') : Buffer.alloc(0);
+    if (bytes.length !== 64 || bytes.toString('base64url') !== signature
+      || !verify(null, Buffer.from(canonical(core)), preservedMutationPublicKey(location.binding.publicKey).key, bytes)) {
+      preservedMutationFail('Preserved mutation fence integrity is invalid');
+    }
+  }
+  if (state.schemaVersion !== 'entrorove.preserved-mutation-fence/1.0' || state.epoch !== 0
+    || state.identity !== null && canonical(state.identity) !== canonical(identity(authority))
+    || !Array.isArray(state.grants) || state.grants.length > 10000 || state.identity === null && state.grants.length) {
+    preservedMutationFail('Preserved mutation fence cannot replace original task identity or epoch history');
+  }
+  return { ...location, context: null, state: { epoch: 0, status: 'active' }, preservedState: state };
+}
+function grantFor(state, authority) {
+  const grant = state.grants.find(item => item.challengeId === authority.challengeId);
+  const nonce = authority.passId ? authority.challengeNonce : authority.nonce;
+  const digest = authority.passId ? authority.challengeDigest : sha256(canonical(authority));
+  if (state.grants.some(item => item.nonce === nonce && item !== grant)
+    || grant && (grant.nonce !== nonce || grant.challengeDigest !== digest || grant.leaseId !== authority.leaseId
+      || grant.generation !== authority.generation || grant.stepId !== authority.stepId)) {
+    preservedMutationFail('Preserved mutation nonce cannot replace its original challenge or lease');
+  }
+  return grant;
+}
+export async function assertPreservedMutationIssued(input, pass) {
+  const binding = await preservedMutationOriginalBinding(input, pass), grant = grantFor(binding.preservedState, pass);
+  if (!grant || grant.passDigest !== sha256(canonical(pass))) preservedMutationFail('Preserved mutation requires its original issued pass and nonce fence');
+  return binding;
+}
+export async function preservedMutationProtectedFiles(input, authority) {
+  const binding = await preservedMutationOriginalBinding(input, authority), grant = grantFor(binding.preservedState, authority);
+  if (!grant?.protectedFiles) preservedMutationFail('Preserved mutation requires its original protected file observations');
+  return grant.protectedFiles;
+}
+async function persist(input, binding, state) {
+  const { signature: previous, ...core } = state;
+  const signer = await loadPreservedMutationSigner(input, binding.signerConfigPath, binding.binding.keyId);
+  const signature = sign(null, Buffer.from(canonical(core)), signer.privateKey).toString('base64url');
+  await atomicMutationJson14(binding.fencePath, { ...core, signature }, { privateFrom: binding.stateRoot, replace: true });
+}
+export async function withPreservedMutationFence(input, authority, action, { attest = false, issue = false, protectedFiles } = {}) {
+  const original = await preservedMutationOriginalBinding(input, authority);
+  return withStateLock(original.fencePath, async () => {
+    const binding = await preservedMutationOriginalBinding(input, authority), state = binding.preservedState;
+    if (state.identity === null) state.identity = identity(authority);
+    let grant = grantFor(state, authority);
+    if (!grant) {
+      if (!attest || authority.passId) preservedMutationFail('Preserved mutation has no original attested challenge');
+      grant = { challengeId: authority.challengeId, nonce: authority.nonce, challengeDigest: sha256(canonical(authority)),
+        leaseId: authority.leaseId, generation: authority.generation, stepId: authority.stepId, passDigest: null, protectedFiles };
+      state.grants.push(grant);
+    }
+    if (attest && canonical(grant.protectedFiles) !== canonical(protectedFiles)) preservedMutationFail('Preserved mutation protected baseline changed during attestation');
+    if (authority.passId) {
+      const passDigest = sha256(canonical(authority));
+      if (grant.passDigest !== passDigest && (!issue || grant.passDigest !== null)) preservedMutationFail('Preserved mutation challenge was already bound to another pass');
+      if (issue) grant.passDigest = passDigest;
+      else if (!grant.passDigest) preservedMutationFail('Preserved mutation pass is not issued');
+    }
+    await persist(input, binding, state);
+    return action(binding.state);
+  });
+}

package/local-preserved-mutation-wire.mjs

@@ -0,0 +1,49 @@
+import { createPublicKey } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationFail14, mutationPath14 } from './local-mutation-files.mjs';
+
+export const preservedMutationFail = message => mutationFail14('ENTROROVE_MUTATION_DELEGATION_INVALID', message);
+function exact(value, names) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || canonical(Object.keys(value).sort()) !== canonical([...names].sort())) preservedMutationFail('Preserved mutation delegation fields are invalid');
+}
+export function preservedMutationPublicKey(encoded) {
+  try {
+    const bytes = Buffer.from(encoded, 'base64'), key = createPublicKey({ key: bytes, format: 'der', type: 'spki' });
+    if (typeof encoded !== 'string' || bytes.toString('base64') !== encoded || key.asymmetricKeyType !== 'ed25519'
+      || key.export({ format: 'der', type: 'spki' }).toString('base64') !== encoded) throw new Error();
+    return { key, keyId: sha256(bytes) };
+  } catch { preservedMutationFail('Preserved mutation requires a canonical Ed25519 public key'); }
+}
+function files(values) {
+  if (!Array.isArray(values) || values.length > 2000) preservedMutationFail('Preserved mutation file manifest is invalid');
+  for (const [index, file] of values.entries()) {
+    exact(file, ['path', 'sha256']); mutationPath14(file.path);
+    if (!/^[0-9a-f]{64}$/.test(file.sha256) || index && values[index - 1].path >= file.path) {
+      preservedMutationFail('Preserved mutation file manifest must be sorted and unique');
+    }
+  }
+  return values;
+}
+export function preservedMutationDelegation(authority) {
+  const value = authority.writeDelegation;
+  exact(value, ['schemaVersion', 'purpose', 'scopeKeyId', 'mutationKeyId', 'mutationPublicKey',
+    'gateEvidenceDigest', 'importGraphDigest', 'protectedFiles', 'targetFiles', 'targetImports']);
+  const publicKey = preservedMutationPublicKey(value.mutationPublicKey);
+  if (value.schemaVersion !== 'entrorove.preserved-write-delegation/1.0' || value.purpose !== 'preserved-existing-modify'
+    || ['scopeKeyId', 'mutationKeyId', 'gateEvidenceDigest', 'importGraphDigest'].some(field => !/^[0-9a-f]{64}$/.test(value[field]))
+    || publicKey.keyId !== value.mutationKeyId || new Set([authority.runnerKeyId, value.scopeKeyId, value.mutationKeyId]).size !== 3
+    || authority.epoch !== 0 || authority.newFilePaths.length !== 0) preservedMutationFail('Preserved mutation role or original epoch is invalid');
+  files(value.protectedFiles); files(value.targetFiles);
+  if (canonical(value.targetFiles.map(file => file.path)) !== canonical(authority.paths)
+    || value.protectedFiles.some(file => authority.paths.includes(file.path))
+    || !Array.isArray(value.targetImports) || canonical(value.targetImports.map(file => file?.path)) !== canonical(authority.paths)) {
+    preservedMutationFail('Preserved mutation must retain its exact existing target and protected path sets');
+  }
+  for (const file of value.targetImports) {
+    exact(file, ['path', 'specifiers']);
+    if (!Array.isArray(file.specifiers) || file.specifiers.some(item => typeof item !== 'string' || !item || /[\u0000-\u001f\u007f]/.test(item))
+      || canonical([...new Set(file.specifiers)].sort()) !== canonical(file.specifiers)) preservedMutationFail('Preserved mutation import manifest is invalid');
+  }
+  return value;
+}

package/local-scope-create-require.mjs

@@ -0,0 +1,142 @@
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import ts from 'typescript';
+import { createScopeImportResolver, scopeSourceChecker } from './local-scope-import-expressions.mjs';
+import { scopeFail, scopePath } from './local-scope-files.mjs';
+
+const purePathMethods = new Set(['join', 'resolve', 'basename', 'dirname', 'extname', 'isAbsolute', 'normalize',
+  'relative', 'parse', 'format', 'toNamespacedPath', 'matchesGlob']);
+function unwrap(node) { while (node && ts.isParenthesizedExpression(node)) node = node.expression; return node; }
+function imported(declaration) {
+  if (ts.isImportSpecifier(declaration)) return { imported: declaration.propertyName?.text ?? declaration.name.text,
+    module: declaration.parent.parent.parent.moduleSpecifier.text };
+  if (ts.isImportClause(declaration)) return { imported: 'default', module: declaration.parent.moduleSpecifier.text };
+  if (ts.isNamespaceImport(declaration)) return { imported: '*', module: declaration.parent.parent.moduleSpecifier.text };
+  return null;
+}
+function importName(node) {
+  for (let parent = node; parent; parent = parent.parent) {
+    if (ts.isImportDeclaration(parent)) return true;
+    if (ts.isStatement(parent)) return false;
+  }
+  return false;
+}
+function immutable(declaration, source) {
+  return declaration && ts.isVariableDeclaration(declaration) && ts.isVariableDeclarationList(declaration.parent)
+    && declaration.parent.flags & ts.NodeFlags.Const && declaration.initializer && declaration.getSourceFile() === source
+    && !(ts.getCombinedModifierFlags(declaration) & ts.ModifierFlags.Ambient) && !source.isDeclarationFile;
+}
+function staticAnchor(call, source, repositoryRoot, filename, declaration, pathMethod) {
+  if (call.arguments.length !== 1) return null;
+  let visited = 0;
+  const value = (raw, seen = new Set(), depth = 0) => {
+    const node = unwrap(raw);
+    if (!node || depth > 32 || ++visited > 256) return null;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+    if (ts.isPropertyAccessExpression(node) && ts.isMetaProperty(node.expression)
+      && node.expression.keywordToken === ts.SyntaxKind.ImportKeyword && node.expression.name.text === 'meta') {
+      const file = path.resolve(repositoryRoot, filename);
+      return node.name.text === 'dirname' ? path.dirname(file) : node.name.text === 'filename' ? file
+        : node.name.text === 'url' ? pathToFileURL(file).href : null;
+    }
+    if (ts.isCallExpression(node)) {
+      const method = pathMethod(node.expression);
+      if (!['join', 'resolve'].includes(method) || node.arguments.length < 1 || node.arguments.length > 32) return null;
+      const args = node.arguments.map(item => value(item, seen, depth + 1));
+      if (args.some(item => typeof item !== 'string') || method === 'resolve' && !args.some(item => path.isAbsolute(item))) return null;
+      return path[method](...args);
+    }
+    if (!ts.isIdentifier(node)) return null;
+    const bound = declaration(node);
+    return immutable(bound, source) && !seen.has(bound) ? value(bound.initializer, new Set([...seen, bound]), depth + 1) : null;
+  };
+  let absolute = value(call.arguments[0]);
+  if (typeof absolute !== 'string' || !absolute || /[\u0000-\u001f\u007f]/.test(absolute)) return null;
+  if (absolute.startsWith('file:')) { try { absolute = fileURLToPath(absolute); } catch { return null; } }
+  if (!path.isAbsolute(absolute)) return null;
+  const relative = path.relative(repositoryRoot, absolute).split(path.sep).join('/');
+  if (!relative || relative === '..' || relative.startsWith('../') || path.isAbsolute(relative)
+    || relative.split('/').some(part => ['.git', '.entrorove', '.aimlock', '.archguard'].includes(part))) {
+    scopeFail('ENTROROVE_PATH_UNSAFE', `createRequire in "${filename}" resolves its anchor outside the authorized repository or into a reserved control directory`);
+  }
+  return scopePath(relative);
+}
+/** Infer only lexical builtin factories and immutable path expressions; never run scanned code. */
+export function createScopeRequireContexts(source, repositoryRoot, filename) {
+  let checker, safety;
+  const declaration = node => {
+    checker ??= scopeSourceChecker(source);
+    const declarations = checker.getSymbolAtLocation(node)?.declarations;
+    return declarations?.length === 1 && declarations[0].getSourceFile() === source ? declarations[0] : null;
+  };
+  const origin = node => ts.isIdentifier(node) ? imported(declaration(node) ?? source) : null;
+  const factory = node => { const value = node && origin(unwrap(node));
+    return value?.imported === 'createRequire' && ['node:module', 'module'].includes(value.module); };
+  const pathObject = node => { const value = node && origin(unwrap(node));
+    return ['default', '*'].includes(value?.imported) && ['node:path', 'path'].includes(value?.module); };
+  const pathMethod = node => {
+    node = unwrap(node);
+    if (node && ts.isPropertyAccessExpression(node) && pathObject(node.expression)) return node.name.text;
+    const value = node && origin(node);
+    return value && ['node:path', 'path'].includes(value.module) ? value.imported : null;
+  };
+  const factoryCall = node => { node = unwrap(node);
+    return node && ts.isCallExpression(node) && factory(node.expression) ? node : null; };
+  const moduleArguments = createScopeImportResolver(source);
+  const mutableBuiltinLoad = node => {
+    if (!ts.isCallExpression(node) || !node.arguments.length) return false;
+    const callee = unwrap(node.expression), bound = ts.isIdentifier(callee) && declaration(callee);
+    const loading = callee.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(callee) && callee.text === 'require'
+      || factoryCall(callee) || bound && ts.isVariableDeclaration(bound) && factoryCall(bound.initializer);
+    return loading && moduleArguments(node.arguments[0])?.some(name => ['path', 'node:path', 'module', 'node:module'].includes(name));
+  };
+  function safeBuiltins() {
+    if (safety !== undefined) return safety;
+    safety = true;
+    const visit = node => {
+      if (mutableBuiltinLoad(node)) safety = false;
+      if (ts.isIdentifier(node) && !importName(node)) {
+        if (node.text === 'syncBuiltinESMExports') safety = false;
+        if (pathObject(node)) {
+          const member = node.parent, call = member?.parent;
+          if (!ts.isPropertyAccessExpression(member) || member.expression !== node
+            || !(purePathMethods.has(member.name.text) && ts.isCallExpression(call) && call.expression === member)
+              && !['sep', 'delimiter'].includes(member.name.text)) safety = false;
+        }
+        const method = origin(node);
+        if (method && ['node:module', 'module'].includes(method.module)
+          && ['default', '*', 'register', 'registerHooks', 'syncBuiltinESMExports'].includes(method.imported)) safety = false;
+        if (method && ['node:path', 'path'].includes(method.module) && purePathMethods.has(method.imported)
+          && !(ts.isCallExpression(node.parent) && node.parent.expression === node)) safety = false;
+        if (factory(node) && !(ts.isCallExpression(node.parent) && node.parent.expression === node)) safety = false;
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source); return safety;
+  }
+  const anchor = call => repositoryRoot && safeBuiltins() ? staticAnchor(call, source, repositoryRoot, filename, declaration, pathMethod) : null;
+  function loader(node) {
+    node = unwrap(node);
+    const direct = factoryCall(node);
+    if (direct) return { anchor: anchor(direct), call: direct };
+    if (!node || !ts.isIdentifier(node)) return null;
+    const bound = declaration(node), creation = bound && ts.isVariableDeclaration(bound) && factoryCall(bound.initializer);
+    if (creation) return { anchor: immutable(bound, source) ? anchor(creation) : null, call: creation, declaration: bound };
+    if (node.text === 'require' && bound) return { anchor: null };
+    return null;
+  }
+  return { loader,
+    knownFactoryReference(node) {
+      const named = ts.isImportSpecifier(node.parent) && imported(node.parent);
+      return importName(node) && (factory(node) || named?.imported === 'createRequire' && ['node:module', 'module'].includes(named.module))
+        || factory(node) && ts.isCallExpression(node.parent)
+        && node.parent.expression === node && anchor(node.parent) !== null;
+    },
+    loaderReference(node) {
+      if (!ts.isIdentifier(node) || importName(node)) return null;
+      const found = loader(node);
+      if (!found) return null;
+      const declared = found.declaration?.name === node;
+      return { safe: Boolean(found.anchor) && (declared || ts.isCallExpression(node.parent) && node.parent.expression === node) };
+    } };
+}

package/local-scope-import-expressions.mjs

@@ -7,7 +7,7 @@ function unwrap(node) {
     || ts.isTypeAssertionExpression(node) || ts.isNonNullExpression(node))) node = node.expression;
   return node;
 }
-function sourceChecker(source) {
+export function scopeSourceChecker(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,
@@ -47,7 +47,7 @@ export function createScopeImportResolver(source, suppliedChecker) {
         return result;
       }
       if (!ts.isIdentifier(node)) return null;
-      checker ??= sourceChecker(source);
+      checker ??= scopeSourceChecker(source);
       const declarations = checker.getSymbolAtLocation(node)?.declarations;
       if (declarations?.length !== 1) return null;
       const declaration = declarations[0];

package/local-scope-repository.mjs

@@ -15,6 +15,8 @@ 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';
+import { createScopeRequireContexts } from './local-scope-create-require.mjs';
+import { resolveCreatedRequire } from './local-scope-require-resolution.mjs';
 
 const execute = promisify(execFile);
 async function git(root, args, allowed = [], input = { repositoryRoot: root }) {
@@ -107,11 +109,17 @@ 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(), unresolvedImports = [], resolve = createScopeImportResolver(parsed); let dynamic = false;
-  const add = expression => {
+  const found = new Set(), requires = new Map(), unresolvedImports = [], resolve = createScopeImportResolver(parsed); let dynamic = false;
+  const contexts = createScopeRequireContexts(parsed, context.repositoryRoot, context.sourceFilename ?? filename);
+  const unresolved = (expression, reason, message) => { dynamic = true;
+    unresolvedImports.push({ ...unresolvedImportSite(parsed, expression), reason, message }); };
+  const add = (expression, anchor) => {
     const values = resolve(expression);
     if (values === null) { dynamic = true; unresolvedImports.push(unresolvedImportSite(parsed, expression)); }
-    else for (const value of values) found.add(value);
+    else for (const value of values) {
+      if (anchor) requires.set(`${anchor}\0${value}`, { anchor, specifier: value });
+      else found.add(value);
+    }
   };
   const visit = node => {
     if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) { if (node.moduleSpecifier) add(node.moduleSpecifier); }
@@ -120,21 +128,28 @@ function scriptImports(source, filename, context = {}) {
     else if (ts.isCallExpression(node)) {
       const importer = node.expression.kind === ts.SyntaxKind.ImportKeyword;
       const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
-      if (importer || requireCall) {
+      const created = importer ? null : contexts.loader(node.expression);
+      if (importer || requireCall || created) {
         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]);
+        else if (created && !created.anchor) unresolved(node, 'create-require-context-not-statically-proven',
+          'Require uses a shadowed, mutable or unproven factory/path context; no dependency lookup is authorized');
+        else add(node.arguments[0], created?.anchor);
       }
     }
     const runtimeReference = !isTypeOnlyReference(node);
     if (runtimeReference && ts.isIdentifier(node)) {
-      if (dynamicNames.has(node.text) && (node.text !== 'Function' || isDynamicFunctionReference(node, context))) dynamic = true;
+      if (dynamicNames.has(node.text) && (node.text !== 'Function' || isDynamicFunctionReference(node, context))
+        && !(node.text === 'createRequire' && contexts.knownFactoryReference(node))) dynamic = true;
+      const loader = contexts.loaderReference(node);
+      if (loader && !loader.safe) unresolved(node, 'require-loader-escapes-static-context',
+        'Require loader aliases, mutable bindings and uses outside direct calls remain unresolved');
       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;
+        && !(ts.isMethodDeclaration(node.parent) && node.parent.name === node) && !loader?.safe) dynamic = true;
     }
     if (runtimeReference && ts.isElementAccessExpression(node)) {
       const member = staticString(node.argumentExpression);
@@ -143,7 +158,7 @@ function scriptImports(source, filename, context = {}) {
     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, unresolvedImports };
+  visit(parsed); return { specifiers: [...found].sort(), requires: [...requires.values()], dynamic, unresolvedImports };
 }
 function vueScripts(source, filename) {
   const { descriptor, errors } = parseVue(source, { filename, sourceMap: false,
@@ -176,14 +191,15 @@ function vueScripts(source, filename) {
   };
   walk(descriptor.template?.ast); return scripts;
 }
-function importSpecifiers(content, filename) {
+function importSpecifiers(content, filename, repositoryRoot) {
   try {
     const source = content.toString('utf8'), parts = path.extname(filename).toLowerCase() === '.vue' ? vueScripts(source, filename) : [{ source, filename }];
-    const specifiers = new Set(), unresolvedImports = []; let dynamic = false;
-    for (const part of parts) { const parsed = scriptImports(part.source, part.filename, part); dynamic ||= parsed.dynamic;
+    const specifiers = new Set(), requires = new Map(), unresolvedImports = []; let dynamic = false;
+    for (const part of parts) { const parsed = scriptImports(part.source, part.filename, { ...part, repositoryRoot, sourceFilename: filename }); dynamic ||= parsed.dynamic;
       unresolvedImports.push(...parsed.unresolvedImports.map(site => ({ ...site, line: site.line + (part.lineOffset ?? 0) })));
+      for (const require of parsed.requires) requires.set(`${require.anchor}\0${require.specifier}`, require);
       for (const specifier of parsed.specifiers) specifiers.add(specifier); }
-    return { specifiers: [...specifiers].sort(), dynamic, unresolvedImports };
+    return { specifiers: [...specifiers].sort(), requires: [...requires.values()], 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');
@@ -280,7 +296,7 @@ export async function importGraph(root, originals, input = { repositoryRoot: roo
     const aliases = await scopeTsconfigImports(target => configMetadata(root, target, input), relative, configPath);
     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;
+    const imports = importSpecifiers(read.content, relative, root); 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()) {
@@ -289,6 +305,12 @@ export async function importGraph(root, originals, input = { repositoryRoot: roo
         ...(declarations.has(specifier) ? { declarationOnly: true, declarationPath: relative } : {}) });
       if (target !== null && !visited.has(target)) pending.push(target);
     }
+    for (const request of imports.requires) {
+      const resolved = await resolveCreatedRequire(relative, request.anchor, request.specifier, target => configMetadata(root, target, input));
+      for (const file of resolved.metadata) metadata.set(file.path, file);
+      edges.push({ from: relative, to: resolved.external ? null : resolved.target, external: resolved.external, specifier: request.specifier });
+      if (!resolved.external && resolved.target !== null && !visited.has(resolved.target)) pending.push(resolved.target);
+    }
   }
   const nodes = [...visited.values()].sort((a, b) => a.path.localeCompare(b.path));
   await stableScope(root, nodes, input);
@@ -299,7 +321,7 @@ export async function importGraph(root, originals, input = { repositoryRoot: roo
     ...(unresolvedImports.length ? { unresolvedImports } : {}) };
 }
 export async function scopeCandidateImports(root, file, input = { repositoryRoot: root }) {
-  const parsed = importSpecifiers(Buffer.from(file.content), file.path);
+  const parsed = importSpecifiers(Buffer.from(file.content), file.path, root);
   const workspace = await workspaceIndex(root, input);
   const context = (input.importContexts ?? []).filter(item => file.path === item.sourcePrefix || file.path.startsWith(`${item.sourcePrefix}/`))
     .sort((a, b) => b.sourcePrefix.length - a.sourcePrefix.length)[0];
@@ -309,7 +331,12 @@ 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,
+  for (const request of parsed.requires) {
+    const resolved = await resolveCreatedRequire(file.path, request.anchor, request.specifier, target => configMetadata(root, target, input));
+    await stableScope(root, resolved.metadata, input);
+    edges.push({ from: file.path, to: resolved.external ? null : resolved.target, external: resolved.external, specifier: request.specifier });
+  }
+  return { edges: edges.sort((a, b) => `${a.from}:${a.specifier}`.localeCompare(`${b.from}:${b.specifier}`)), 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 }) {