@ecoma-io/archkeep 0.25.0 → 0.26.0

package/src/corpus/goldens/trajectory.json

@@ -0,0 +1,83 @@
+{
+  "schemaVersion": 2,
+  "tool": {
+    "name": "@ecoma-io/archkeep",
+    "version": "0.26.0"
+  },
+  "command": "trajectory",
+  "workspace": {
+    "root": "/tmp/archkeep-golden-fixture",
+    "provider": "native",
+    "marker": "archkeep.json",
+    "provenance": {
+      "commit": "1fd51709c377d99a6139891e1200291cf08aede9",
+      "remote": null,
+      "dirty": false
+    }
+  },
+  "status": "ok",
+  "exitCode": 0,
+  "coverage": {
+    "complete": true,
+    "projects": 3,
+    "analyzedFiles": 3,
+    "imports": 2,
+    "notAnalyzed": [],
+    "blindSpots": [],
+    "notes": [
+      "counts are snapshot-relative: 1 observation are stored graph snapshots — capture points, not commits, days, or captures attempted",
+      "rule-impact cannot be recomputed from stored snapshots — snapshots carry the graph and the policy fingerprint, not the constraint table or import sites, so no violation-level trajectory is reported. Run `delta` between two live points, or `check` at any commit."
+    ]
+  },
+  "result": {
+    "dir": "/tmp/archkeep-golden-fixture/.archkeep-history",
+    "observations": {
+      "count": 1,
+      "basis": "graph_snapshots",
+      "first": "0001-71341a04.json",
+      "last": "0001-71341a04.json",
+      "withProvenance": 1,
+      "dirtyProvenance": 0
+    },
+    "available": false,
+    "unavailableReason": "insufficient_history",
+    "transitions": {
+      "count": 0,
+      "architecture": 0,
+      "policy": 0,
+      "provider": 0,
+      "codeDrift": 0,
+      "incomparable": 0,
+      "unchanged": 0
+    },
+    "disclosures": {
+      "policyOneSided": 0,
+      "provenanceOneSided": 0,
+      "crossRepo": 0
+    },
+    "projects": {
+      "first": 3,
+      "current": 3,
+      "delta": null,
+      "addedEvents": null,
+      "removedEvents": null,
+      "changedEvents": null,
+      "introduced": null,
+      "resolved": null,
+      "persistent": null
+    },
+    "edges": {
+      "first": 2,
+      "current": 2,
+      "delta": null,
+      "addedEvents": null,
+      "removedEvents": null,
+      "changedEvents": null,
+      "introduced": null,
+      "resolved": null,
+      "persistent": null
+    },
+    "trends": null
+  }
+}
+

package/src/corpus/goldens/trajectory.text

@@ -0,0 +1,10 @@
+trajectory  /tmp/archkeep-golden-fixture/.archkeep-history
+1 observation (graph_snapshots), 0 transitions
+✖ insufficient_history: a trajectory needs at least two observations — derived values are unavailable, not zero
+signals  architecture 0 · policy 0 · provider 0 · code drift 0 · incomparable 0 · unchanged 0
+projects  first 3 · current 3 · delta n/a · added n/a · removed n/a · changed n/a · introduced n/a · resolved n/a · persistent n/a
+edges     first 2 · current 2 · delta n/a · added n/a · removed n/a · introduced n/a · resolved n/a · persistent n/a
+disclosures  policy incomparable 0 · provenance incomparable 0 · cross-repo 0 · dirty captures 0 · with provenance 1
+trends  n/a
+counts are snapshot-relative: 1 observation are stored graph snapshots — capture points, not commits, days, or captures attempted
+rule-impact cannot be recomputed from stored snapshots — snapshots carry the graph and the policy fingerprint, not the constraint table or import sites, so no violation-level trajectory is reported. Run `delta` between two live points, or `check` at any commit.

package/src/corpus/goldens/usage-error.text

