create-evda 0.1.0

package/lib/grants.mjs

@@ -0,0 +1,188 @@
+// Grants: who may read a circle (Spec 07, section 3; Spec 00 #65).
+//
+// A circle answers "who can read this". Its audience is a set of grants, one file each, under the
+// `grants` role, in the substrate's own Member shape (SCHEMA-member, `common/src/member.ts`):
+//
+//   grants/peers/<principalId>--<circle>.eco.yaml
+//
+//   id: members/peers/iris.atlas--workshop.eco
+//   kind: member
+//   schemaVersion: "0.1"
+//   principalKind: peer
+//   principalId: iris.atlas
+//   eco: workshop.eco
+//   role: viewer
+//   grantedAt: 2026-09-16T15:00:00.000Z
+//   grantedBy: dana.atlas
+//   holder:                      person-layer key, preserved by the substrate's parser
+//     kind: agent
+//     name: Iris
+//
+// Every grantee is a peer (#65): a holder owns a record, a record is an atlas, and the substrate's
+// principal kind for another atlas is `peer`. What kind of holder the grantee is (person, agent,
+// company) rides on the grant as `holder`, so the circle can say who reads it without opening the
+// peer's record. An agent holds `viewer` and nothing else: it reads a circle; it does not hold one.
+//
+// Grants live outside the circle they govern, as the substrate keeps `members/` outside `ecos/`:
+// the access answer cannot sit inside the bytes it protects. `test/grants.test.mjs` hands every
+// file this module writes to the substrate's `parseMember`.
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { join, relative } from "node:path";
+import { resolveRole } from "./roles.mjs";
+import { readCircles, ecoNamespace } from "./circles.mjs";
+import { HOLDER_KINDS, holderOf } from "./manifest.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export const MEMBER_ROLES = ["owner", "editor", "viewer"];
+export const PRINCIPAL_KIND = "peer";
+export const GRANTS_SUBDIR = "peers";
+// atlas-arch:yaml-encoding: a grant is a config file this layer names by its suffix, like eco.yaml
+export const GRANT_SUFFIX = ".yaml";
+
+const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+// A principal id is another record's atlas id. The substrate's rules (member.ts): never `--`,
+// which delimits the filename; never `/`, which is a path.
+export function checkPrincipalId(id) {
+  if (!nonEmpty(id)) throw new EvdaError("a grant needs the grantee record's id (its atlas id, such as iris.atlas).", { exit: 2 });
+  if (/\s/.test(id) || id.includes("--") || id.includes("/") || id.includes("..")) throw new EvdaError(`"${id}" is not a record id: no whitespace, no --, no /.`, { exit: 2 });
+  return id;
+}
+
+export const grantsDir = (evda) => resolveRole(evda, "grants");
+export const grantId = (principalId, eco) => `members/${PRINCIPAL_KIND}s/${principalId}--${eco}`;
+export const grantFile = (principalId, eco) => `${principalId}--${eco}${GRANT_SUFFIX}`;
+
+// Build a grant in the substrate's Member shape.
+export function grantManifest({ to, circle, role = "viewer", by, at = new Date() }) {
+  const principalId = checkPrincipalId(to?.id);
+  if (!isObject(to) || !HOLDER_KINDS.includes(to.kind)) throw new EvdaError(`a grant names the holder's kind: ${HOLDER_KINDS.join(", ")}.`, { exit: 2 });
+  if (!MEMBER_ROLES.includes(role)) throw new EvdaError(`role must be one of ${MEMBER_ROLES.join(", ")}, got ${JSON.stringify(role)}.`, { exit: 2 });
+  if (to.kind === "agent" && role !== "viewer") throw new EvdaError(`REFUSED: an agent holds viewer and nothing else. It reads a circle; it does not hold one (Spec 00 #65).`, { code: "AGENT_ROLE", exit: 2 });
+  if (!nonEmpty(by)) throw new EvdaError("a grant says who granted it (grantedBy).", { exit: 2 });
+  const eco = ecoNamespace(circle);
+  const m = {
+    id: grantId(principalId, eco),
+    kind: "member",
+    schemaVersion: "0.1",
+    principalKind: PRINCIPAL_KIND,
+    principalId,
+    eco,
+    role,
+    grantedAt: at instanceof Date ? at.toISOString() : String(at),
+    grantedBy: by,
+    holder: { kind: to.kind },
+  };
+  if (nonEmpty(to.name)) m.holder.name = to.name.trim();
+  return m;
+}
+
+// Read every grant file under the role. Returns [{ file, rel, manifest, problems, principalId,
+// circle, role, holder }]. Never throws for a problem in a file; each is listed.
+export function readGrants(evda) {
+  const role = grantsDir(evda);
+  if (!role.mapped) return null;
+  if (!role.exists || !role.isDir) throw new EvdaError(`grants role is mapped to "${role.rel}" but that directory does not exist.`, { code: "MISSING_ROLE" });
+  const dir = join(role.abs, GRANTS_SUBDIR);
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir).sort()) {
+    const abs = join(dir, name);
+    if (name.startsWith(".") || !statSync(abs).isFile() || !name.endsWith(GRANT_SUFFIX)) continue;
+    const rel = relative(evda.dir, abs);
+    const problems = [];
+    const fail = (m) => problems.push({ level: "fail", message: `${rel}: ${m}` });
+    const warn = (m) => problems.push({ level: "warn", message: `${rel}: ${m}` });
+    const g = { file: abs, rel, manifest: null, problems, principalId: null, circle: null, role: null, holder: null };
+    out.push(g);
+    let m;
+    try {
+      m = parseYaml(readFileSync(abs, "utf8"));
+    } catch (e) {
+      fail(`is not readable YAML (${e.message}).`);
+      continue;
+    }
+    if (!isObject(m)) { fail("must hold a mapping."); continue; }
+    g.manifest = m;
+    const slug = name.slice(0, -GRANT_SUFFIX.length);
+    const sep = slug.indexOf("--");
+    const fromName = sep > 0 ? { principalId: slug.slice(0, sep), eco: slug.slice(sep + 2) } : null;
+    if (!fromName) fail(`is not named <principalId>--<circle>.eco${GRANT_SUFFIX}.`);
+    if (m.kind !== "member") fail(`"kind" must be "member", got ${JSON.stringify(m.kind)}. A grant is the substrate's member tuple.`);
+    if (m.principalKind !== PRINCIPAL_KIND) fail(`"principalKind" must be "${PRINCIPAL_KIND}" (#65: every grantee is a record, and a record is a peer), got ${JSON.stringify(m.principalKind)}.`);
+    if (!nonEmpty(m.principalId)) fail(`has no "principalId".`);
+    else if (fromName && m.principalId !== fromName.principalId) fail(`names principalId ${JSON.stringify(m.principalId)} but the file says ${JSON.stringify(fromName.principalId)}. The filename is the address.`);
+    if (!nonEmpty(m.eco) || !m.eco.endsWith(".eco")) fail(`has no "eco" ending in .eco.`);
+    else if (fromName && m.eco !== fromName.eco) fail(`names eco ${JSON.stringify(m.eco)} but the file says ${JSON.stringify(fromName.eco)}.`);
+    if (!MEMBER_ROLES.includes(m.role)) fail(`"role" must be one of ${MEMBER_ROLES.join(", ")}, got ${JSON.stringify(m.role)}.`);
+    if (!nonEmpty(m.grantedAt)) fail(`has no "grantedAt".`);
+    if (!nonEmpty(m.grantedBy)) fail(`has no "grantedBy".`);
+    if (m.id !== undefined && nonEmpty(m.principalId) && nonEmpty(m.eco) && m.id !== grantId(m.principalId, m.eco)) warn(`"id" is ${JSON.stringify(m.id)}; the substrate derives ${grantId(m.principalId, m.eco)}.`);
+    if (!isObject(m.holder) || !HOLDER_KINDS.includes(m.holder.kind)) fail(`has no "holder.kind" (${HOLDER_KINDS.join(", ")}). A circle must be able to say what kind of holder reads it.`);
+    else {
+      g.holder = { kind: m.holder.kind, name: nonEmpty(m.holder.name) ? m.holder.name : null };
+      if (m.holder.kind === "agent" && m.role !== "viewer") fail(`grants ${m.role} to an agent. An agent holds viewer and nothing else (Spec 00 #65).`);
+    }
+    g.principalId = nonEmpty(m.principalId) ? m.principalId : null;
+    g.circle = nonEmpty(m.eco) && m.eco.endsWith(".eco") ? m.eco.slice(0, -".eco".length) : null;
+    g.role = MEMBER_ROLES.includes(m.role) ? m.role : null;
+  }
+  return out;
+}
+
+// Write a grant. Refuses when the circle does not exist, is public (a public circle needs no
+// grant), or the grant exists and overwrite is not set.
+export function grant(evda, { circle, to, role = "viewer", by, at }, { overwrite = false } = {}) {
+  const gr = grantsDir(evda);
+  if (!gr.mapped) throw new EvdaError('no "grants" role in the mapping, so there is nowhere to write a grant.', { exit: 2 });
+  const circles = readCircles(evda);
+  const c = (circles ?? []).find((x) => x.name === circle);
+  if (!c) throw new EvdaError(`no circle named "${circle}" in this record (it has: ${(circles ?? []).map((x) => x.name).join(", ") || "none"}).`, { code: "NO_CIRCLE", exit: 2 });
+  if (c.manifest?.public === true) throw new EvdaError(`circle "${circle}" is public; a public circle needs no grant.`, { code: "PUBLIC_CIRCLE", exit: 2 });
+  const m = grantManifest({ to, circle, role, by: by ?? holderOf(evda).id ?? holderOf(evda).name ?? "owner", at });
+  const dir = join(gr.abs, GRANTS_SUBDIR);
+  const p = join(dir, grantFile(m.principalId, m.eco));
+  if (existsSync(p) && !overwrite) throw new EvdaError(`${relative(evda.dir, p)} exists; pass overwrite to replace it.`, { exit: 2 });
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(p, toYaml(m));
+  return p;
+}
+
+// Remove a grant. Returns true when a file was removed.
+export function revoke(evda, { circle, id }) {
+  const gr = grantsDir(evda);
+  if (!gr.mapped) throw new EvdaError('no "grants" role in the mapping.', { exit: 2 });
+  const p = join(gr.abs, GRANTS_SUBDIR, grantFile(checkPrincipalId(id), ecoNamespace(circle)));
+  if (!existsSync(p)) return false;
+  unlinkSync(p);
+  return true;
+}
+
+// May a principal read a circle? Never a bare boolean: the answer says why, so a refusal names
+// what is missing and a pass names what allowed it.
+export function access(evda, circleName, principalId) {
+  const circles = readCircles(evda) ?? [];
+  const c = circles.find((x) => x.name === circleName);
+  if (!c) return { allowed: false, why: `no circle named "${circleName}"`, circle: null, grant: null };
+  const broken = c.problems.find((p) => p.level === "fail");
+  if (broken) return { allowed: false, why: `circle "${circleName}" is malformed: ${broken.message}`, circle: c, grant: null };
+  if (c.manifest.public === true) return { allowed: true, why: "the circle is public", circle: c, grant: null };
+  if (!nonEmpty(principalId)) return { allowed: false, why: `circle "${circleName}" is private and no reader was named`, circle: c, grant: null };
+  const grants = readGrants(evda);
+  if (grants === null) return { allowed: false, why: `circle "${circleName}" is private and this record has no grants role`, circle: c, grant: null };
+  const g = grants.find((x) => x.principalId === principalId && x.circle === circleName && x.problems.every((p) => p.level !== "fail"));
+  if (!g) return { allowed: false, why: `no grant on circle "${circleName}" for ${principalId}`, circle: c, grant: null };
+  return { allowed: true, why: `${g.role} grant to ${g.holder.kind}${g.holder.name ? ` ${g.holder.name}` : ""} (${g.rel})`, circle: c, grant: g };
+}
+
+// Open a circle as a principal. Returns the validated circle when the reader may read it; throws
+// REFUSED (exit 2) when not. Reading the circle's bytes is not built; this returns what the circle
+// declares (members by path) and nothing under those paths is opened here.
+export function readCircleAs(evda, circleName, principalId) {
+  const a = access(evda, circleName, principalId);
+  if (!a.allowed) throw new EvdaError(`REFUSED: ${a.why}.`, { code: "NO_GRANT", exit: 2 });
+  return { circle: a.circle, why: a.why, members: a.circle.members };
+}

package/lib/index.mjs

@@ -0,0 +1,67 @@
+// The derived directory: .evda/due.jsonl and .evda/digest.md.
+//
+// due.jsonl is derived from the ledger's `**Due:**` lines and nothing else. Deterministic: one row
+// per entry, fixed key order, sorted by (due, id), trailing newline, empty file when nothing is
+// due. digest.md is derived from the generated block of AGENTS.md. Both can be deleted and rebuilt
+// byte-identical, which is the proof that the plain files are the truth and .evda/ is a cache.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { readLedger } from "./ledger.mjs";
+import { resolveRole } from "./roles.mjs";
+import { splitFence, digestFrom } from "./agents.mjs";
+
+export const indexPath = (evda) => join(evda.dir, ".evda", "due.jsonl");
+export const digestPath = (evda) => join(evda.dir, ".evda", "digest.md");
+
+// An entry is due while it still has a live test: it names a date, nothing has superseded it, and
+// it has not already been resolved.
+export function deriveDue(parsed, source) {
+  const rows = parsed.entries
+    .filter((e) => e.due && e.supersededBy.length === 0 && !["falsified", "retired"].includes(e.statusWord))
+    .map((e) => ({ id: e.id, due: e.due, status: e.statusWord, hypothesis: e.title, test: e.test, source }))
+    .sort((a, b) => (a.due === b.due ? a.id.localeCompare(b.id) : a.due.localeCompare(b.due)));
+  return rows.length ? rows.map((r) => JSON.stringify(r)).join("\n") + "\n" : "";
+}
+
+// What the index should say right now. null when the record has no ledger role.
+export function expectedIndex(evda) {
+  const ledger = readLedger(evda);
+  if (!ledger) return null;
+  return { text: deriveDue(ledger.parsed, ledger.rel), count: ledger.parsed.entries.filter((e) => e.due).length };
+}
+
+// What the digest should say right now. null when the operating layer is unmapped, missing, or
+// has no generated fence.
+export function expectedDigest(evda) {
+  const r = resolveRole(evda, "agents");
+  if (!r.mapped || !r.exists) return null;
+  const parts = splitFence(readFileSync(r.abs, "utf8"));
+  return parts ? digestFrom(parts.generated) : null;
+}
+
+export function currentIndex(evda) {
+  const p = indexPath(evda);
+  return existsSync(p) ? readFileSync(p, "utf8") : null;
+}
+
+export function currentDigest(evda) {
+  const p = digestPath(evda);
+  return existsSync(p) ? readFileSync(p, "utf8") : null;
+}
+
+export function reindex(evda) {
+  mkdirSync(join(evda.dir, ".evda"), { recursive: true });
+  const expected = expectedIndex(evda);
+  const text = expected ? expected.text : "";
+  writeFileSync(indexPath(evda), text);
+  const digest = expectedDigest(evda);
+  if (digest !== null) writeFileSync(digestPath(evda), digest);
+  return {
+    path: indexPath(evda),
+    text,
+    rows: text ? text.trimEnd().split("\n").length : 0,
+    ledger: !!expected,
+    digest: digest !== null,
+  };
+}

package/lib/ledger.mjs

@@ -0,0 +1,168 @@
+// The hypothesis ledger, Spec 04. A parser and two derived views (chain, current).
+//
+// The file is flat markdown. Each entry opens with `### H-NNNN: title` and carries bold fields.
+// Nothing here is authoritative; the markdown is. This module reads it and never writes it,
+// because writing the ledger is the agent's job and a CLI that appends entries is the first step
+// toward the tooling becoming the truth.
+
+import { readFileSync } from "node:fs";
+import { ledgerFile } from "./roles.mjs";
+
+export const STATUS_WORDS = ["open", "standing", "refined", "falsified", "retired"];
+export const REQUIRED_FIELDS = ["Status", "Hypothesis", "Origin", "Falsifier"];
+export const KNOWN_FIELDS = [
+  "Status", "Domain", "Raised", "Supersedes", "Superseded by", "Hypothesis", "Origin",
+  "Falsifier", "Test", "Due", "Confirmed", "Pushback", "Evidence", "Outcome",
+];
+// Spec 04 rule 2: an origin says which of three kinds it is.
+export const ORIGIN_KINDS = ["quote", "path", "reasoning"];
+const LIST_FIELDS = ["Pushback", "Evidence"];
+
+// Anchored at column 0 on purpose: the entry template at the top of the file is indented, and
+// an indented `### H-0042:` is a shape to copy, not an entry.
+//
+// Two heading shapes are accepted, because two implementations settled on different ones the
+// night this was written and `ledger.py list` read 0 entries out of 34 as a result:
+//   ### H-0001: title        the spec's shape, and what the real ledger uses
+//   ## H-0001 <sep> title    where <sep> is ":", "-", or a dash character
+// The shape of the first entry in a file is reported as `shape`, so a writer can copy it.
+export const ENTRY_HEAD = /^(#{2,3}) (H-\d{4})(?:\s*([:\-\u2013\u2014])\s*(.*))?$/;
+const FIELD = /^\*\*([A-Za-z][A-Za-z ]*?):\*\*\s?(.*)$/;
+const DATE = /\d{4}-\d{2}-\d{2}/;
+const ID = /H-\d{4}/g;
+
+export const oneLine = (s) => (s ?? "").replace(/\s+/g, " ").trim();
+
+// How many entry headings the file has, counted independently of the parser. Doctor compares the
+// two so a parser that silently finds nothing in a full file cannot pass.
+export function countHeads(text) {
+  return text.split("\n").filter((l) => ENTRY_HEAD.test(l)).length;
+}
+
+export function parseLedger(text) {
+  const lines = text.split("\n");
+  const entries = [];
+  let cur = null;
+  let field = null;
+
+  let shape = null;
+  lines.forEach((line, i) => {
+    const h = ENTRY_HEAD.exec(line);
+    if (h) {
+      cur = { id: h[2], num: Number(h[2].slice(2)), title: (h[4] ?? "").trim(), line: i + 1, fields: {}, order: [], pushback: [], evidence: [] };
+      if (!shape) shape = `${h[1]}${h[3] ?? ""}`;
+      entries.push(cur);
+      field = null;
+      return;
+    }
+    if (!cur) return;
+    if (/^## /.test(line) || /^# /.test(line)) { cur = null; field = null; return; }
+    if (/^---\s*$/.test(line)) { field = null; return; }
+    if (line.trim() === "") { field = null; return; }
+
+    const f = FIELD.exec(line);
+    if (f) {
+      field = f[1];
+      cur.fields[field] = f[2];
+      cur.order.push(field);
+      return;
+    }
+    if (!field) return;
+    if (LIST_FIELDS.includes(field)) {
+      const list = field === "Pushback" ? cur.pushback : cur.evidence;
+      if (/^- /.test(line)) { list.push(line.slice(2)); return; }
+      if (/^\s+\S/.test(line) && list.length) { list[list.length - 1] += " " + line.trim(); return; }
+    }
+    cur.fields[field] += "\n" + line;
+  });
+
+  const normalized = entries.map(normalize);
+  const byId = new Map(normalized.map((e) => [e.id, e]));
+  return { entries: normalized, byId, heads: countHeads(text), shape };
+}
+
+function normalize(e) {
+  const f = e.fields;
+  const status = oneLine(f.Status);
+  const statusMatch = /^([a-z]+)\b\s*(.*)$/i.exec(status);
+  const statusWord = statusMatch ? statusMatch[1].toLowerCase() : "";
+  const raised = oneLine(f.Raised);
+  const raisedDate = DATE.exec(raised)?.[0] ?? null;
+  const dueText = oneLine(f.Due);
+  const due = /^(\d{4}-\d{2}-\d{2})/.exec(dueText)?.[1] ?? null;
+  // `Due: none, because <reason>` is the explicit statement that no date exists. It is not a
+  // missing date and not a bad one; a "none" with no reason is an invented emptiness.
+  const dueNone = /^none\b/i.test(dueText);
+  const dueNoneReason = dueNone ? oneLine(dueText.replace(/^none\b[,:.]?\s*(?:because\s*)?/i, "")) : "";
+  const confirmed = /^(\d{4}-\d{2}-\d{2})/.exec(oneLine(f.Confirmed))?.[1] ?? null;
+  const supersedesText = oneLine(f.Supersedes);
+  const supersededByText = oneLine(f["Superseded by"]);
+  const origin = oneLine(f.Origin);
+  const originKindMatch = /^(quote|path|reasoning)\b[:.,]?\s*(.*)$/i.exec(origin);
+  return {
+    ...e,
+    status,
+    statusWord,
+    statusQualifier: statusMatch ? oneLine(statusMatch[2].replace(/^,\s*/, "")) : "",
+    domain: oneLine(f.Domain),
+    raised,
+    raisedDate,
+    supersedes: supersedesText.match(ID) ?? [],
+    supersedesText,
+    supersededBy: supersededByText.match(ID) ?? [],
+    supersededByText,
+    hypothesis: oneLine(f.Hypothesis),
+    origin,
+    originKind: originKindMatch ? originKindMatch[1].toLowerCase() : null,
+    originBody: originKindMatch ? originKindMatch[2] : origin,
+    falsifier: oneLine(f.Falsifier),
+    test: oneLine(f.Test),
+    due,
+    dueText,
+    dueNone,
+    dueNoneReason,
+    confirmed,
+    pushbackNote: oneLine(f.Pushback),
+    evidenceNote: oneLine(f.Evidence),
+    outcome: oneLine(f.Outcome),
+    unknownFields: e.order.filter((k) => !KNOWN_FIELDS.includes(k)),
+    missingFields: REQUIRED_FIELDS.filter((k) => !(k in f) || oneLine(f[k]) === ""),
+  };
+}
+
+// Read the ledger through the mapping. null when the role is absent; throws when mapped and missing.
+export function readLedger(evda) {
+  const r = ledgerFile(evda);
+  if (!r) return null;
+  const text = readFileSync(r.file, "utf8");
+  return { path: r.file, rel: r.fileRel, text, parsed: parseLedger(text) };
+}
+
+// Supersession chain through one entry: earliest ancestor first, latest descendant last.
+export function chain(parsed, id) {
+  const seen = new Set();
+  const back = [];
+  let cur = parsed.byId.get(id);
+  if (!cur) return null;
+  while (cur && !seen.has(cur.id)) {
+    seen.add(cur.id);
+    back.unshift(cur);
+    cur = cur.supersedes[0] ? parsed.byId.get(cur.supersedes[0]) : null;
+  }
+  const fwd = [];
+  cur = parsed.byId.get(id);
+  cur = cur.supersededBy[0] ? parsed.byId.get(cur.supersededBy[0]) : null;
+  while (cur && !seen.has(cur.id)) {
+    seen.add(cur.id);
+    fwd.push(cur);
+    cur = cur.supersededBy[0] ? parsed.byId.get(cur.supersededBy[0]) : null;
+  }
+  return [...back, ...fwd];
+}
+
+// The "current" view. Derived, never stored (Spec 05, supersession).
+export function current(parsed) {
+  return parsed.entries.filter(
+    (e) => e.supersededBy.length === 0 && !["falsified", "retired", "refined"].includes(e.statusWord)
+  );
+}

package/lib/locate.mjs

@@ -0,0 +1,76 @@
+// The locator. An EVDA is not the current directory (Spec 05, ruling 1 from gstack): an agent is
+// usually working somewhere else when it needs the record. Resolution order, first hit wins:
+//
+//   1. an explicit directory passed to the command
+//   2. $EVDA_HOME
+//   3. the nearest ancestor of the working directory holding evda.json
+//   4. ~/.evda/current, a symlink to the record or a file holding its path
+//
+// An env var is a deliberate instruction for the session, so it beats the incidental fact of
+// where the shell happens to be. Every result says which rule found it, so a wrong record is
+// diagnosable in one line.
+
+import { existsSync, lstatSync, readlinkSync, readFileSync, mkdirSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { findRoot, manifestPath } from "./manifest.mjs";
+import { EvdaError } from "./errors.mjs";
+
+export function pointerPath(env = process.env) {
+  return env.EVDA_CURRENT_FILE ?? join(env.HOME ?? homedir(), ".evda", "current");
+}
+
+export function readPointer(env = process.env) {
+  const p = pointerPath(env);
+  if (!existsSync(p) && !isSymlink(p)) return null;
+  if (isSymlink(p)) return resolve(dirname(p), readlinkSync(p));
+  const raw = readFileSync(p, "utf8").trim();
+  return raw ? resolve(raw) : null;
+}
+
+function isSymlink(p) {
+  try { return lstatSync(p).isSymbolicLink(); } catch { return false; }
+}
+
+// Point ~/.evda/current at a record. Refuses a directory that is not an EVDA.
+export function setPointer(dir, env = process.env) {
+  const abs = resolve(dir);
+  if (!existsSync(manifestPath(abs))) throw new EvdaError(`REFUSED: ${abs} has no evda.json, so it cannot be the current EVDA.`, { exit: 2 });
+  const p = pointerPath(env);
+  mkdirSync(dirname(p), { recursive: true });
+  if (existsSync(p) || isSymlink(p)) unlinkSync(p);
+  try {
+    symlinkSync(abs, p);
+  } catch {
+    writeFileSync(p, abs + "\n");
+  }
+  return p;
+}
+
+export function locate({ explicit = null, cwd = process.cwd(), env = process.env } = {}) {
+  if (explicit) {
+    const dir = resolve(explicit);
+    if (!existsSync(manifestPath(dir))) throw new EvdaError(`REFUSED: ${dir} has no evda.json. This directory is not an EVDA.`, { code: "NO_MANIFEST", exit: 2 });
+    return { dir, via: "argument" };
+  }
+  if (env.EVDA_HOME) {
+    const dir = resolve(env.EVDA_HOME);
+    if (!existsSync(manifestPath(dir))) throw new EvdaError(`REFUSED: EVDA_HOME=${env.EVDA_HOME} has no evda.json.`, { code: "NO_MANIFEST", exit: 2 });
+    return { dir, via: "EVDA_HOME" };
+  }
+  const root = findRoot(cwd);
+  if (root) return { dir: root, via: "working directory" };
+  const pointed = readPointer(env);
+  if (pointed) {
+    if (!existsSync(manifestPath(pointed))) throw new EvdaError(`REFUSED: ${pointerPath(env)} points at ${pointed}, which has no evda.json. Run \`evda use <dir>\` to repoint it.`, { code: "NO_MANIFEST", exit: 2 });
+    return { dir: pointed, via: pointerPath(env) };
+  }
+  throw new EvdaError(
+    [
+      "REFUSED: no EVDA found. Looked, in order, for a directory argument, $EVDA_HOME, an evda.json in",
+      `  ${cwd} or any parent, and ${pointerPath(env)}. None resolved.`,
+      "  Create one: create-evda <dir>. Point at one: evda use <dir>, or export EVDA_HOME=<dir>.",
+    ].join("\n"),
+    { code: "NO_MANIFEST", exit: 2 }
+  );
+}