create-evda 0.1.0

package/lib/resolvers.mjs

@@ -0,0 +1,123 @@
+// The resolver registry: one resolver per reference scheme (Spec 07, section 4).
+//
+// Resolving a reference asks the source whether the pointer still lands, and returns one of three
+// results. It never returns the payload, and it never returns nothing:
+//
+//   { status: "resolved",    at: YYYY-MM-DD, label: string|null }   the source answered; `label`
+//                                                                    is what the source calls the
+//                                                                    thing, offered for the stored
+//                                                                    label and nothing more
+//   { status: "unreachable", why: string }                           the source was asked and did
+//                                                                    not answer
+//   { status: "skipped",     why: string }                           the source was not asked,
+//                                                                    and why
+//
+// A skip is not an empty read. A resolver that has no connector on this machine (Contacts, the
+// password manager, another EVDA's grant) says SKIPPED and why, and the reference renders as its
+// label plus the reason. The url resolver is the one that works everywhere: Node's fetch with a
+// timeout, no dependency.
+//
+// What the registry reads first is the folder's `connectors` list (folder.evda.json): a scheme the
+// folder does not declare is skipped before any resolver runs.
+
+import { SCHEMES } from "./references.mjs";
+import { EvdaError } from "./errors.mjs";
+
+const registry = new Map();
+
+export function registerResolver(scheme, fn) {
+  if (!SCHEMES.includes(scheme)) throw new EvdaError(`"${scheme}" is not a reference scheme (${SCHEMES.join(", ")}).`, { exit: 2 });
+  if (typeof fn !== "function") throw new EvdaError(`resolver for ${scheme} must be a function.`, { exit: 2 });
+  registry.set(scheme, fn);
+}
+
+export function resolverFor(scheme) {
+  return registry.get(scheme) ?? null;
+}
+
+export function registeredSchemes() {
+  return [...registry.keys()].sort();
+}
+
+export const localDate = (d = new Date()) => {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+};
+
+// Fetch a page and read at most `cap` bytes of it, enough for a <title>. The body is dropped on
+// the floor: the result is a status and a title, never the page.
+async function readCapped(res, cap) {
+  if (!res.body) return "";
+  const reader = res.body.getReader();
+  const chunks = [];
+  let got = 0;
+  try {
+    while (got < cap) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      got += value.byteLength;
+    }
+  } finally {
+    try { await reader.cancel(); } catch { /* the stream is already closed */ }
+  }
+  return Buffer.concat(chunks.map((c) => Buffer.from(c))).toString("utf8", 0, cap);
+}
+
+export async function resolveUrl(reference, { fetch = globalThis.fetch, timeoutMs = 5000, now = new Date() } = {}) {
+  if (typeof fetch !== "function") return { status: "skipped", why: "no fetch on this runtime" };
+  let res;
+  try {
+    res = await fetch(reference.pointer, {
+      method: "GET",
+      redirect: "follow",
+      headers: { accept: "text/html, */*;q=0.5" },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (e) {
+    const timedOut = e && (e.name === "TimeoutError" || e.name === "AbortError");
+    return { status: "unreachable", why: timedOut ? `timed out after ${timeoutMs} ms` : `${e.cause?.code ?? e.name ?? "error"}: ${e.cause?.message ?? e.message}` };
+  }
+  if (!res.ok) {
+    try { await res.body?.cancel(); } catch { /* nothing to drop */ }
+    return { status: "unreachable", why: `HTTP ${res.status}` };
+  }
+  const type = res.headers.get("content-type") ?? "";
+  let label = null;
+  if (/html/i.test(type)) {
+    const head = await readCapped(res, 65536);
+    const m = /<title[^>]*>([^<]*)<\/title>/i.exec(head);
+    if (m) label = m[1].replace(/\s+/g, " ").trim() || null;
+  } else {
+    try { await res.body?.cancel(); } catch { /* nothing to drop */ }
+  }
+  return { status: "resolved", at: localDate(now), label };
+}
+
+// The three sources this tool cannot reach on its own. Each says why.
+const NO_CONNECTOR = {
+  contacts: "no Contacts connector on this device; the reference keeps its label",
+  "1password": "no password manager connector on this device; the item is asked for at use, never resolved here",
+  evda: "no grant or projection from that EVDA is held here; the address is kept and nothing about it is known",
+};
+for (const [scheme, why] of Object.entries(NO_CONNECTOR)) registerResolver(scheme, async () => ({ status: "skipped", why }));
+registerResolver("url", resolveUrl);
+
+// Resolve one parsed reference (from references.mjs validateReference or parseReference).
+// `connectors` is the folder's list; when given, a scheme it does not name is skipped.
+export async function resolveReference(reference, { connectors = null, ...opts } = {}) {
+  if (!reference || !reference.scheme) throw new EvdaError("resolveReference needs a parsed reference with a scheme.", { exit: 2 });
+  if (Array.isArray(connectors) && !connectors.includes(reference.scheme)) {
+    return { status: "skipped", why: `the folder does not declare the ${reference.scheme} connector (it declares: ${connectors.join(", ") || "none"})` };
+  }
+  const fn = resolverFor(reference.scheme);
+  if (!fn) return { status: "skipped", why: `no resolver is registered for ${reference.scheme}` };
+  const r = await fn(reference, opts);
+  if (!r || !["resolved", "unreachable", "skipped"].includes(r.status)) {
+    throw new EvdaError(`resolver for ${reference.scheme} returned ${JSON.stringify(r)}; a result is resolved, unreachable or skipped, never nothing.`, { exit: 1 });
+  }
+  if (r.status !== "resolved" && !(typeof r.why === "string" && r.why.trim() !== "")) {
+    throw new EvdaError(`resolver for ${reference.scheme} returned ${r.status} without saying why.`, { exit: 1 });
+  }
+  return r;
+}

package/lib/roles.mjs

@@ -0,0 +1,89 @@
+// Roles, not paths. Spec 05, "The layout is declared, not imposed."
+//
+// A tool never writes `record/daily` into its own code. It asks the manifest where the
+// `record/daily` role lives, and the manifest may answer with anything relative to the root
+// (an adopted folder of notes might answer `journal/days`). A role may be absent; a mapped role whose
+// path is missing is a loud failure, never an empty read.
+
+import { existsSync, statSync } from "node:fs";
+import { join, resolve, sep, isAbsolute } from "node:path";
+import { EvdaError } from "./errors.mjs";
+
+export const ROLES = {
+  // The operating layer. A file, not a directory, and not part of any declared layer: every record
+  // has one, whatever it is called. A scaffold maps it to AGENTS.md; an adopted vault might map it
+  // to CLAUDE.md. Only a record with NO operating layer is a failure.
+  agents: { layer: null, kind: "file" },
+  "record/daily": { layer: "record", kind: "dir" },
+  "record/captures": { layer: "record", kind: "dir" },
+  "record/people": { layer: "record", kind: "dir" },
+  ledger: { layer: "ledger", kind: "dir", file: "hypotheses.md" },
+  circles: { layer: "circles", kind: "dir" },
+  // Who may read each circle: one grant file per (reader, circle), kept outside the circles as the
+  // substrate keeps members/ outside ecos/. The access answer cannot live inside what it protects.
+  grants: { layer: "circles", kind: "dir" },
+};
+
+export const ROLE_NAMES = Object.keys(ROLES);
+
+export function rolesForLayer(layer) {
+  return ROLE_NAMES.filter((r) => ROLES[r].layer === layer);
+}
+
+// Resolve one role. Never throws for an absent or missing role; the caller decides how loud
+// to be. Throws only when a mapped path escapes the record, which is refused everywhere.
+export function resolveRole(evda, role) {
+  const spec = ROLES[role];
+  const rel = evda.manifest.mapping[role];
+  if (rel === undefined) {
+    return { role, layer: spec?.layer ?? null, known: !!spec, mapped: false, rel: null, abs: null, exists: false };
+  }
+  if (isAbsolute(rel)) {
+    throw new EvdaError(`REFUSED: mapping for "${role}" is absolute (${rel}). Mappings are relative to the record root.`, {
+      code: "BAD_MAPPING",
+      exit: 2,
+    });
+  }
+  const abs = resolve(evda.dir, rel);
+  if (abs !== evda.dir && !abs.startsWith(evda.dir + sep)) {
+    throw new EvdaError(`REFUSED: mapping for "${role}" (${rel}) resolves outside the record.`, {
+      code: "BAD_MAPPING",
+      exit: 2,
+    });
+  }
+  const exists = existsSync(abs);
+  const isDir = exists && statSync(abs).isDirectory();
+  const out = { role, layer: spec?.layer ?? null, kind: spec?.kind ?? null, known: !!spec, mapped: true, rel, abs, exists, isDir };
+  if (spec?.file) {
+    out.file = join(abs, spec.file);
+    out.fileRel = join(rel, spec.file);
+    out.fileExists = existsSync(out.file);
+  }
+  return out;
+}
+
+export function resolveAll(evda) {
+  const names = [...ROLE_NAMES, ...Object.keys(evda.manifest.mapping).filter((r) => !ROLES[r])];
+  return names.map((r) => resolveRole(evda, r));
+}
+
+// The operating layer file, or null when no role is mapped. Loud when mapped and missing.
+export function agentsFile(evda) {
+  const r = resolveRole(evda, "agents");
+  if (!r.mapped) return null;
+  if (!r.exists) throw new EvdaError(`agents role is mapped to "${r.rel}" but that file does not exist.`, { code: "MISSING_ROLE" });
+  return r;
+}
+
+// The ledger file, or null when the role is absent. Loud when mapped and missing.
+export function ledgerFile(evda) {
+  const r = resolveRole(evda, "ledger");
+  if (!r.mapped) return null;
+  if (!r.exists) {
+    throw new EvdaError(`ledger role is mapped to "${r.rel}" but that directory does not exist.`, { code: "MISSING_ROLE" });
+  }
+  if (!r.fileExists) {
+    throw new EvdaError(`ledger role is mapped to "${r.rel}" but ${r.fileRel} does not exist.`, { code: "MISSING_ROLE" });
+  }
+  return r;
+}

package/lib/validate.mjs

@@ -0,0 +1,84 @@
+// Entry validation with stable codes. `evda doctor` renders these; the conformance vectors compare
+// them, so a code is part of the format contract and does not change casually. Levels: "fail" is a
+// broken record, "warn" is something a reader should know.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { STATUS_WORDS } from "./ledger.mjs";
+
+
+// The path in a `path` origin. Backticks are the delimiter when present, because a real record has
+// spaces and ampersands in its paths (`captures/Sleep & Evenings/...`). Without backticks the whole
+// body is the path, less a trailing full stop.
+export function originPath(body) {
+  const ticked = /`([^`]+)`/.exec(body);
+  if (ticked) return ticked[1].trim();
+  return body.trim().replace(/\.$/, "");
+}
+
+export function validateEntries(parsed, { root = null } = {}) {
+  const problems = [];
+  const push = (level, code, e, message) => problems.push({ level, code, id: e.id, line: e.line, message });
+  const seen = new Map();
+  let lastNum = 0;
+
+  for (const e of parsed.entries) {
+    if (seen.has(e.id)) push("fail", "DUPLICATE_ID", e, `${e.id} appears twice (first at line ${seen.get(e.id)}). IDs are unique.`);
+    seen.set(e.id, e.line);
+    if (e.num < lastNum) push("warn", "OUT_OF_ORDER", e, `${e.id} comes after H-${String(lastNum).padStart(4, "0")}. The ledger is append-only, so IDs should ascend.`);
+    lastNum = Math.max(lastNum, e.num);
+
+    for (const f of e.missingFields) push("fail", "MISSING_FIELD", e, `${e.id} has no ${f}.`);
+    if (e.status && !STATUS_WORDS.includes(e.statusWord)) push("fail", "BAD_STATUS", e, `${e.id} status "${e.status}" does not start with one of ${STATUS_WORDS.join(" | ")}.`);
+    if (!e.raisedDate) push("warn", "NO_RAISED_DATE", e, `${e.id} Raised has no YYYY-MM-DD date.`);
+    if (!e.test) push("warn", "NO_TEST", e, `${e.id} has no Test. A hypothesis nobody will check is a belief.`);
+    for (const f of e.unknownFields) push("warn", "UNKNOWN_FIELD", e, `${e.id} has a field this tool does not know: "${f}". Preserved, not validated.`);
+
+    // Spec 04 rule 5: standing means tested and survived, so it carries an Outcome. Untested is open.
+    if (e.statusWord === "standing" && !e.outcome) push("fail", "STANDING_NO_OUTCOME", e, `${e.id} is "standing" with an empty Outcome. Standing means the test ran and the claim survived; if it has not been tested it is "open".`);
+    if (e.statusWord === "falsified" && !e.outcome) push("warn", "FALSIFIED_NO_OUTCOME", e, `${e.id} is "falsified" with an empty Outcome. What killed it?`);
+
+    // Spec 04 rule 2: an origin says which of three kinds it is.
+    if (e.origin && !e.originKind) push("warn", "ORIGIN_NO_KIND", e, `${e.id} Origin does not say which kind it is (quote | path | reasoning): "${e.origin.slice(0, 60)}"`);
+    if (e.originKind === "quote" && !/["“”]/.test(e.originBody)) push("warn", "ORIGIN_QUOTE_UNQUOTED", e, `${e.id} Origin is a quote with no quotation marks.`);
+    if (e.originKind === "path" && root) {
+      const target = originPath(e.originBody);
+      if (target && !existsSync(join(root, target))) push("fail", "ORIGIN_PATH_MISSING", e, `${e.id} Origin path "${target}" does not exist in the record.`);
+    }
+
+    // Supersession: both directions must exist, because the "current" view is derived from them.
+    if (e.supersedesText && e.supersedes.length === 0) push("warn", "SUPERSEDES_PROSE", e, `${e.id} Supersedes is prose, not an ID: "${e.supersedesText}". Invisible to the chain.`);
+    if (e.supersededByText && e.supersededBy.length === 0) push("warn", "SUPERSEDED_BY_PROSE", e, `${e.id} Superseded by is prose, not an ID: "${e.supersededByText}". Invisible to the chain.`);
+    for (const id of e.supersedes) {
+      const target = parsed.byId.get(id);
+      if (!target) { push("fail", "SUPERSEDES_MISSING", e, `${e.id} supersedes ${id}, which does not exist.`); continue; }
+      if (!target.supersededBy.includes(e.id)) push("fail", "SUPERSEDES_ASYMMETRIC", e, `${e.id} supersedes ${id} but ${id} does not say Superseded by: ${e.id}. The chain reads differently from each end.`);
+    }
+    for (const id of e.supersededBy) {
+      const target = parsed.byId.get(id);
+      if (!target) { push("fail", "SUPERSEDED_BY_MISSING", e, `${e.id} is superseded by ${id}, which does not exist.`); continue; }
+      if (!target.supersedes.includes(e.id)) push("fail", "SUPERSEDED_BY_ASYMMETRIC", e, `${e.id} says Superseded by: ${id} but ${id} does not say Supersedes: ${e.id}.`);
+    }
+    if (e.supersededBy.length && ["open", "standing"].includes(e.statusWord)) push("warn", "SUPERSEDED_STILL_OPEN", e, `${e.id} is superseded by ${e.supersededBy[0]} but its status is still "${e.statusWord}".`);
+    if (e.statusWord === "refined" && e.supersededBy.length === 0 && !e.supersededByText) push("warn", "REFINED_NOT_SUPERSEDED", e, `${e.id} is "refined" but nothing supersedes it. What was the refinement?`);
+
+    // Due is optional, and an absent Due is the normal parked state rather than a defect.
+    // Reversed 2026-09-16 after one night of requiring it. The owner's correction: "It's not like you
+    // need to keep questioning me about this stuff. We can never reach an answer. For something like
+    // this we can fucking park it." A hypothesis is how a person holds their thinking loosely, not a
+    // task with a deadline, and a system that brings it back on a schedule turns their thinking into a
+    // queue they owe answers to. What surfaces a claim is evidence arriving, never a date passing.
+    // A PRESENT Due is still validated below: a bare `none` still fails.
+    if (e.dueNone && !e.dueNoneReason) push("fail", "DUE_NONE_NO_REASON", e, `${e.id} Due says "none" with no reason. Write: **Due:** none, because <why no date can exist>`);
+    if (e.dueText && !e.due && !e.dueNone) push("fail", "BAD_DUE", e, `${e.id} Due is neither YYYY-MM-DD nor "none, because ...": "${e.dueText}".`);
+
+    // Pushback: quoted, never summarised.
+    for (const p of e.pushback) {
+      if (!/["“”*]/.test(p)) push("warn", "PUSHBACK_UNQUOTED", e, `${e.id} has a pushback bullet with no quotation: "${p.slice(0, 60)}"`);
+    }
+    for (const ev of e.evidence) {
+      if (!/\S/.test(ev)) push("warn", "EMPTY_EVIDENCE", e, `${e.id} has an empty Evidence bullet.`);
+    }
+  }
+  return problems;
+}

package/lib/vectorcli.mjs

@@ -0,0 +1,49 @@
+// `evda vector`: the conformance projection as a command, so a second implementation (a reader in
+// another language) can diff its own projection against this one over the same directory without
+// either depending on the other's code.
+//
+//   evda vector <vdir>            print toVector(<vdir>/ledger.md) as JSON, 2-space, sorted keys off
+//   evda vector <vdir> --check    compare to <vdir>/expected.json; prints CHECKED 1 vector or FAIL
+//   evda vector --all <dir>...    every vector directly under each <dir>, --check each
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { toVector, VECTOR_SOURCE } from "./vectors.mjs";
+import { EvdaError } from "./errors.mjs";
+
+function vectorDirs(base) {
+  if (!existsSync(base)) return [];
+  return readdirSync(base).map((n) => join(base, n)).filter((p) => statSync(p).isDirectory() && existsSync(join(p, VECTOR_SOURCE))).sort();
+}
+
+function checkOne(dir) {
+  const expectedPath = join(dir, "expected.json");
+  const actual = JSON.stringify(toVector(readFileSync(join(dir, VECTOR_SOURCE), "utf8"), { root: dir }), null, 2) + "\n";
+  if (!existsSync(expectedPath)) { console.log(`FAIL ${dir}: no expected.json (freeze it with scripts/freeze-vector.mjs)`); return false; }
+  const expected = readFileSync(expectedPath, "utf8");
+  if (actual !== expected) { console.log(`FAIL ${dir}: projection differs from expected.json`); return false; }
+  return true;
+}
+
+export async function vectorMain(args) {
+  const flags = args.filter((a) => a.startsWith("--"));
+  const positional = args.filter((a) => !a.startsWith("--"));
+  if (flags.includes("--all")) {
+    const bases = (positional.length ? positional : ["vectors"]).map((p) => resolve(p));
+    const dirs = bases.flatMap((b) => vectorDirs(b));
+    if (!dirs.length) throw new EvdaError(`no vectors under ${bases.join(", ")}`, { exit: 2 });
+    let bad = 0;
+    for (const d of dirs) if (!checkOne(d)) bad++;
+    console.log(`CHECKED ${dirs.length} vectors under ${bases.join(", ")}${bad ? `, ${bad} FAILED` : ""}`);
+    return bad ? 1 : 0;
+  }
+  const dir = resolve(positional[0] ?? ".");
+  if (!existsSync(join(dir, VECTOR_SOURCE))) throw new EvdaError(`${dir} has no ${VECTOR_SOURCE}`, { exit: 2 });
+  if (flags.includes("--check")) {
+    const ok = checkOne(dir);
+    if (ok) console.log(`CHECKED 1 vector  ${dir}`);
+    return ok ? 0 : 1;
+  }
+  process.stdout.write(JSON.stringify(toVector(readFileSync(join(dir, VECTOR_SOURCE), "utf8"), { root: dir }), null, 2) + "\n");
+  return 0;
+}

package/lib/vectors.mjs

@@ -0,0 +1,53 @@
+// Conformance vectors (Spec 04, "Two implementations, and the rule that keeps them honest").
+//
+// A vector is a directory holding `ledger.md` and `expected.json`. `toVector` is the neutral
+// projection of a parse that every implementation must reproduce exactly: the parsed entries in a
+// fixed shape, the validation problems by (level, code, id), the derived due index as text, the
+// derived current view, and the chain through every entry that has one. Nothing here is specific
+// to this implementation's internal objects.
+
+import { parseLedger, chain, current } from "./ledger.mjs";
+import { validateEntries } from "./validate.mjs";
+import { deriveDue } from "./index.mjs";
+
+export const VECTOR_SOURCE = "ledger.md";
+
+export function toVector(text, { root = null } = {}) {
+  const parsed = parseLedger(text);
+  const problems = validateEntries(parsed, { root });
+  const chains = {};
+  for (const e of parsed.entries) {
+    if (e.supersedes.length || e.supersededBy.length) chains[e.id] = (chain(parsed, e.id) ?? []).map((x) => x.id);
+  }
+  return {
+    heads: parsed.heads,
+    shape: parsed.shape,
+    entries: parsed.entries.map((e) => ({
+      id: e.id,
+      line: e.line,
+      title: e.title,
+      status_word: e.statusWord,
+      status_qualifier: e.statusQualifier,
+      domain: e.domain,
+      raised_date: e.raisedDate,
+      supersedes: e.supersedes,
+      superseded_by: e.supersededBy,
+      hypothesis: e.hypothesis,
+      origin_kind: e.originKind,
+      origin: e.origin,
+      falsifier: e.falsifier,
+      test: e.test,
+      due: e.due,
+      due_none: e.dueNone,
+      pushback: e.pushback,
+      evidence: e.evidence,
+      outcome: e.outcome,
+      unknown_fields: e.unknownFields,
+      missing_fields: e.missingFields,
+    })),
+    problems: problems.map((p) => ({ level: p.level, code: p.code, id: p.id })),
+    due_jsonl: deriveDue(parsed, VECTOR_SOURCE),
+    current: current(parsed).map((e) => e.id),
+    chains,
+  };
+}