@@ -0,0 +1,105 @@
+archkeep: no command given.
+archkeep — module-boundary enforcement across every language in the workspace
+
+Usage:
+  archkeep check [<path>...]   Check imports against the boundary rules
+  archkeep graph    Print the project graph as a deterministic snapshot
+  archkeep diff <baseline>   Compare two graph snapshots edge by edge
+  archkeep delta <baseline> | --capture   Classify how boundary violations moved between a captured baseline and head
+  archkeep change <baseline> --intent <file>   Reconcile a declared change intent against the architectural delta
+  archkeep discover [--propose]   Report observed facts, and optionally propose candidate architecture
+  archkeep drift    Compare the observed architecture against the declared intent
+  archkeep reconcile    Compare the declared intent against the observed architecture
+  archkeep waivers    List the boundary waivers and permanent suppressions on the table
+  archkeep fitness    Judge every declared fitness function against the workspace
+  archkeep history <dir>   Describe how the architecture evolved across snapshots
+  archkeep trajectory <dir>   Aggregate the deterministic drift trajectory across snapshots
+  archkeep evolution    Describe how the architecture evolved across a Git revision range
+  archkeep health [<snapshot-dir>]   Describe architecture health metrics and trends
+  archkeep report [<snapshot-dir>]   One governance document: how healthy the architecture is, and why
+  archkeep debt <dir>   Print the architecture-debt ledger across snapshots
+  archkeep impact <project>   List projects that depend on the named project
+  archkeep scenario <project>   Evaluate a hypothetical change against the current workspace
+  archkeep explain <file:line:column>   Explain the judgment for one import site
+  archkeep context <project> [--plan [<path>...]]   Show the architecture constraints that apply to a project
+  archkeep provenance    Describe where this run's facts came from and which rows carry an origin
+  archkeep decisions <id>   Walk the full chain behind one recorded decision — decision to bound rows, projects, findings, and its verification level
+  archkeep adr [<id>]   List recorded architecture decisions and what each binds
+  archkeep rules <list|info|verify|add> [<rule-name>]   List official rules, show details, verify catalog integrity, or add a rule
+  archkeep --help              Show this message
+
+Options:
+  --format text|sarif|json   Terminal report (default), SARIF 2.1.0 for GitHub
+                        code scanning, or the versioned JSON envelope
+                        docs/reference/json-output.md documents
+  --output <file>       Write the report to a file instead of stdout
+  --config <file>       Read the boundary law from here instead of
+                        <workspace root>/module-boundaries.config.mjs
+  --evidence-out <dir>   Also write each custom rule's evidence bundle
+                        into this existing directory, as <rule>.json —
+                        the exact document the rule was judged over
+  --capture             Print an evidence snapshot of the current tree
+                        (raw import records, graph, coverage, policy
+                        fingerprint) for a later delta run to compare against.
+                        Without --output, the snapshot goes to stdout.
+  --event-out <dir>     Append the delta's evolution event to this directory
+                        (one canonical record per transition; idempotent — a
+                        rerun over the same transition writes nothing new).
+                        Absent: no event file is written
+  --intent <file>       The change-intent manifest declaring the material
+                        architectural consequences this change expects
+                        (required; see docs/usage/change.md)
+  --propose             Also derive candidate components, boundaries, tags and rules from
+                        the observed facts — every candidate marked proposed and not
+                        authoritative; nothing is ever written
+  --write-intent <file>   Write the proposed components and rules to a valid
+                        architecture-intent.json file. Only valid with --propose;
+                        refuses to overwrite a file that already exists — the file
+                        is a candidate for drift/reconcile and must be reviewed
+                        before use
+  --base <rev>          The baseline revision — a commit, branch, tag,
+                        or HEAD~n; the first revision analyzed
+  --head <rev>          The tip revision (default HEAD); must be a
+                        linear descendant of --base with no merges between
+  --events <dir>        Link the evolution event store in <dir> so debt entries carry
+                        introducedBy/resolvedBy refs and a resolved list
+  --scenario-file <file>   Path to the scenario JSON file describing the
+                        hypothetical changes to evaluate
+  --plan                Request the agent planning context: current
+                        architecture, applicable policy (with Intent),
+                        impact, current violations, drift, coverage, and
+                        the commands that verify the change. Trailing
+                        paths scope the change; deterministic and
+                        never an LLM plan — Archkeep produces facts,
+                        agents produce plans.
+  --history-dir <dir>   Path to the workspace's history directory. When given and
+                        the directory holds archived snapshots, the planning context
+                        includes the architecture-debt snapshot: current violations,
+                        exemptions, and gaps aged across the history. Used only with
+                        `--plan`; ignored otherwise.
+  --catalog <path>      Path to the catalog file
+                        (default: node_modules/@ecoma-io/archkeep-rules/catalog.json)
+  --to <dir>            Target directory for the .wasm file
+                        (default: tools/rules/)
+
+Projects and tags come from the project graph (archkeep.json or Nx); the rules come from
+module-boundaries.config.mjs at the workspace root — the same table ESLint
+reads, so both enforcers answer from one source. That filename is a
+convention and can be changed per workspace: through archkeep.json's
+`boundaryConfig` field, or the integration's `boundaryConfig` option in nx.json.
+
+Naming paths scopes the run to those files. That is a fast local pre-check and
+not the gate: the cycle and lazy-load rules judge the file graph as a whole, so
+a scoped run can miss what a whole-workspace run would find.
+
+A workspace with a go.work at its root also has its use list compared against
+every project's go.mod, whatever paths scope the run — a module in one list
+and not the other means a developer's go build and CI build different trees.
+
+A workspace whose tsconfig declares a paths table also has each alias judged
+for life: an alias whose every target points into directories that do not
+exist resolves no import, so it fails the run the way a violation does. The
+table itself is never re-resolved — the check reads the same parsed tsconfig
+the import resolver uses.
+
+Exit codes: 0 clean · 1 findings (violations, go.work drift, dead path aliases) · 2 usage error · 3 no verdict (a file could not be analyzed, or the run could not start)

package/src/corpus/goldens/waivers.json

@@ -0,0 +1,40 @@
+{
+  "schemaVersion": 2,
+  "tool": {
+    "name": "@ecoma-io/archkeep",
+    "version": "0.26.0"
+  },
+  "command": "waivers",
+  "workspace": {
+    "root": "/tmp/archkeep-golden-fixture",
+    "provider": "native",
+    "marker": "archkeep.json",
+    "provenance": {
+      "commit": "1fd51709c377d99a6139891e1200291cf08aede9",
+      "remote": null,
+      "dirty": false
+    }
+  },
+  "status": "ok",
+  "exitCode": 0,
+  "coverage": {
+    "complete": true,
+    "projects": 3,
+    "analyzedFiles": 3,
+    "imports": 2,
+    "notAnalyzed": [],
+    "blindSpots": [],
+    "notes": [
+      "remainingMs is the wall clock at the moment of this run, not a fact about the workspace — it is expected to differ between two runs of an unchanged tree and should be excluded from any diff or hash meant to detect real change. Every other field here is deterministic given the same law and the same tree."
+    ]
+  },
+  "result": {
+    "waivers": [],
+    "covered": 0,
+    "expired": 0,
+    "stale": 0,
+    "suppressions": [],
+    "suppressed": 0
+  }
+}
+

package/src/corpus/goldens/waivers.text

@@ -0,0 +1 @@
+no waivers — every boundary is enforced, nothing is being accepted temporarily or permanently

package/src/corpus/goldens-lsp/initialize.result.json

@@ -0,0 +1,15 @@
+{
+  "capabilities": {
+    "textDocumentSync": {
+      "change": 1,
+      "openClose": true,
+      "save": {
+        "includeText": false
+      }
+    }
+  },
+  "serverInfo": {
+    "name": "archkeep",
+    "version": "<version>"
+  }
+}

package/src/corpus/goldens-lsp/publish-cleared-empty.json

@@ -0,0 +1,4 @@
+{
+  "diagnostics": [],
+  "uri": "file:///tmp/archkeep-lsp-golden-fixture/libs/inner/main.go"
+}

package/src/corpus/goldens-lsp/publish-fixed-empty.json

@@ -0,0 +1,5 @@
+{
+  "diagnostics": [],
+  "uri": "file:///tmp/archkeep-lsp-golden-fixture/libs/inner/main.go",
+  "version": 2
+}

package/src/corpus/goldens-lsp/publish-unparseable.json

@@ -0,0 +1,54 @@
+{
+  "diagnostics": [
+    {
+      "code": "analysisFailure",
+      "message": "Module boundaries were not fully checked here: parse error: ',' expected.. Imports this server could not read are not covered by the verdict below.",
+      "range": {
+        "end": {
+          "character": 15,
+          "line": 0
+        },
+        "start": {
+          "character": 15,
+          "line": 0
+        }
+      },
+      "severity": 2,
+      "source": "archkeep"
+    },
+    {
+      "code": "analysisFailure",
+      "message": "Module boundaries were not fully checked here: parse error: Expression expected.. Imports this server could not read are not covered by the verdict below.",
+      "range": {
+        "end": {
+          "character": 21,
+          "line": 1
+        },
+        "start": {
+          "character": 21,
+          "line": 1
+        }
+      },
+      "severity": 2,
+      "source": "archkeep"
+    },
+    {
+      "code": "analysisFailure",
+      "message": "Module boundaries were not fully checked here: TypeScript cannot resolve './thing' from 'libs/inner/broken.ts'. Imports this server could not read are not covered by the verdict below.",
+      "range": {
+        "end": {
+          "character": 22,
+          "line": 0
+        },
+        "start": {
+          "character": 20,
+          "line": 0
+        }
+      },
+      "severity": 2,
+      "source": "archkeep"
+    }
+  ],
+  "uri": "file:///tmp/archkeep-lsp-golden-fixture/libs/inner/broken.ts",
+  "version": 1
+}

package/src/corpus/goldens-lsp/publish-violation.json

@@ -0,0 +1,22 @@
+{
+  "diagnostics": [
+    {
+      "code": "onlyTagsConstraintViolation",
+      "message": "A project tagged with \"zone:inner\" can only depend on libs tagged with \"zone:inner\"",
+      "range": {
+        "end": {
+          "character": 27,
+          "line": 3
+        },
+        "start": {
+          "character": 1,
+          "line": 3
+        }
+      },
+      "severity": 1,
+      "source": "archkeep"
+    }
+  ],
+  "uri": "file:///tmp/archkeep-lsp-golden-fixture/libs/inner/main.go",
+  "version": 1
+}

package/src/corpus/goldens-lsp/register-watched-files.json

@@ -0,0 +1,72 @@
+{
+  "registrations": [
+    {
+      "id": "archkeep/watched-files",
+      "method": "workspace/didChangeWatchedFiles",
+      "registerOptions": {
+        "watchers": [
+          {
+            "globPattern": "**/module-boundaries.config.mjs"
+          },
+          {
+            "globPattern": "**/tsconfig.base.json"
+          },
+          {
+            "globPattern": "**/project.json"
+          },
+          {
+            "globPattern": "**/nx.json"
+          },
+          {
+            "globPattern": "**/archkeep.json"
+          },
+          {
+            "globPattern": "**/package.json"
+          },
+          {
+            "globPattern": "**/module-federation.config.js"
+          },
+          {
+            "globPattern": "**/module-federation.config.ts"
+          },
+          {
+            "globPattern": "**/go.mod"
+          },
+          {
+            "globPattern": "**/go.work"
+          },
+          {
+            "globPattern": "**/Cargo.toml"
+          },
+          {
+            "globPattern": "**/pyproject.toml"
+          },
+          {
+            "globPattern": "**/pom.xml"
+          },
+          {
+            "globPattern": "**/settings.gradle"
+          },
+          {
+            "globPattern": "**/settings.gradle.kts"
+          },
+          {
+            "globPattern": "**/build.gradle"
+          },
+          {
+            "globPattern": "**/build.gradle.kts"
+          },
+          {
+            "globPattern": "**/moon.yml"
+          },
+          {
+            "globPattern": "**/.moon/workspace.yml"
+          },
+          {
+            "globPattern": "**/.config/moon/workspace.yml"
+          }
+        ]
+      }
+    }
+  ]
+}

package/src/go-work.mjs

@@ -71,29 +71,6 @@ import { isAbsolute, posix, relative, sep } from "node:path";
 
 import { projectOwning } from "./analysis/source-util.mjs";
 
-/**
- * What each drift finding means — one entry per `messageId` a finding can
- * carry. `../report/sarif.mjs` derives its rule descriptors from this table,
- * the same arrangement it has with `../rules/messages.mjs`, so a kind added
- * here cannot be nameless in a code-scanning upload.
- */
-export const GO_WORK_MESSAGES = Object.freeze({
-  goWorkMissingUse:
-    "A project's go.mod is not in go.work's use list: a developer's go build and gopls skip a " +
-    "module the Nx graph covers, so dev machines and CI select different module sets.",
-  goWorkStaleUse:
-    "A go.work use entry names a directory with no tracked go.mod: go commands fail on developer " +
-    "machines while CI, which never reads go.work, stays green.",
-  goWorkUnmodeledUse:
-    "A go.work use entry names a module the Nx graph does not model: it builds on developer " +
-    "machines while nx affected and the boundary check never see it.",
-  goWorkOutsideUse:
-    "A go.work use entry points outside the workspace: developer builds include a module no run " +
-    "over this workspace can cover.",
-});
-
-export const GO_WORK_MESSAGE_IDS = Object.freeze(Object.keys(GO_WORK_MESSAGES));
-
 /** A parse failure that names its line, so the failure record is actionable. */
 const parseError = (line, reason) => new Error(`go.work:${line}: ${reason}`);
 
@@ -299,6 +276,14 @@ function useDirectory(usePath, workspaceRoot) {
  * - **`goWorkOutsideUse`** — a `use` entry above the workspace root. Whatever
  *   it builds, no run over this workspace can cover it.
  *
+ * One of the FOUR finding families — PD-13 (2026-09-06) outcome (c): no
+ * Finding supertype exists, and the relationship pin lives on
+ * `./rules/index.mjs`'s `violationOf` header. These findings stay this
+ * family's own shape and fold into the one verdict lane as count keys into
+ * `verdictFor` (`./verdict.mjs`). The canonical statement is the
+ * "Finding — the unowned concept" section of
+ * `../../../docs/architecture/refactor/SEMANTIC-MODEL.md`.
+ *
  * @param {{ uses: { path: string, line: number, column: number }[],
  *   workspaceRoot: string,
  *   projects: { name: string, root: string }[],

package/src/governance/evolution-event.mjs

@@ -191,6 +191,21 @@ export function escapeIdentityField(value) {
  * string (#627) — while a triple with no delimiter in any field spells
  * exactly what earlier versions spelled, byte for byte.
  *
+ * One other spelling of edge identity exists in this package, for a
+ * different medium, and the two are deliberately not unified:
+ * `edgeIdentityKey` (`../commands/diff.mjs`) joins the same triple with
+ * `\0` for in-memory set arithmetic in the diff family — `computeDiff`'s
+ * index maps, `trajectory`'s persistence sets — and is never stored. Different
+ * media, one law: each family keeps exactly one identity constructor, and
+ * consumers consume a constructor's output rather than re-deriving a second
+ * spelling of it (`../../../../docs/adr/0008-snapshot-identity-per-family.md`,
+ * INV-6 in `../../../../docs/architecture/refactor/INVARIANTS.md`). An edge
+ * reaches this module only as its raw triple, never as a pre-built string
+ * from either spelling (`evolutionBoundary` below refuses one), and a
+ * `\0`-joined diff key written into an event would give one edge two
+ * spellings inside the store — every identity string it already holds reads
+ * `source>target:type`.
+ *
  * @param {{source: string, target: string, type: string}} edge
  * @returns {string}
  */

package/src/governance/evolution-store.mjs

@@ -101,8 +101,14 @@ function shortId(id) {
  * silently manufacture duplicates — the failure shape this store exists to
  * rule out.
  *
+ * It then runs the same vocabulary rules the read path enforces (see
+ * `eventVocabularyViolation`): a record outside the event vocabulary — a
+ * wrong `schemaVersion`, a classification or disposition outside its
+ * vocabulary — is refused BEFORE it can be persisted, so `writeEvent` never
+ * writes a record `readEvents` would refuse and brick the store on (#738).
+ *
  * @param {object} event The event to write.
- * @throws {Error} naming the mismatch.
+ * @throws {Error} naming the mismatch or the violated vocabulary rule.
  */
 function validateEventForWrite(event) {
   if (typeof event !== "object" || event === null || Array.isArray(event)) {
@@ -130,12 +136,50 @@ function validateEventForWrite(event) {
         "tuple {base, head, declarationDigest}",
     );
   }
+  const violation = eventVocabularyViolation(event);
+  if (violation !== null) {
+    throw new Error(`archkeep: refusing to write the evolution event: ${violation}`);
+  }
+}
+
+/**
+ * The three vocabulary rules every stored event must pass — the schema
+ * version, the classification subset, and the disposition — as ONE copy both
+ * sides of the store run: `validateEventForWrite` refuses a write outside
+ * them, `validateEventRecord` refuses a read of one, so a record `writeEvent`
+ * persists is exactly a record `readEvents` accepts and a refused write can
+ * never brick a later read (#738).
+ *
+ * @param {object} event The record to check.
+ * @returns {string|null} The violated rule, or `null` when the record is
+ *   within the vocabulary.
+ */
+function eventVocabularyViolation(event) {
+  if (event.schemaVersion !== EVOLUTION_EVENT_SCHEMA_VERSION) {
+    return `schemaVersion ${JSON.stringify(
+      event.schemaVersion,
+    )} is not ${EVOLUTION_EVENT_SCHEMA_VERSION}`;
+  }
+  if (
+    !Array.isArray(event.classifications) ||
+    event.classifications.some((entry) => !EVENT_CLASSIFICATIONS.includes(entry))
+  ) {
+    return `classifications must be a subset of [${EVENT_CLASSIFICATIONS.join(", ")}]`;
+  }
+  if (!EVENT_DISPOSITIONS.includes(event.disposition)) {
+    return `disposition ${JSON.stringify(
+      event.disposition,
+    )} is not one of [${EVENT_DISPOSITIONS.join(", ")}]`;
+  }
+  return null;
 }
 
 /**
- * The three validations every stored event must pass: the schema version, the
- * classification subset, and the disposition. Any other shape is a malformed
- * store — thrown, never read as an event.
+ * The three vocabulary rules every stored event must pass — the schema
+ * version, the classification subset, and the disposition — the ONE copy
+ * `eventVocabularyViolation` owns, shared with the write path so a record
+ * `writeEvent` accepts is exactly a record `readEvents` accepts. Any other
+ * shape is a malformed store — thrown, never read as an event.
  *
  * @param {object} parsed The parsed record.
  * @param {string} path The file it came from, for the error message.
@@ -147,28 +191,9 @@ function validateEventRecord(parsed, path) {
       `archkeep: malformed evolution event '${path}': the record is not a JSON object`,
     );
   }
-  if (parsed.schemaVersion !== EVOLUTION_EVENT_SCHEMA_VERSION) {
-    throw new Error(
-      `archkeep: malformed evolution event '${path}': schemaVersion ${JSON.stringify(
-        parsed.schemaVersion,
-      )} is not ${EVOLUTION_EVENT_SCHEMA_VERSION}`,
-    );
-  }
-  if (
-    !Array.isArray(parsed.classifications) ||
-    parsed.classifications.some((entry) => !EVENT_CLASSIFICATIONS.includes(entry))
-  ) {
-    throw new Error(
-      `archkeep: malformed evolution event '${path}': classifications must be a subset of ` +
-        `[${EVENT_CLASSIFICATIONS.join(", ")}]`,
-    );
-  }
-  if (!EVENT_DISPOSITIONS.includes(parsed.disposition)) {
-    throw new Error(
-      `archkeep: malformed evolution event '${path}': disposition ${JSON.stringify(
-        parsed.disposition,
-      )} is not one of [${EVENT_DISPOSITIONS.join(", ")}]`,
-    );
+  const violation = eventVocabularyViolation(parsed);
+  if (violation !== null) {
+    throw new Error(`archkeep: malformed evolution event '${path}': ${violation}`);
   }
 }
 
@@ -182,9 +207,11 @@ function validateEventRecord(parsed, path) {
  * against `io.root`. A missing directory is an empty store: it is created
  * before the scan, so the first event in a fresh store lands at `0000`.
  *
- * The event's `id`/`dedupeKey` must match the canonical tuple (see
- * `validateEventForWrite`) — a caller cannot persist a record whose identity
- * lies about its content.
+ * The event's `id`/`dedupeKey` must match the canonical tuple and the record
+ * must sit within the event vocabulary (see `validateEventForWrite`) — a
+ * caller cannot persist a record whose identity lies about its content, or
+ * whose vocabulary `readEvents` would refuse: the store never gains a file
+ * that would brick its own reads.
  *
  * @param {string} dir Absolute or relative path to the event store directory.
  * @param {object} event The EvolutionEvent to append.
@@ -200,8 +227,9 @@ function validateEventRecord(parsed, path) {
  *   against and is REQUIRED for a write.
  * @returns {{id: string, duplicate: boolean}} The event id, and whether this
  *   call wrote nothing because the event already existed.
- * @throws {Error} on a mismatched event identity, an unreadable or malformed
- *   store, a containment violation, or a `wx` refusal.
+ * @throws {Error} on an event that fails validation (identity or vocabulary),
+ *   an unreadable or malformed store, a containment violation, or a `wx`
+ *   refusal.
  */
 export function writeEvent(dir, event, io = {}) {
   validateEventForWrite(event);