Skip to content

The store layout has no owner, so its path conventions are duplicated across the codebase #989

Description

@williamthorsen

Problem

The store's on-disk layout has no owner, so the conventions that define it are re-declared at every site that needs them.

The events-path convention (content/events/{id}.md) is hardcoded independently at five production sites across two packages, with nothing keeping them in agreement:

File Role
packages/kb/src/create/create.ts:116 Creates the directory
packages/agents/src/capture-event/write-event.ts:15 Writes events into it
packages/agents/src/capture-event/cli.ts:249 Resolves an event's path
packages/agents/src/capture-event/event-push-state.ts:18 Checks push state against it
packages/agents/src/kb-update-events/cli.ts:181 Edits events in it

If the convention moves, event-push-state.ts goes stale silently. Its catch { return false } maps any failure to "not pushed", which means "editable" — so a stale path costs the store its event immutability with no error, no warning, and no failing test.

The .kb directory name and the content/ root are scattered the same way, across both packages. Drift there fails loudly rather than silently, but the cause is identical.

The tests that appear to guard the events path cannot. event-push-state.test.ts:85 builds its fixture by re-declaring the same literal the code under test declares, so a drifted layout would strand code and fixture together on the old path and the test would keep passing.

Those tests are also redundant. capture-event/__tests__/cli.test.ts:621 already drives isEventPushed end-to-end through its only call site (cli.ts:273), against a real git-backed store: an isEventPushed that wrongly returned false would fail to refuse the amend, and that test would go red.

Separately, the agents suite flakes. Tests that stand up a bare remote and run a real git push spawn upwards of a dozen git subprocesses each; alone they finish in about a second, but under full-suite parallelism the spawns contend and stretch past vitest's 5s default, so nmr --filter agents test fails intermittently today. Both git-touching test files do this — event-push-state.test.ts and capture-event/__tests__/cli.test.ts:60, which pushes at line 71 and again through its helper at line 84.

Proposed solution

Give the store's on-disk layout a single owner in packages/kb, and have every site derive its paths from it. packages/kb scaffolds the store and is the natural home; packages/agents already depends on @codeassembly/kb.

The owner is a module of its own, not an addition to records/. records/ maps frontmatter to typed objects and holds no filesystem knowledge; layout is an independent axis, changing when the store's directory shape changes rather than when a record gains a field.

Delete event-push-state.test.ts outright: once drift is unrepresentable, what remains is covered at the CLI level, where the behavior actually lives.

Remove the push from the git-backed fixture that survives. Nothing in the suite needs to exercise git push — a pushed upstream is fixture, not subject, and it can be synthesized locally.

Acceptance criteria

Must have

  • The store's on-disk layout has one definition, owned by a module whose reason to change is the layout itself.
  • Every production site derives the events path from that definition.
  • Every production site derives the .kb directory name and the content/ root from that definition.
  • event-push-state.test.ts is removed.
  • No test in the agents suite pushes to a git remote, and none stands up a bare remote.
  • The refusal to amend a pushed event remains covered.
  • The agents suite passes on repeated full-suite runs with no timeout flake.
  • New and changed behavior in this change is covered by tests.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions