The eight words

Most products have three vocabularies: one in the code, one in the product spec, and one in the marketing. Ours has one. The words below are the type names in the domain package, the nouns in the API contract, and the nouns on this website — and where a page here says “resource” it is because the code says Resource, not because a writer liked the sound of it.

That is not tidiness for its own sake. It means an engineer, a support lead and somebody in a sales call can describe the same behaviour without anybody translating, and it means a question like “what happens when a Jira ticket already in our context gets edited?” has one answer rather than three.

Resource

One item of knowledge, at a path in your knowledge tree. Its content is the text itself. A GitHub issue is a resource; so is a pull request review, a doc, a release note.

Not “document”, not “file”, not “item”. A resource is the unit the whole system is addressed in.

Origin

Where a resource came from: which source (GitHub, Jira, Slack), the external id there, the URL, the author who wrote it, and when.

Origin travels with the resource permanently. It is the reason a citation is possible three months and four hundred changes later.

Change

Recording a resource is a change: what changed, by which author, when, and a message saying why. Changes are append-only — there is no edit-in-place path, for anyone.

Changes are also idempotent by content. Recording what a path already says records nothing, so a connector can re-sync as often as it likes without inflating the history.

Revision

Every change produces a new revision — a point in history you can read at. “What did we know last Tuesday” is a read at an older revision. “What moved this answer” is a diff of two of them.

Proposal

One or more proposed changes with a message, waiting on a decision. Members and agents never write shared context directly; they open a proposal.

Approved, its changes join the history as ordinary changes on the same straight line. Rejected, it vanishes without a trace — no draft state, no residue. A proposal is decided once, and only while it is pending.

Provenance

Where an answer came from: the revision it was read at, the resource it came from, and the origin URL at the source.

Origin is where the resource came from; provenance is where the answer came from, and it ends at the origin. If you only remember one sentence from this page, it is that every answer cites its source.

Subscription

How an author follows the shared context without holding it. It remembers the last revision they have seen; the feed is every change after that bookmark, and catching up empties it.

Content never travels — only the news that it changed. Your agent reads the news, not the whole newspaper.

Context

The shared context is the sequence of changes. It is deliberately not a code object: there is no Context type to instantiate, because the context is not a thing the system holds — it is what the history adds up to.

Not “knowledge base”. A knowledge base is a place you put things; a shared context is what your team has established.

Two roles, at the boundary

Owner and member are roles, and they live at the authorization boundary rather than in the domain. Members propose; owners decide. Who counts as an owner is enforced where a request arrives, which is why custom roles are a roadmap question and not a change to the model.

The full story told in these words — a narrative and a three-way conversation between product, engineering and marketing — lives in the repository as docs/domain/speaking-the-domain.md.