Skip to content

ontology/ and ontology-kit/: shared option-4 classes on Pages, base URL in one place, immutability and catalog gate (#177) - #178

Merged
michielbdejong merged 2 commits into
mainfrom
claude/ontology-scaffold
Sep 25, 2026
Merged

michielbdejong merged 2 commits into
mainfrom
claude/ontology-scaffold

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Refs #177. The groundwork for the option-4 design, following Michiel's decisions: a top-level ontology/ published at Pages /ontology/, the base URL kept in one place, and strict class matching with Devonian lenses. No plugin uses it yet.

  • ontology/: only generated, immutable term files (extensionless JSON-AD):

    • the release v1;
    • the classes event-v1, issue-v1, time-entry-v1, work-project-v1, work-person-v1, bank-transaction-v1;
    • 22 properties.

    They reuse the atomic-calendar-*, work-*, bank-* and money-* names, and reference task/v1 and core subjects on atomicdata.dev rather than copying them.

  • ontology-kit/ (name still open on Design: plugins sync into shared row classes, and plugin views work on any table of that class ("option 4") #177):

    • base.json: the only place the base URL is written;
    • source.json: the definitions;
    • ontology.mjs build|check, generating terms.mjs subject constants;
    • resolver.mjs: exact class and exact property only, with lens hooks and no duck typing;
    • README.
  • CI check --published origin/main fails on:

    • an invalid source;
    • a stale or stray generated file;
    • any change or removal of a term file already on main. A meaning change needs -v2; the only allowed in-place change is a base move.
  • The gate: while the base is on *.github.io, any catalog entry whose entry, published bundle or plugin code references the base or imports ontology-kit/ must be enabled: false. The base URL written literally outside base.json is refused.

  • Pages: ontology-published.yml checks that every term is served at its subject with the committed bytes.

  • Dev-server: serves /ontology/* with subjects rewritten to its own origin and Pages-like headers. A new ontology e2e lane checks that the pinned host reads event-v1 and accepts a hand-made table of that class.

Checks:

  • the kit's unit tests (28) and the ontology check;
  • oxlint and oxfmt on integrations and ontology-kit;
  • the e2e tsc;
  • the ontology lane e2e, 1 passed at 2567fc30b.

Open: how a plugin's e2e reaches bundled github.io subjects while the dev-server serves them locally; and copying integrations/ alone now needs ontology-kit/ alongside it.

🤖 Generated with Claude Code

Michiel de Jong and others added 2 commits September 25, 2026 17:57
Two top-level folders, per #177 §2.0 and Michiel's decision on question
12: ontology/ holds only the generated, published, immutable term files
(v1, classes/<name>-v1, properties/<shortname>, extensionless JSON-AD);
ontology-kit/ holds base.json (the one place the base URL is written),
source.json, the build and check, the generated subject constants and
the strict field resolver.

- v1: event-v1, issue-v1, time-entry-v1 (with work-project-v1 and
  work-person-v1) and bank-transaction-v1, reusing the calendarFields,
  work-* and bank-* shortnames and referencing task/v1 and core `name`
  by their atomicdata.dev subjects. Declared, not verified.
- `node ontology-kit/ontology.mjs check`: generated files equal a fresh
  build; no term file on origin/main changed or deleted except by a
  base move; the base literal only in base.json and generated/built
  files; and, while the base is on github.io, every catalog entry that
  uses it is `enabled: false`.
- resolver.mjs: exact class and exact property subject only, with lens
  hooks for other shapes. No duck typing.
- CI: the check, the kit's unit tests, and oxlint/oxfmt on
  ontology-kit/ in shared-checks; ontology/** and ontology-kit/** in the
  `any` filter and allowed in lane `paths`; ontology-published.yml
  checks Pages serves each term file at its subject after a build.
- AGENTS.md: the two folders, and that they are approved shared code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ne (#177)

The dev-server serves the committed term files at /ontology/<path>, with
their subjects moved from base.json's base to its own origin and GitHub
Pages' headers (application/octet-stream, access-control-allow-origin *,
a CORS preflight answered 405), as spike S1 imitated. The new tooling
lane `ontology` (index 17, e2e only, runs when ontology/,
ontology-kit/, the dev-server or the pin change) checks that the pinned
host reads event-v1 from there and that atomic-server accepts a table of
that class and a row with one of its properties.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong
michielbdejong merged commit 9b0f886 into main Sep 25, 2026
31 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant