[Upd4ting]

Why

Goal: finish the AntelopeJS docs rewrite. Every TypeScript example compiles against its repo's own source, hand-written version prose is gone, and the W1-W5 docs standard ships. This is the W4 pass for interface-database (outer-loop#35, decision 11 item 5). It brings README.md and docs/ to the Docs standard, in the shape of AntelopeJS/dms packages/dms/docs, and turns standard mode on so CI keeps them there.

Summary

 package.json
   "antelopeJs": {
     "test": ..., "skills": [...],
+    "docs": { "standard": true }
   }
 README.md, docs/**/*.md (25 files)
+  frontmatter title, description, mode (body H1 moved into title)
~  sentence-case headings, no dashes, unslop + technical-writing applied
~  class listings and claims checked against src/staged-query and its TSDoc
+  update() overloads as on this branch (interface-database#65)
-  every `Schema.get(...)!` non-null assertion (17), now an `if (!schema) throw` guard
-  "remains unpublished ... development package version" (version prose, and false)
+  README badges and the query execution SVG marked illustration

No page was split, merged, renamed or moved, and no section, table row or example was dropped. Each docs page lost only its body H1, which moved into title. Fences are unchanged except 3.results/2.write_results.md, which gains one checked ReturnType example (examples 44 to 45). No screenshots, so no docs/captures.ts.

Modes: the docs index and the operations pages except atomic mutations are how-to. The query type pages, the results pages, the operations index and atomic mutations are reference.

Current contract (interface-database#65)

update() lists the updater overload first, as the source does (src/staged-query/selection.ts:40-49,104-113). A function argument gives Query<number> when the object it builds fits DeepPartial<T>, and never otherwise. A partial document gives Query<number>. A value typed any matches the updater overload, so the call is typed never and has no .run(). ReturnType<typeof table.update> reads Query<number>, and a new checked example shows run() resolving to a number. The selection, single selection, CRUD and write results pages all say this.

Claims corrected against the source

• Class listings. Table, Stream, Datum, Query, Schema and SchemaInstance now match src/staged-query/. atomicMutation(key, ...); insert takes DeepPartial<T> & object; getAll takes IndexKeys; between and aggregates take keyof T & string; pluck/without return Pick/Omit; lookup takes a Stream<U> and returns Omit<T, TK> & Record<TK, ...>; default takes U extends QueryValue; the missing distinct(field: undefined) overload is listed; the staged Schema<T, Definition> and its get.
• ValueProxy. epoch() takes no timezone; both split parameters are optional; the during and slice bounds are stated.
• FieldType is StringFieldType | IoTsCodec, and the codec shape needs _A, _O, _I, name, is, encode and decode (schema.ts:41-65). IoTsCodec is not exported.
• Atomic mutations shipped in v0.1.5 (CHANGELOG.md:150). The page said they were unpublished. It now says adapter support is shown by the adapter's implementation and tests. Rejected field names are those that contain . or start with $ (atomic.ts validateField).
• replace() returns the number of modified documents, per its TSDoc. Added from the TSDoc: a changed schema ID leaves old data out of reach; createInstance() resolves to its ID; Schema.get() does not check its type arguments; between() excludes its upper bound; a refused duplicate stores nothing of that row; getAll() without an index matches the primary key.

Heading slugs

{#id} anchors are not used. Five headings changed words, and no link in this repo, in antelope-web or in the AntelopeJS code search points at any of them:

• index#advanced-build-queries-without-executing-them to #build-queries-without-executing-them
• query_types/stream#join---left-join to #join-for-a-left-join
• query_types/stream#joininner---inner-join to #joininner-for-an-inner-join
• query_types/valueproxy#eqvalue--nevalue to #eqvalue-and-nevalue
• query_types/valueproxy#andvalue--orvalue--not to #andvalue-orvalue-and-not

Evidence

• Before (campaign/integration 178776a, tooling-configs dab0aea checkDocs in standard mode, Vale 3.26.0): files=25 examples=44 failures=279.
• After (head b9ef608): files=25 examples=45 failures=0.
• docs-measure on b9ef608 with VALE_BIN set: exit 0.
• pnpm run checks on b9ef608 with GITHUB_BASE_REF=campaign/integration: Checks: 8 passed, 0 failed.
• Rendered anchors: antelope-web campaign/integration a8f40a6, nuxt dev in sites/interfaces with INTERFACES_DOCS_LOCAL=database=<clone>. Every page answers 200, pages=24 links=68 anchored=1 broken=0 (links resolved from each file, as the docs check does), no page renders {#, and the renamed heading ids render.
• CI run 41554252373: every job passed or was skipped. The docs step AntelopeJS/tooling-configs/actions/docs@dab0aea28840981138795aca32381e7fa8ac8d1b installed Vale (standard mode on) and printed Docs: 25 files, 77 local links, 1 compatibility tables, 45 checked examples, 0 API pages; 0 failures. The PR is not docs-only in the docs-only job's sense, because the package.json opt-in is part of it. The docs delta allows that file for this change.

Round 2 (W5 r1 FAIL at b9ef608)

• Blocking, fixed. 3.results/5.database_changes.md listed the staged-query Schema<T, Definition> as the root class. It now lists the root Schema<T = any> (src/schema.ts:13-30): static list(), constructor(id, definition: SchemaDefinition), and the members it inherits from the staged class, which the page names as the staged-query entry's Schema. A tsc probe against the docs project compiles new Schema<Db>(...), Schema.list() and Schema.get<Db>(), and new Schema<Db, SchemaDefinition>(...) fails with TS2558 (Expected 0-1 type arguments, but got 2).
• Notes, fixed. A missing key can give null or undefined (table, single selection, table operations). instance(CROSS_INSTANCE) returns a SchemaInstance. The selection page lists the inherited key, default, union, cast and changes. orderBy() takes an index name, per its TSDoc. default() covers null, per its TSDoc.
• Not changed. The 1.index.md pages link siblings with ./2.table.md, and antelope-web resolves those against the folder route, so the rendered links 404 (/docs/database/table). The links are unchanged from the base and the production site shows the same 404s, so this needs an antelope-web fix.
• On dd2b996: docs-measure with VALE_BIN set exits 0, the standard lever gives failures=0, and pnpm run checks with GITHUB_BASE_REF=campaign/integration gives Checks: 8 passed, 0 failed.
• CI run 41556261776 on dd2b996: every job passed or was skipped. The docs step actions/docs@dab0aea installed Vale and printed Docs: 25 files, 77 local links, 1 compatibility tables, 45 checked examples, 0 API pages; 0 failures.

Merge danger

Door: two-way. Docs and one package.json key. A revert restores the old pages and turns standard mode off.

Blast radius: docs. From here on, every interface-database PR that touches README.md or docs/ must pass Vale and the standard checks in CI.

Attention

• The cast sections of 1.query_types/8.datum.md and 9.valueproxy.md keep their one-line cast<U>() examples. They document that published method, and the text says nothing checks the new type. Every other fence is cast-free.
• 3.results/2.write_results.md is now titled "Write results", since it covers update, replace and delete too.
• Not confirmed: that date.sub(date) returns seconds (no TSDoc or test states the unit), that insert() returns provided IDs as well as generated ones, the PostgreSQL detail in atomic mutations, compound index prefix lookups and the index performance advice. These kept their original wording.

[Upd4ting]

W5 review: FAIL at b9ef608

Fresh W5 reviewer. I did not write this PR. I pushed nothing.

Blocking

1. docs/3.results/5.database_changes.md:11-18. The PR replaces a correct listing of Schema with a wrong one. The old listing showed class Schema<T = any> with constructor(id: string, definition: SchemaDefinition). The new one shows class Schema<T = any, Definition = SchemaDefinition> with constructor(id, definition: Definition). That is the staged-query class (src/staged-query/schema.ts:115). The Schema that @antelopejs/interface-database exports, which docs/index.md tells readers to import, is class Schema<T = any> extends StagedSchema<T, SchemaDefinition> (src/schema.ts:13-30). It takes one type argument and also has static list(). A probe with tsc confirms that a // @ts-expect-error on new Schema<X, SchemaDefinition>(...) from the package root holds. Fix: list the root class (Schema<T = any>, constructor(id, definition: SchemaDefinition), static list(), and the inherited static get plus instance methods), and label the two-parameter form as the staged-query entry's class.

Checked and confirmed

• update() contract (interface-database#65). The overload order and types match src/staged-query/selection.ts:40-49,104-113. A tsc probe against src/ confirms each of these, and the same probe fails on a deliberately false assertion:
  • any gives never on both Table and SingleSelection.
  • A fitting updater gives Query<number>, and a misfitting one gives never.
  • A plain partial document gives Query<number>.
  • ReturnType<typeof users.update> and ReturnType<ReturnType<typeof users.get>["update"]> both read Query<number>, with run() resolving to number.
• Removed assertions. The diff removes all 17 Schema.get(...)! non-null assertions. Each is replaced by const x = Schema.get(...) plus if (!x) throw new Error(...). That is honest narrowing of the declared Schema<T, Definition> | undefined return. No !, as, @ts- or any was added in any fence. The page now says that Schema.get() does not check its type arguments, which matches the SAFETY note in the source.
• cast<U>(). 8.datum.md:120 and 9.valueproxy.md (cast<U>() section) both say nothing checks the new type.
• The "unpublished" sentence. It was false: atomicMutation landed in v0.1.5 (CHANGELOG.md), and npm lists 0.1.5 through 0.2.0. It was removed, and the replacement tells readers to check the adapter's implementation and tests.
• Version prose. A grep found none. The only versions in the docs are in the generated compat block, which this PR does not change.
• Other claims. I checked 52 more claims against src/, its TSDoc and tests (signatures, overload order, between bounds, IndexKeys, FieldType and IoTsCodec, ValidateAtomicMutation field rules, createInstance/listInstances, DuplicateKeyError, the exports map, and the Query iterator). All are true apart from the notes below. No true claim was deleted.
• Counts.
  • Before: 178776a with standard mode forced on gives 25 files, 44 checked examples, 279 failures.
  • After: the head gives 45 checked examples, 0 failures.
  • docs-measure with VALE_BIN (Vale 3.26.0) exits 0 at this head.
• Checks and CI. pnpm run checks with GITHUB_BASE_REF=campaign/integration gives Checks: 8 passed, 0 failed. CI run 41554252373 is green, with every job passed or skipped.
• Render. I rendered with antelope-web campaign/integration a8f40a6, nuxt dev in sites/interfaces, and INTERFACES_DOCS_LOCAL. The crawl found 44 pages, 744 links and 423 anchored links. Every #fragment resolves, and no page renders {#. The five renamed heading ids render.

Notes (non-blocking)

• Pre-existing 404 links. The rendered query_types, operations and results index pages link to /docs/database/table and similar paths, which return 404. The real routes are /docs/database/query_types/table and so on. That gives 20 broken page links. The production site shows the same 404s, and the source links did not change, so this is an antelope-web issue with relative links from 1.index.md pages, not a regression from this PR. The hand-back's broken=0 did not count these links.
• Missing keys. 2.table.md:88, 4.single_selection.md:44 and 3.table_operations.md:63 say a provider can return null for a missing key. The shared suite expects undefined (src/tests/basic_operations.test.ts:328). Say "null or undefined".
• 5.database_changes.md:45 says instance(CROSS_INSTANCE) "returns a query stage". It returns a SchemaInstance.
• 3.selection.md:96 says the class "inherits every stream operation", but its list leaves out key, default, union, cast and changes.
• 6.filtering.md:155 says orderBy() takes "a field". The parameter is index.
• default() wording. 8.datum.md:58 says default() covers null or undefined. The TSDoc and the stream and valueproxy pages say null only.
• Unconfirmed. The PR body lists claims it could not confirm. These are also unconfirmed: that replace removes omitted fields, the conflict semantics, and that the index name equals the field name.

Could not confirm

The PostgreSQL detail in atomic mutations, compound-index prefix lookups, that sub returns seconds, and that hasfields checks all fields. These are adapter behaviour that the source does not state.

[Upd4ting]

W5 review: #67, round 2

PASS+NOTES at head dd2b996 (base campaign/integration 178776a). Fresh W5 reviewer. I did not write this PR. I pushed nothing.

Goal (Antony, 2026-10-30): finish the AntelopeJS docs rewrite on campaign/integration. Every TypeScript example compiles against its repo's own source, hand-written version prose is gone, and the W1-W5 docs standard ships.

Round-1 blocker: fixed and true

docs/3.results/5.database_changes.md now lists the root class as class Schema<T = any> extends StagedSchema<T, SchemaDefinition> with static list(): ReadonlyMap<string, Schema> and constructor(id: string, definition: SchemaDefinition), then the inherited members under StagedSchema<T, Definition>. A sentence names StagedSchema as the staged-query entry's Schema. This matches src/schema.ts:13-30 and src/staged-query/schema.ts.

My own tsc probe against src (probe removed after):

• new Schema<X, SchemaDefinition>(...) from the package root fails with TS2558: Expected 0-1 type arguments, but got 2. (its @ts-expect-error holds; removing it surfaces the error).
• ReturnType<typeof Schema.list> equals ReadonlyMap<string, Schema>.
• Schema.get<X>(id) equals StagedQuerySchema<X, SchemaDefinition> | undefined, as listed.
• new StagedQuerySchema<A, { custom: true }>(...) from ./staged-query compiles, so the two-parameter form belongs to that entry.
• Control: a false type equality fails.

The new sentence "A schema defined again under the same ID replaces the earlier one" matches the TSDoc and Map.set in the constructor.

Round-1 notes: all fixed

• Missing keys: 2.table.md, 4.single_selection.md and 3.table_operations.md now say null or undefined.
• instance(CROSS_INSTANCE) now returns a SchemaInstance.
• 3.selection.md adds key, default, union, cast and changes. The list now covers every public method of src/staged-query/stream.ts.
• orderBy() now takes the name of an index (orderBy(index: string, direction?)).
• 8.datum.md default() now says null only, matching the TSDoc.

Notes (non-blocking)

• Schema.list() holds only schemas built through the root Schema constructor (Schema.defined). A schema built with the staged-query Schema is not listed. "every schema this process defined" reads wider than that.
• The pre-existing 1.index.md relative links that antelope-web renders as 404 are still open (an antelope-web fix, not this PR).

Gates

• docs-measure with VALE_BIN (Vale 3.26.0), --dir on a clean clone: exit 0, Docs: 25 files, 77 local links, 1 compatibility tables, 45 checked examples, 0 API pages; 0 failures.
• No {#id}. No as cast or suppression in fences. The cast<U>() hits are documented method signatures.
• pnpm run checks with GITHUB_BASE_REF=campaign/integration: Checks: 8 passed, 0 failed. A first run under load 26 failed one test on mocha's 2000 ms timeout (aggregation_operations). The diff is docs only, and the rerun at load 1 was green.
• CI run 41556261776 is for this head and succeeded, docs step actions/docs@dab0aea with 0 failures. gh pr checks: 5 pass, 2 skipping.
• The r2 diff stays in docs/. Commit message has no attribution.

gate-verdict: PASS+NOTES dd2b996