create-agdf 0.14.4 → 0.20.0

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/presentation.js

@@ -0,0 +1,122 @@
+import { interactionLocales } from "../resources/context.js";
+import { localePack } from "../interaction-presentation.js";
+import { controlCounts } from "./contract.js";
+
+export function renderMaintenanceOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
+  const copy = localePack(registry, language).repositoryMaintenance;
+  return [renderControlMigration(control, { registry, language, details }),
+    `[1] ${copy.start}`, `[2] ${copy.later}`, `[3] ${copy.details}`].join("\n");
+}
+
+export function renderMaintenanceResult(report, { registry = interactionLocales, language = "en", details = false } = {}) {
+  const copy = localePack(registry, language).repositoryMaintenance;
+  if (report.inspection_state !== "complete") return `${copy.unavailable}: ${report.target}\n${report.diagnostics.map((item) => item.code).join("\n")}`;
+  return [renderControlMigration(report.compatibility, { registry, language, details }),
+    ...report.diagnostics.map((item) => `${item.run_id ? `${item.run_id}: ` : ""}${item.code}${item.path ? `: ${item.path}` : ""}`),
+    `${copy.title}: ${copy.outcomes[report.maintenance_outcome]}`].join("\n");
+}
+
+export function renderStartupControlNotice(facts, { registry = interactionLocales, language = "en", platform = process.platform } = {}) {
+  if (!facts.invocation) return "";
+  const pack = localePack(registry, language);
+  const copy = pack.repositoryMaintenance;
+  const migration = pack.installSetup.controlMigration;
+  const quote = platform === "win32" ? (value) => `'${String(value).replaceAll("'", "''")}'`
+    : (value) => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  const command = [facts.invocation.executable, ...facts.invocation.argv].map(quote).join(" ");
+  return [copy.title, `${migration.target}: ${facts.target}`,
+    facts.status === "unavailable" ? copy.unavailable : `${migration.state}: ${migration.states[facts.status]}`,
+    ...(facts.counts ? [replacement(migration.eligibleDescription, { count: facts.counts.migration }),
+      replacement(migration.blockedDescription, { count: facts.counts.repair })] : []),
+    copy.next, `${platform === "win32" ? "& " : ""}${command}`].join("\n");
+}
+
+function replacement(template, values = {}) {
+  return Object.entries(values).reduce((current, [key, value]) => current.replaceAll(`{${key}}`, String(value)), template);
+}
+
+export function renderControlMigration(control, { registry = interactionLocales, language = "en", details = false } = {}) {
+  if (!control || control.status === "not_checked") return "";
+  const copy = localePack(registry, language).installSetup.controlMigration;
+  const lines = ["", copy.title, `${copy.target}: ${control.target}`,
+    `${copy.state}: ${copy.states[control.status]}`];
+  const { migration: eligible, repair } = controlCounts(control);
+  if (eligible) lines.push(replacement(copy.eligibleDescription, { count: eligible }));
+  if (repair) lines.push(replacement(copy.blockedDescription, { count: repair }));
+  if (control.changes.length) lines.push(replacement(copy.changed, { count: control.changes.length }));
+  if (control.repair) {
+    const repairCopy = localePack(registry, language).installSetup.controlRepair;
+    lines.push(replacement(repairCopy.repairedDescription, { count: control.repair.items.filter((item) => item.outcome === "repaired").length }));
+    for (const item of control.repair.items.filter((item) => !item.available)) {
+      for (const finding of item.required) lines.push(`${item.run_id}: ${repairCopy.reasons[finding.code] ?? repairCopy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
+    }
+  }
+  if (!details) {
+    if (control.diagnostics.length && !repair) lines.push(copy.repairDescription);
+    if (eligible || repair || control.diagnostics.length) lines.push(copy.detailsDescription);
+    return lines.join("\n");
+  }
+  lines.push(`${copy.format}: ${control.supported_control_state_version}`,
+    replacement(copy.historicalCount, { count: control.runs.filter((run) => run.status === "historical").length }));
+  for (const run of control.runs.filter((entry) => entry.status !== "current" && entry.status !== "historical")) {
+    lines.push(`${run.run_id}: ${copy.states[run.status]}`);
+    for (const finding of run.diagnostics) lines.push(`  ${finding.code}${finding.path ? `: ${finding.path}` : ""}`);
+  }
+  for (const diagnostic of control.diagnostics) lines.push(`${diagnostic.code}${diagnostic.path ? `: ${diagnostic.path}` : ""}`);
+  for (const change of control.changes) lines.push(`${change.run_id}: ${copy.backup}: ${change.backup}`);
+  if (control.status === "migration_required") lines.push(copy.migrationDescription, copy.manualDescription, copy.legacyDescription);
+  if (control.status === "repair_required") lines.push(copy.repairDescription);
+  return lines.join("\n");
+}
+
+export function renderControlMigrationDecision(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
+  const copy = localePack(registry, language).installSetup.controlMigration;
+  const lines = [renderControlMigration(plan.control, { registry, language, details }),
+    replacement(copy.batchDescription, { count: plan.runs.length }), copy.backupDescription];
+  if (plan.approval_reset_count) lines.push(replacement(copy.resetDescription, { count: plan.approval_reset_count }));
+  if (details) {
+    for (const run of plan.runs) {
+      lines.push(`${copy.run}: ${run.run_id}`, `${copy.sourceRevision}: ${run.source_revision_id}`,
+        `${copy.nextGate}: ${run.next_gate}`,
+        ...run.prior_approvals.filter((row) => row.status !== "missing" || row.evidence)
+          .map((row) => `  ${row.gate}: ${row.status} (${row.evidence})`));
+    }
+    for (const diagnostic of plan.diagnostics) lines.push(`${diagnostic.run_id}: ${diagnostic.code}`);
+  }
+  lines.push(`[1] ${copy.migrateChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
+  return lines.join("\n");
+}
+
+export function renderControlRepairOffer(control, { registry = interactionLocales, language = "en", details = false } = {}) {
+  const copy = localePack(registry, language).installSetup.controlRepair;
+  return [renderControlMigration(control, { registry, language, details }), copy.searchDescription,
+    `[1] ${copy.startChoice}`, `[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`].join("\n");
+}
+
+export function renderControlRepairPlan(plan, { registry = interactionLocales, language = "en", details = false } = {}) {
+  const pack = localePack(registry, language).installSetup;
+  const copy = pack.controlRepair;
+  const candidates = plan.items.filter((item) => item.available);
+  const lines = [copy.title, `${pack.controlMigration.target}: ${plan.target}`,
+    replacement(copy.availableDescription, { count: candidates.length }), copy.backupDescription];
+  if (candidates.some((item) => item.approval_reset)) lines.push(copy.resetDescription);
+  for (const item of plan.items) {
+    lines.push(`${item.run_id}: ${copy.kinds[item.kind]}`);
+    for (const finding of item.required) lines.push(`  ${copy.reasons[finding.code] ?? copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}`);
+    if (details) for (const source of item.sources) lines.push(`  ${source.path}: ${source.source} ${source.commit ?? source.journal ?? ""}`);
+    if (details && item.available && item.source_content !== item.candidate_content) {
+      const before = item.source_content.split("\n");
+      const after = item.candidate_content.split("\n");
+      let start = 0;
+      while (start < before.length && start < after.length && before[start] === after[start]) start++;
+      let end = 0;
+      while (end < before.length - start && end < after.length - start && before.at(-1 - end) === after.at(-1 - end)) end++;
+      lines.push(...before.slice(start, before.length - end).map((line) => `- ${line}`),
+        ...after.slice(start, after.length - end).map((line) => `+ ${line}`));
+    }
+  }
+  for (const finding of plan.diagnostics) lines.push(`${copy.manualDescription}${finding.path ? `: ${finding.path}` : ""}${details ? ` (${finding.code})` : ""}`);
+  if (candidates.length) lines.push(`[1] ${copy.applyChoice}`);
+  lines.push(`[2] ${copy.skipChoice}`, `[3] ${copy.detailsChoice}`);
+  return lines.join("\n");
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/repair.js

@@ -0,0 +1,226 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isSafeControlRelativePath } from "../control-state/contained-file.js";
+import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
+import { parseRunState } from "../control-state/run-state-parser.js";
+import { approvalSeal, artefactFileDigest, canonicalRunText, listedArtefactPaths, runSealState } from "../control-state/run-seal.js";
+import { inspectSelfReferenceRecovery } from "../control-state/run-recovery.js";
+import { atomicWrite, unapproveRecoveryApprovals, withRunLock, writeRunLocked, writeRunRecoveryLocked } from "../control-state/run-state-writer.js";
+import { inspectControlMigration } from "./compatibility.js";
+
+const digest = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
+const textDigest = (content) => digest(canonicalRunText(content));
+const pathError = (path) => Object.assign(new Error("AGDF_REPAIR_PATH_INVALID"), { code: "AGDF_REPAIR_PATH_INVALID", path });
+
+function checkedPath(root, relative, { createParents = false } = {}) {
+  if (!isSafeControlRelativePath(relative)) throw pathError(relative);
+  try { directoryIdentity(root); } catch { throw pathError(relative); }
+  let cursor = root;
+  const segments = relative.split("/");
+  for (const segment of segments.slice(0, -1)) {
+    cursor = join(cursor, segment);
+    try { directoryIdentity(cursor); } catch (error) {
+      if (error.code !== "ENOENT") throw pathError(relative);
+      if (!createParents) return null;
+      mkdirSync(cursor, { mode: 0o700 });
+      directoryIdentity(cursor);
+    }
+  }
+  const path = join(root, relative);
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isFile()) throw pathError(relative);
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+  return path;
+}
+
+function gitOriginals(root, path, readGitOriginals) {
+  if (!isSafeControlRelativePath(path) || typeof readGitOriginals !== "function") return [];
+  try {
+    const entries = readGitOriginals(root, path);
+    if (!Array.isArray(entries) || entries.length > 9) return [];
+    return entries.filter(entry => entry?.path === path && isSafeControlRelativePath(entry.git_path)
+      && entry.source === "git" && /^[0-9a-f]{40,64}$/u.test(entry.commit)
+      && typeof entry.bytes === "string" && entry.bytes.length <= 3 * 1024 * 1024
+      && entry.digest === textDigest(Buffer.from(entry.bytes, "base64").toString("utf8")));
+  } catch { return []; }
+}
+
+function proposal(root, item, fields) {
+  const proposed = { ...item, ...fields };
+  proposed.artefacts = [...new Set([...item.artefacts.map((artifact) => artifact.path), ...listedArtefactPaths(proposed.candidate_content)])]
+    .map((path) => { checkedPath(root, path); return { path, digest: artefactFileDigest(root, path) }; });
+  return proposed;
+}
+
+function inspectRunRepair(root, run, readGitOriginals) {
+  const relative = `.agdf/control/runs/${run.run_id}/RUN_STATE.md`;
+  const path = checkedPath(root, relative);
+  const content = regularFileSnapshot(path).content.toString("utf8");
+  const parsed = parseRunState(content, run.run_id);
+  const item = { run_id: run.run_id, kind: "manual", available: false, required: [], sources: [],
+    source_content: content, source_digest: digest(content), source_revision_id: parsed.meta.revision_id,
+    candidate_content: null, files: [], artefacts: listedArtefactPaths(content).map((path) => {
+      checkedPath(root, path);
+      return { path, digest: artefactFileDigest(root, path) };
+    }) };
+  if (!parsed.valid || parsed.meta.lifecycle !== "active" || run.pending_recoveries?.length) {
+    item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
+    return item;
+  }
+  const seal = runSealState(root, content);
+  const checkpoint = inspectSelfReferenceRecovery(root, run.run_id);
+  if (checkpoint) {
+    return proposal(root, item, { kind: "self_reference", available: true, candidate_content: checkpoint.content,
+      sources: [{ path: relative, source: "recovery_journal", journal: checkpoint.source }] });
+  }
+  if (seal.status === "content_changed") {
+    const original = gitOriginals(root, relative, readGitOriginals).find((candidate) => {
+      const text = Buffer.from(candidate.bytes, "base64").toString("utf8");
+      const state = parseRunState(text, run.run_id);
+      return state.valid && state.meta.lifecycle === "active" && state.meta.revision_id === parsed.meta.revision_id
+        && runSealState(root, text).status === "valid" && runSealState(root, text).recorded.content_seal === seal.recorded.content_seal && approvalSeal(text) === seal.recorded.approval_seal
+        && listedArtefactPaths(text).every((path) => artefactFileDigest(root, path).startsWith("sha256:"));
+    });
+    if (original) return proposal(root, item, { kind: "run_snapshot", available: true,
+      candidate_content: Buffer.from(original.bytes, "base64").toString("utf8"), sources: [original] });
+  }
+  if (seal.status === "unsealed") {
+    for (const artifact of listedArtefactPaths(content)) {
+      const target = checkedPath(root, artifact);
+      const status = artefactFileDigest(root, artifact);
+      if (!["missing", "unresolved"].includes(status)) continue;
+      // A descriptive placeholder is not a filename; repair never invents paths or evidence.
+      if (!artifact.startsWith(`.agdf/control/artefacts/${run.run_id}/`) || !isSafeControlRelativePath(artifact)) {
+        item.required.push({ code: "AGDF_REPAIR_REFERENCE_REQUIRED", path: artifact });
+        continue;
+      }
+      if (target) {
+        try { lstatSync(target); item.required.push({ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: artifact }); continue; }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+      }
+      const original = gitOriginals(root, artifact, readGitOriginals)[0];
+      if (original) { item.files.push(original); item.sources.push(original); }
+      else item.required.push({ code: "AGDF_REPAIR_ORIGINAL_REQUIRED", path: artifact });
+    }
+    if (item.files.length && !item.required.length) {
+      item.kind = "missing_artefacts";
+      item.available = true;
+      item.candidate_content = unapproveRecoveryApprovals(content);
+      item.approval_reset = true;
+      return proposal(root, item, {});
+    }
+  }
+  if (!item.required.length) item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
+  return item;
+}
+
+export function inspectControlRepair(root, { readGitOriginals } = {}) {
+  const control = inspectControlMigration(root);
+  const items = [];
+  const diagnostics = [...control.diagnostics];
+  // An incomplete inventory or unsafe scaffold cannot authorize repair writes.
+  if (!diagnostics.length) for (const run of control.runs.filter((entry) => entry.status === "repair_required")) {
+    try { items.push(inspectRunRepair(root, run, readGitOriginals)); } catch (error) {
+      items.push({ run_id: run.run_id, kind: "manual", available: false, files: [], sources: [],
+        required: [{ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) }] });
+    }
+  }
+  return { target: root, control, items, diagnostics, authorizes: false };
+}
+
+function publicRepair(plan, status) {
+  return { status, target: plan.target, authorizes: false, diagnostics: plan.diagnostics,
+    items: plan.items.map(({ run_id, kind, available, required, sources, outcome, backup }) => ({
+      run_id, kind, available, required,
+      sources: sources.map(({ bytes, ...source }) => source), ...(outcome ? { outcome, backup } : {}),
+    })) };
+}
+
+function applyRunRepair(root, item, hooks = {}, readGitOriginals) {
+  const relative = `.agdf/control/runs/${item.run_id}/RUN_STATE.md`;
+  const path = checkedPath(root, relative);
+  return withRunLock(path, () => {
+    if (regularFileSnapshot(path).content.toString("utf8") !== item.source_content) throw new Error("AGDF_STALE_RUN_REVISION");
+    // Re-read the selected source under the lock; callback mutation and source changes cannot
+    // replace the displayed restoration with another snapshot or a newly found original.
+    const run = inspectControlMigration(root).runs.find((entry) => entry.run_id === item.run_id);
+    if (!run || run.status !== "repair_required") throw new Error("AGDF_STALE_RUN_REVISION");
+    const current = inspectRunRepair(root, run, readGitOriginals);
+    if (JSON.stringify(current) !== JSON.stringify(item)) throw new Error("AGDF_STALE_RUN_REVISION");
+    const directory = join(dirname(path), "repair-previews");
+    try { mkdirSync(directory, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; }
+    directoryIdentity(directory);
+    if (process.platform !== "win32" && (lstatSync(directory).mode & 0o077)) throw new Error("AGDF_RECOVERY_JOURNAL_PERMISSIONS_INVALID");
+    const id = randomUUID();
+    const journalPath = join(directory, `${id}.json`);
+    const updatedAt = new Date().toISOString();
+    const nextRevisionId = randomUUID();
+    const journal = { schema_version: 1, phase: "prepared", created_at: updatedAt, run_id: item.run_id,
+      source_content: item.source_content, source_digest: item.source_digest, sources: item.sources,
+      files: item.files, candidate_content: item.candidate_content, next_revision_id: nextRevisionId };
+    atomicWrite(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
+    const restored = [];
+    try {
+      for (const file of item.files) {
+        const target = checkedPath(root, file.path, { createParents: true });
+        try { lstatSync(target); throw new Error("AGDF_STALE_RUN_REVISION"); }
+        catch (error) { if (error.code !== "ENOENT") throw error; }
+        atomicWrite(target, Buffer.from(file.bytes, "base64"));
+        restored.push({ ...file, snapshot: regularFileSnapshot(target) });
+      }
+      hooks.beforeRunWrite?.();
+      const options = { expectedContent: item.source_content, expectedRevisionId: item.source_revision_id,
+        nextRevisionId, updatedAt, validateBeforeWrite: () => {
+          checkedPath(root, relative);
+          for (const artifact of item.artefacts) {
+            checkedPath(root, artifact.path);
+            const expected = item.files.find((file) => file.path === artifact.path)?.digest ?? artifact.digest;
+            if (artefactFileDigest(root, artifact.path) !== expected) throw new Error("AGDF_STALE_RUN_REVISION");
+          }
+        } };
+      if (item.kind === "missing_artefacts") writeRunRecoveryLocked(path, item.candidate_content, options);
+      else writeRunLocked(path, item.candidate_content, item.source_revision_id, { ...options, allowContentChange: true });
+      hooks.afterRunWrite?.();
+      const result = regularFileSnapshot(path).content.toString("utf8");
+      if (runSealState(root, result).status !== "valid") throw new Error("AGDF_CONTROL_REPAIR_VERIFICATION_FAILED");
+      atomicWrite(journalPath, `${JSON.stringify({ ...journal, phase: "committed", result_digest: digest(result) }, null, 2)}\n`);
+      return { outcome: "repaired", backup: journalPath.slice(root.length + 1) };
+    } catch (error) {
+      // Roll back only files we created and still own, only while the run was not replaced.
+      // A post-rename interruption retains the complete original snapshot and avoids a second write.
+      if (regularFileSnapshot(path).content.toString("utf8") === item.source_content) for (const file of restored) {
+        const target = checkedPath(root, file.path);
+        if (target) {
+          const current = regularFileSnapshot(target);
+          if (current.dev === file.snapshot.dev && current.ino === file.snapshot.ino
+              && current.content.equals(file.snapshot.content)) unlinkSync(target);
+        }
+      }
+      throw error;
+    }
+  });
+}
+
+export async function repairInstallationControl(control, { chooseRepair, confirmRepair, hooks, readGitOriginals } = {}) {
+  if (control.status !== "repair_required" || typeof chooseRepair !== "function") return control;
+  if (await chooseRepair(structuredClone(control)) !== "start") return control;
+  const plan = inspectControlRepair(control.target, { readGitOriginals });
+  const candidates = plan.items.filter((item) => item.available);
+  let decision = "skip";
+  if (typeof confirmRepair === "function") decision = await confirmRepair(structuredClone(plan));
+  if (decision === "repair") for (const item of candidates) {
+    try { Object.assign(item, applyRunRepair(control.target, item, hooks, readGitOriginals)); }
+    catch (error) { plan.diagnostics.push({ run_id: item.run_id, code: String(error.code ?? error.message) }); }
+  }
+  const after = inspectControlMigration(control.target);
+  after.changes = control.changes;
+  after.repair = publicRepair(plan, !candidates.length ? "needs_input" : decision !== "repair" ? "deferred"
+    : plan.diagnostics.length || after.status !== "current" ? "partial" : "applied");
+  if (plan.diagnostics.length) {
+    after.diagnostics.push(...plan.diagnostics);
+    after.status = "repair_required";
+  }
+  return after;
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-maintenance/service.js

@@ -0,0 +1,38 @@
+import { isAbsolute } from "node:path";
+import { directoryIdentity } from "../control-state/run-store-inspection.js";
+import { inspectControlMigration } from "./compatibility.js";
+import { migrateInstallationControl } from "./migration.js";
+import { repairInstallationControl } from "./repair.js";
+import { maintenanceResult } from "./contract.js";
+
+export async function runControlMaintenance(target, { guided = false, chooseMaintenance, confirmMigration, confirmRepair, readGitOriginals } = {}) {
+  if (typeof target !== "string" || !isAbsolute(target)) throw new Error("AGDF_MAINTENANCE_TARGET_REQUIRED");
+  const identity = directoryIdentity(target);
+  const verifyTarget = () => {
+    const current = directoryIdentity(target);
+    if (current.realpath !== identity.realpath || current.dev !== identity.dev || current.ino !== identity.ino) {
+      throw new Error("AGDF_MAINTENANCE_TARGET_CHANGED: inspect the target again before applying a new plan");
+    }
+  };
+  const reviewed = (callback) => async (plan) => {
+    verifyTarget();
+    const decision = await callback(plan);
+    verifyTarget();
+    return decision;
+  };
+  const before = inspectControlMigration(target);
+  if (!guided || ["absent", "current"].includes(before.status)) return maintenanceResult(target, before, { operation: guided ? "guided" : "inspect" });
+  if (![chooseMaintenance, confirmMigration, confirmRepair].every((callback) => typeof callback === "function")) {
+    throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
+  }
+  if (await reviewed(chooseMaintenance)(structuredClone(before)) !== "start") {
+    return maintenanceResult(target, inspectControlMigration(target), { operation: "guided", outcome: "deferred" });
+  }
+  let after = await migrateInstallationControl(target, { mode: "safe", confirmMigration: reviewed(confirmMigration) });
+  const diagnostics = [...after.diagnostics];
+  after = await repairInstallationControl(after, { chooseRepair: () => "start", confirmRepair: reviewed(confirmRepair), readGitOriginals });
+  const changed = after.changes.length + (after.repair?.items.filter((item) => item.outcome === "repaired").length ?? 0);
+  const outcome = changed ? (after.status === "current" ? "applied" : "partial")
+    : diagnostics.length || after.repair?.status === "needs_input" ? "needs_input" : "deferred";
+  return maintenanceResult(target, after, { operation: "guided", outcome, diagnostics });
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/runtime/core/lib/control-read/fs.js

@@ -0,0 +1,55 @@
+import * as native from 'node:fs';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+// Only read owners import this seam. No global fs patch and no writer API.
+const context = new AsyncLocalStorage();
+const memo = new WeakMap();
+export function memoizeControlRead(key, work) {
+  const view = context.getStore()?.view;
+  if (!view) return work();
+  let cache = memo.get(view);
+  if (!cache) { cache = new Map(); memo.set(view, cache); }
+  if (!cache.has(key)) {
+    const result = work();
+    if (context.getStore()?.denied) throw Object.assign(Error('resource_denied'), { code: 'resource_denied' });
+    cache.set(key, result);
+  }
+  return cache.get(key);
+}
+// A mutation owner must not inherit a pre-write captured observation.
+export function withLiveControlReads(work) { return context.run(undefined, work); }
+
+export function withControlReadView(view, work) {
+  const scope = { view, denied: false };
+  const check = value => {
+    if (scope.denied) throw Object.assign(Error('resource_denied'), { code: 'resource_denied' });
+    return value;
+  };
+  return context.run(scope, () => {
+    const result = work();
+    return result instanceof Promise ? result.then(check) : check(result);
+  });
+}
+const read = name => (...args) => {
+  const scope = context.getStore();
+  if (!scope) return native[name](...args);
+  try { return scope.view[name](...args); }
+  catch (error) { if (error.code === 'resource_denied') scope.denied = true; throw error; }
+};
+export const existsSync = read('existsSync');
+export const readFileSync = read('readFileSync');
+export const readdirSync = read('readdirSync');
+export const statSync = read('statSync');
+export const lstatSync = read('lstatSync');
+// Containment/type checks do not consume directory size or timestamps. Keep
+// their identity dependency separate from callers that actually inspect stats.
+export const lstatKindSync = path => {
+  const scope = context.getStore();
+  if (scope) {
+    try { return scope.view.lstatKindSync(path); }
+    catch (error) { if (error.code === 'resource_denied') scope.denied = true; throw error; }
+  }
+  const stat = native.lstatSync(path);
+  return stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
+};
+export const realpathSync = read('realpathSync');