@raybase/record-mount 0.0.2 → 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Itself & Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,433 @@
-# @raybase/record-mount
+# `@raybase/record-mount`
 
-This name is reserved for Raybase. Nothing is released under it yet, and this package holds no code.
+Optional, explicitly opt-in Raybase module for mounting an **external
+append-only record layer** into a Raybase app.
+
+The record layer is a separate service — a Cloudflare Worker in front of an
+append-only store — that the app reaches over a service binding. This package
+is the app's half of that seam: a typed client pinned to the service's wire
+contract, the two authorization gates that belong in front of it, and the body
+composer a filing needs. It is a **wire client**, not a database: it stores
+nothing, owns no schema, and knows no family names.
+
+## Why this is in Core and not Pro
+
+Recorded at adoption, as a placement decision should be.
+
+**Core.** The mount is client machinery over a published wire contract. It
+touches nothing Pro owns — no D1 control plane, no organizations or
+memberships, no SSO, no Hub, no licensing — and it needs nothing from Pro to
+work. It sits exactly where `@raybase/api` and `@raybase/openai-subscription`
+sit: an optional first-party module a Core app adds explicitly. Putting it in
+Pro would deny it to Core apps and buy nothing.
+
+Placement in Core prices this capability at zero, permanently, and that is
+accepted deliberately. It also draws the seam in the right place for later:
+**Core owns the read-policy hook; an organization-aware implementation of that
+hook is legitimate Pro work.** The interface is the open half; the
+sophisticated filler can be the commercial half without moving anything.
+
+## Provenance
+
+This package folds **two independent builds** of the same brief, written the
+same day against the same request.
+
+An HQ-application session, working ahead toward this package as a dependency,
+built the contract declarations, the error class and envelope rehydration, the
+client with its construction-time address checks and per-stub contract memo,
+the body composer, the mount's two-gate design, and the first draft of the
+in-memory door double. A provider-side session built the read-policy semantics,
+reviewed and finished the above, and wrote the packaging, the suite and this
+file.
+
+Where the two designs differed, the merits decided and the reasons are in the
+code. Named plainly because a package's history is part of what a reader is
+owed, and because "who wrote this" is not a question a changelog should have to
+guess at later.
+
+## The shape
+
+```ts
+import {
+  createRecordBodyComposer,
+  defineRecordMount,
+  openRecordDoor
+} from "@raybase/record-mount";
+import { allowAll } from "@raybase/core";
+import type { RaybaseEnv } from "@raybase/core/worker";
+import type { RecordDoorStub } from "@raybase/record-mount";
+
+type Env = RaybaseEnv & { RECORDS: RecordDoorStub };
+```
+
+The binding is an ordinary Cloudflare service binding in the app's own
+`wrangler.jsonc`. Raybase adds no obstacle here: `RaybaseEnv` is an
+intersection type and unknown bindings ride the app's config untouched.
+
+```jsonc
+{
+  "services": [
+    {
+      "binding": "RECORDS",
+      "service": "your-record-door",
+      "entrypoint": "WriteDoor",
+      "props": { "actor": "your-app", "namespace": "prod" }
+    }
+  ]
+}
+```
+
+Then, per request:
+
+```ts
+const door = openRecordDoor({ env, binding: "RECORDS", namespace: "prod" });
+
+const mount = defineRecordMount({
+  name: "records",
+  door,
+  auth: { audience: "signed-in", policy: allowAll },
+  readPolicy: ({ envelope, viewer }) => visibleTo(envelope, viewer),
+  unfilteredReads: ["materialize"],
+  composer
+});
+
+const page = await mount.list({ family: "decision", status: ["proposed"] }, viewer);
+```
+
+## The address is deploy configuration, not an argument
+
+No verb takes an actor or a namespace. Both ride the binding's `props`, which
+only the app's deploy config can write and which the calling code has no
+runtime channel to set or forge. That one-wayness is what makes the address
+trustworthy, and it is why `namespace` on `openRecordDoor` is documented as a
+**declaration, not a verification**: it buys one namespace per mount, a legible
+name in refusals, and a written claim a reviewer can diff against the deployed
+config. It cannot catch a config that says one thing here and another in the
+props, and it does not pretend to.
+
+Which entrypoint the app binds decides what it may do. A read door genuinely
+lacks `append` and `transition`, so the runtime refuses a write before any
+policy code runs. That wall is real and it always held.
+
+### What a client can and cannot see across the seam
+
+**A Cloudflare RPC service-binding stub answers every property access with a
+callable.** `typeof stub.append === "function"` is true against a read door,
+true against a service that is not a record door at all, and true for a
+property nobody ever defined. Any check written on property presence is
+reading its own assumption back.
+
+So the client asks the door instead. `version()` carries an optional
+`writes` field — the entrypoint's own declaration of whether it holds the write
+verbs — and `door.writable` is a **getter with three states**:
+
+| `door.writable` | Means |
+|---|---|
+| `true` | a write door: a plain binding really has the methods, or an RPC door declared `writes: true` |
+| `false` | a read door: a plain binding really lacks them, or an RPC door declared `writes: false` |
+| `"unknown"` | an RPC door whose declaration has not arrived yet, or one old enough not to declare at all |
+
+`"unknown"` is an honest third state, not a placeholder. For a definite answer,
+`await door.assertContract()` first and then read it: the contract check is the
+call that fetches the declaration, and it is memoized per binding stub, so a
+later client on the same isolate reads the answer without a second round trip.
+
+`"unknown"` never blocks a write. The call goes out, and if the door turns out
+to lack the verb, the runtime's method-missing `TypeError` is **translated**
+into this package's typed `forbidden` refusal, with the original runtime
+message in `detail.cause`. A consumer switches on the taxonomy either way and
+never has to sniff a runtime error's wording.
+
+The translation is deliberately narrow: it fires only when the `TypeError`'s
+message carries the observed method-missing shape *naming the verb itself*
+(`does not implement … "append"`). Two cases therefore propagate untouched: a
+door that declared `writes: true` and throws anyway (lying or broken — dressing
+a real defect as deploy configuration would bury it), and any `TypeError` that
+is not this verb's own method-missing (a broken door, a serialization failure —
+one such mislabel hid a real invocation bug for an evening,
+fnd-2026-08-31-mount-write-call-invocation). If workerd's wording ever shifts,
+the translation stops firing and the raw error surfaces: loud beats mislabeled.
+
+For the same reason, the "this binding is not a record door" check at
+`openRecordDoor` runs **only on a plain binding**, where absence is real. On an
+RPC stub it would pass against anything, so it is skipped rather than performed
+and believed; a binding pointing at the wrong service is caught at its first
+call, as `invalid_binding`.
+
+## The contract pin is fail-closed
+
+The client pins `RECORD_DOOR_CONTRACT_VERSION` and calls `version()` on its
+first verb — memoized per binding stub, which is per isolate. A door serving a
+different version refuses `contract_mismatch` and **nothing proceeds**. There is
+no degrade path and no negotiation.
+
+The check lands at the first verb rather than at construction because a Worker
+constructs its handle on every request, and an RPC round trip there would price
+the check per request. `assertContract()` is the eager form for an app with a
+real boot hook. Two codes are terminal and stay memoized — `contract_mismatch`
+(this door serves another shape) and `invalid_binding` (this binding points at a
+service that is not a record door); both are deploy configuration, and neither
+resolves by being asked again inside one isolate. A failure to *reach* the door
+clears the memo, so a flap does not poison an isolate for its lifetime.
+
+The memo holds the **reply**, not merely the verdict. A Worker builds a client
+per request over one isolate-lifetime stub, so every client after the first
+reads the door's declared capabilities out of the memo rather than never
+learning them.
+
+### When the pin moves, and when it does not
+
+It moves for any change that breaks either direction of the seam: a verb added
+or removed, an argument or return shape altered, a taxonomy code appearing on a
+verb that could not raise it.
+
+It does **not** move for an additive optional field with defined absence
+semantics, because both directions stay compatible — an old client ignores the
+field, and a new client reads absence as "undeclared" and degrades toward
+`unknown`. `version().writes` is exactly that, and it is why the pin is still
+`"1"`. The alternative was worse than pedantic: the pin is fail-closed, so a
+bump to `"2"` would have refused every currently deployed door at once, and this
+package cannot execute that flag day — the doors are deployed by the consuming
+organization, not from this repository. A version bump nobody can land is an
+outage wearing a migration.
+
+## Two gates, and they answer different questions
+
+**Gate 1 — the route's Raybase auth declaration.** `audience` and `policy`,
+exactly as a Raybase action declares them, validated through Core's own
+machinery at mount time and evaluated through it on every call.
+`defineRecordMount` **refuses to mount without one**: a record layer is not a
+surface on which "I forgot" may be spellable, so an explicitly public mount says
+`{ audience: "public", policy: allowAll }` and means it.
+
+Every principal kind is answered for, because the declared policy is evaluable
+against only two of them:
+
+| Principal | Gate 1 |
+|---|---|
+| `public` | judged by the audience alone |
+| `user` | evaluated against the declared policy |
+| `operator` | **also** evaluated against the declared policy — an operator is not exempt |
+| `service` | **refused**, unless the mount declares `allowServicePrincipals` |
+| `agent` | judged as the `user`, `public` or `service` principal it acts for |
+
+A service principal carries no user, so a role policy against it is not merely
+unevaluated but unevaluable — and "the policy could not be applied" must never
+read as "the policy passed".
+
+The same rule applies one step earlier, where it is knowable at mount time: a
+mount whose audience admits `public` and whose policy is narrower than
+`allowAll` is **refused at mount time**. That declaration is contradictory — it
+admits anonymous callers, who carry no user for the restriction to be evaluated
+against — and the alternative is for it to resolve silently in the permissive
+direction. Narrow the audience, or say `allowAll` and mean it.
+
+**Gate 2 — the read-policy hook.** Envelope in, allow or deny out, applied to
+every row and every `get` the mount serves. The default is
+`allowAnyAuthenticated`: any non-anonymous, non-disabled principal reads
+everything, and an agent counts as the principal it acts for. What replaces it
+is the consuming app's design. A hook receives the viewer as given, so an agent
+run arrives as kind `agent`; read `principalOnBehalfOf(viewer.principal)` to
+judge by whom it acts for.
+
+A hook that **throws** is not a denial. It propagates: a policy that cannot
+decide has not decided, and turning that into "deny" would render an outage as a
+silently empty page.
+
+### Deny means absence
+
+A denied `get` answers `not_found`. A denied row is simply not in its page. The
+two are indistinguishable on purpose: a `forbidden` on a specific id confirms
+that the id exists, which is the leak the policy was installed to close.
+
+Indistinguishable means **byte-identical**, not merely same-code. The denial's
+message is built from the same default a record door's own `not_found` uses
+(`` `${code}: ${JSON.stringify(detail)}` ``) rather than written out here.
+Matching on `detail` alone is not enough: a denial that said `not_found: <id>`
+against a door whose absence says `not_found: {"id":"<id>"}` differs in the
+half most likely to reach a log, a toast or an error page, and one probe per id
+is an existence oracle again.
+
+### A filtered page is a shorter page
+
+Filtering shrinks a page. A `limit: 50` list whose viewer may read twelve of
+them returns twelve rows **and the page's own cursor**. The cursor is still
+correct — it is the door's keyset position, not a count — so a consumer that
+needs full pages loops until it has enough. This is stated rather than hidden
+because a shrinking page is exactly what a row policy costs.
+
+The hook is asked about a page at bounded concurrency (`readPolicyConcurrency`,
+default 16), because a hook is expected to read app tables and a page may carry
+a thousand rows. Order is preserved regardless of completion order.
+
+### `count` and `materialize` are fail-closed
+
+Neither can be filtered by a per-envelope hook, for different reasons. `count`
+is folded inside the door and returns totals, not records: filtering it would
+mean counting client-side over the whole namespace, and serving it unfiltered
+discloses the shape of a corpus the viewer may not read. `materialize` streams
+stored bytes — whole files, several records to a file in some forms — so there
+is no envelope for the hook to judge at all.
+
+So both are gated, and **the gate arms on a pair, decided once at mount time:
+can the effective read policy deny a viewer this mount's audience admits?**
+Armed, they refuse `forbidden` unless the mount declares them:
+
+```ts
+unfilteredReads: ["materialize"]   // this mount folds whole pages, deliberately
+```
+
+| Mount | Deniable admitted viewer? | Gate |
+|---|---|---|
+| `{signed-in, allowAnyAuthenticated}` (the default) | no — the audience admits only authenticated viewers, and the default allows all of them | **unarmed**, both verbs flow |
+| `{public, allowAll}` with the default read policy | yes — public principals are admitted, and the default denies them | **armed** |
+| `{["public","signed-in"], …}` with the default | yes — the public class is still admitted | **armed** |
+| any policy this package cannot see inside | assumed yes | **armed** |
+| `denyAllRecords` | yes, on every audience | **armed** |
+
+Both halves of the pair matter. Arming only on "is there a custom policy?"
+fails **open** — the default denies public principals, so a public-audience
+mount served an anonymous caller the totals and the bytes while `list` served
+that same caller nothing. Arming on "can this policy deny anybody?" fails
+**noisy** — the default denies *some* principal, so every mount would arm and
+`unfilteredReads` would become mandatory boilerplate instead of a signal.
+
+A policy this package did not write is always armed, wrapper or not. That is
+deliberate: being unrecognised is never the permissive answer, which is why
+`readPolicy: (i) => allowAnyAuthenticated(i)` arms even though it behaves
+exactly like the default. Erring toward a declaration is the safe direction.
+
+`unguardedDoor` remains the general escape hatch for a caller that wants the
+client with no gate at all and is willing to say so at the call site.
+
+### A paged `materialize` is not a snapshot
+
+The cursor is a position in a deterministic order, not a point in time. A
+multi-page walk taken while writes land under the same prefix can repeat an
+entry or miss one. Walk a quiesced namespace when that matters.
+
+## The body composer
+
+The door takes **bytes, not fields** — it parses a record's envelope out of the
+body it is handed, which is what makes a record immutable and its digest
+meaningful. So a filing surface needs a composer, and without one every form
+field is a string concatenation.
+
+This one is generic over consumer-supplied family descriptors. No family, no
+field name and no id prefix is hardcoded anywhere in this package; the
+consumer's schema domain stays the consumer's. What the package owns is the
+**dialect** and the discipline around it:
+
+- Field order is the descriptor's, so the same fields always compose to the same
+  bytes and therefore the same digest.
+- Only declared fields may appear, and required ones must. An unknown input
+  field refuses rather than being dropped — a silently ignored field is a filing
+  that lies.
+- Four render forms only — `scalar`, `list`, `folded`, `map` — because the
+  reader on the other end is a minimal one. A value that cannot be rendered
+  unambiguously in that subset is **refused**, never escaped: a value that needs
+  escaping to survive is a value the far reader will get wrong.
+- **Composition self-checks.** Every composed body is parsed back with the
+  dialect's own reader and compared field by field before it is returned. The
+  canonical-bytes discipline is an assertion here, not a promise.
+- **The reader accepts a superset of what the writer emits**, deliberately. A
+  mount reads records other writers filed, so `parseRecordFrontmatter` tracks
+  the record substrate's own reader rather than this composer: inside a
+  one-level map a sub-value may itself fold (`  sub: >-`, or a bare `  sub:`,
+  followed by indented continuation lines rejoined with single spaces), and a
+  tab-led line counts as a continuation rather than as a new top-level key.
+  The composer emits neither form. Reading *less* than the substrate would
+  make the mount misread real records the substrate serves correctly — which
+  is a silent wrong answer, the one failure this package will not ship.
+
+Refusals arrive as `RecordDoorError` with the door's own `invalid_record` code,
+so a form handler has one error surface for "this filing is malformed" whether
+the composer caught it or the door did — and neither becomes a 500.
+
+### Writing: `by` is provenance, and the door checks it against the actor
+
+`mount.transition(...)` passes the caller's whole event through, `by` included.
+A door may guard that field: ours matches `by` against the provenance prefixes
+the *binding's actor* is allowed to stamp, and refuses `forbidden` when they
+disagree. So an app that stamps `by` from the signed-in user, while its binding
+carries some other actor, will meet a `forbidden` whose cause is not obvious
+from the call site.
+
+`by` is per-act provenance, never identity, and no consumer should build an
+authorization on it. Stamp it with something the binding's actor is entitled to
+claim, and keep the viewer's identity in the event's `fields` if the record
+should carry it.
+
+## Testing
+
+`@raybase/record-mount/testing` exports `createRecordDoorDouble()`, a
+contract-conformant in-memory door: the result envelope, the closed taxonomy,
+the Row projection, keyset paging, append idempotency by content, and the
+ordering rule that `forbidden` outranks `not_found`. It is generic — family, id
+shape, lifecycle vocabulary, grants and headline derivation are all hooks with
+documented defaults — and it lets a consuming app exercise its mount with no
+deployed Worker, no service binding and no network.
+
+**It is not the door.** Bytes the double accepts are not thereby proven
+acceptable to a deployed door: its frontmatter reader is this package's own, so
+a suite green against it is a builder-authored oracle for wire acceptance and
+nothing more. The real-door cross-check is a consumer-side act against a running
+service, and the double does not stand in for it.
+
+### The double presents as an RPC stub by default
+
+It used to hand back a plain object that simply omitted `append`/`transition`
+for a read door, and that cost a real defect: the production seam answers every
+property access with a callable, so every property-presence check read one way
+against the fixture and the other way against a deployed door. The suite was
+green on a shape that does not exist in production.
+
+So `createRecordDoorDouble()` now returns a **Proxy that answers every property
+with a function**, where calling a verb the door does not carry rejects with a
+`TypeError` imitating the runtime's method-missing shape — and the manners go
+one level down: a callable read off the stub answers *its* property accesses
+(`call`, `apply`, anything) with further method-missing callables, as the real
+proxy does, so an extracted-and-re-invoked verb fails in the fixture the same
+way it fails in production. The message shape (`does not implement` naming the
+method) is what the client's translation keys on; **do not pin the full
+sentence in a test** — workerd's wording is not ours to guarantee, and when it
+changes the client deliberately stops translating rather than guessing.
+
+```ts
+createRecordDoorDouble({ writable: false });                      // RPC read door, declares writes: false
+createRecordDoorDouble({ writable: false, declaredWrites: "omit" }); // an older door: declares nothing
+createRecordDoorDouble({ rpc: false });                           // a plain object, where absence is absence
+```
+
+Pass `rpc: false` when the thing you are standing in for really is an
+in-process implementation. Everything else should keep the default: a fixture
+kinder than the seam is a fixture that lies.
+
+Two more specifics worth knowing before you build on it. Its **`materialize` path
+layout (`family/id`) is invented** — a real door's tree is its substrate's, and
+is not that — so a prefix convention tested against the double is testing the
+double. And its **refusal messages are all one shape**, the error type's
+default; a real door authors bespoke prose at some sites, so match on `code` and
+`detail`, not on message text. The single exception is `not_found`, where the
+shapes genuinely agree and the agreement is load-bearing for deny-means-absence
+above.
+
+## Status
+
+Version 0.1.0. This repository's own suite runs against the in-memory double —
+a **Proxy in the test process** standing in for a Cloudflare service binding;
+nothing here reaches workerd.
+
+The real seam has now been walked by a consumer, though: as of 428c3a47
+(2026-08-31) the first consumer's topology suite drives every read and write
+verb of this client against a **deployed record door over a real service
+binding** — including doors that declare `version().writes` on both entrypoints
+— and runs green. That walkthrough is what surfaced (and now pins the fix for)
+the two real-seam defects the double alone could not see: writability read off
+stub property presence, and write verbs invoked via an extracted
+`Function.prototype.call` that the RPC proxy answers as a method named "call".
+The proof lives in the consumer's suite, not this one — this package's own
+tests remain a simulation, and the double is kept faithful to what the real
+seam has actually been observed to do. One deliberately open corner: whether a
+real stub answers `toString`/`valueOf` as RPC methods, as the double does, has
+not been observed; if the real seam differs, the double follows the seam.

package/dist/body.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The per-family body builder: filing from a form means composing a
+ * canonical record body, and this is the machinery that composes it.
+ *
+ * **It is generic over consumer-supplied family descriptors.** No family,
+ * no field name and no id prefix is hardcoded anywhere in this package —
+ * the consumer's schema domain stays the consumer's. What this module owns
+ * is the *dialect*: which frontmatter forms it will emit, deterministically,
+ * and which inputs it refuses rather than rendering ambiguously.
+ *
+ * ## The dialect, and why it is small
+ *
+ * A record body is frontmatter plus prose, and the parser on the other end
+ * is a minimal one — the record substrate parses the envelope out of the
+ * body itself, with a hand-written reader rather than a YAML library.
+ * Emitting the full YAML surface would produce bytes that round-trip
+ * through a real YAML parser and are silently misread by a minimal one, so
+ * this composer emits four forms only:
+ *
+ * - `scalar` — `key: value`
+ * - `list`   — `key: [a, b]`
+ * - `folded` — `key: >-` with two-space continuation lines, rejoined with
+ *              single spaces on read
+ * - `map`    — a bare `key:` with two-space `sub: value` lines
+ *
+ * and it **refuses** any value it cannot render unambiguously in that
+ * subset. A refusal is loud and typed; there is no escaping fallback,
+ * because a value that needs escaping to survive is a value the reader on
+ * the other end will get wrong.
+ *
+ * That list is the WRITE dialect, and the reader in this module is wider
+ * than it: a mount reads records other writers filed, so the reader tracks
+ * the record substrate's own reader (folded map sub-values, tab-led
+ * continuations) rather than this writer. See `parseRecordFrontmatter` —
+ * the asymmetry is deliberate and documented there.
+ *
+ * Keys are restricted to letters, `_` and `-` for the same reason: the
+ * minimal readers this dialect targets match keys with that charset and
+ * SKIP a line they do not match, which turns a key containing a digit into
+ * a silently dropped field. A refusal at compose time is the better
+ * failure.
+ *
+ * ## Refusals arrive in the door's own taxonomy
+ *
+ * A composition refusal throws `RecordDoorError` with code
+ * `invalid_record` — exactly what the door answers for a body it cannot
+ * accept. A form handler therefore has ONE error surface for "this filing
+ * is malformed", whether the composer caught it or the store did, and
+ * neither becomes a 500.
+ */
+/** How one field renders into the frontmatter block. */
+export type RecordFieldRender = "scalar" | "list" | "folded" | "map";
+export type RecordFieldDescriptor = {
+    /** The frontmatter key. Letters, `_` and `-` only. */
+    key: string;
+    /** The input key this field reads. Defaults to `key`. */
+    from?: string;
+    /** Default `"scalar"`. */
+    render?: RecordFieldRender;
+    /** A missing or empty required field refuses. */
+    required?: boolean;
+    /**
+     * A fixed value, written whatever the input says — the mechanical
+     * fields a family always carries (`type: finding`). An input that also
+     * supplies the key refuses, rather than one of the two silently winning.
+     */
+    constant?: string;
+};
+export type RecordFamilyDescriptor = {
+    /** The family name, as the consumer's schema domain spells it. */
+    family: string;
+    /** The fields, in the order they are written. Order is the bytes. */
+    fields: RecordFieldDescriptor[];
+    /**
+     * The input key carrying the markdown prose that follows the block.
+     * Omitted, the family files as frontmatter alone.
+     */
+    prose?: string;
+    /** Whether the prose must be present and non-empty. */
+    proseRequired?: boolean;
+    /**
+     * The id prefix this family's records carry, e.g. `"dec"`. Declared, the
+     * composer checks that the composed id matches the contract's id scheme
+     * AND carries this prefix — so a form that files a decision under a
+     * case's id is refused here rather than at the door.
+     *
+     * The prefix vocabulary is the consumer's; only the *scheme* is the
+     * contract's.
+     */
+    idPrefix?: string;
+    /** Which frontmatter key holds the id. Defaults to `"id"`. */
+    idKey?: string;
+};
+export type RecordBodyComposer = {
+    /** The families this composer knows, in declaration order. */
+    readonly families: readonly string[];
+    /** Compose one family's canonical body bytes from a form's input. */
+    compose(family: string, input: Record<string, unknown>): string;
+};
+/**
+ * The contract's id scheme: `<prefix>-<yyyy-mm-dd>-<slug>`, with an
+ * optional trailing ordinal that the slug charset already admits. The
+ * scheme belongs to the door, which refuses `invalid_id` on anything else;
+ * the *prefix vocabulary* belongs to the consumer, which is why a
+ * descriptor supplies the prefix and this pattern supplies the shape.
+ */
+export declare const RECORD_ID_PATTERN: RegExp;
+/** Mint an id under that scheme. Refuses rather than emitting one the door
+ *  would reject. */
+export declare function mintRecordId(input: {
+    prefix: string;
+    date: string;
+    slug: string;
+    ordinal?: number;
+}): string;
+/**
+ * Build a composer over the consumer's family descriptors.
+ *
+ * Descriptors are validated once, here, rather than at every filing: a
+ * malformed descriptor is a programming error and belongs at module load,
+ * not in a user's form submission.
+ */
+export declare function createRecordBodyComposer(descriptors: readonly RecordFamilyDescriptor[]): RecordBodyComposer;
+/**
+ * This package's frontmatter reader: `key: value`, `key: [a, b]`, `key: >-`
+ * folded blocks rejoined with single spaces, and one-level maps of two-space
+ * `sub: value` lines whose sub-values may THEMSELVES fold. Keys are letters,
+ * `_` and `-`; a line matching nothing is skipped, which is what minimal
+ * readers do and why the composer refuses to emit one.
+ *
+ * ## The reader accepts a superset of what the writer emits
+ *
+ * The reader is deliberately NOT the writer's mirror, and saying so plainly
+ * is the point of this paragraph. The composer's write dialect is the small,
+ * refusing one documented at the top of this module — it never emits a folded
+ * map sub-value, and it refuses any input it cannot render in its four forms.
+ * The reader, though, reads a corpus written by OTHER writers, and the record
+ * substrate's own reader accepts more than we emit. Reading less than the
+ * substrate does would make a mount unable to read real records the substrate
+ * happily serves, so the reader matches the substrate's reader instead:
+ *
+ * - inside an open map, `  sub: >-` **or** `  sub:` (an empty sub-value)
+ *   opens a folded sub-value; the following indented lines that are not
+ *   themselves two-space `sub: value` lines append, rejoined with single
+ *   spaces. A new two-space `sub: value` line closes the open fold; a
+ *   non-indented line closes the map;
+ * - a TAB-led line counts as indented, exactly as the substrate's reader
+ *   counts it — treating it as top-level would silently drop a continuation.
+ *
+ * Note the asymmetry is one-directional and safe in the direction that
+ * matters: every byte the composer emits still reads back to what it wrote
+ * (the round-trip assertion in `composeOne` is what enforces that), while
+ * bytes the composer would refuse to write may still be read.
+ *
+ * At top level `key:` (empty) opens a MAP, not a fold — the substrate does
+ * the same, and the `sub:`-opens-a-fold rule applies only INSIDE a map.
+ *
+ * It lives beside the writer on purpose. A dialect with its reader and its
+ * writer in two modules is a dialect with two definitions, and the drift
+ * shows up as bytes nobody can explain.
+ */
+export declare function parseRecordFrontmatter(text: string): Record<string, unknown>;
+/** The prose beneath a composed body's frontmatter block. */
+export declare function recordProseOf(text: string): string;
+//# sourceMappingURL=body.d.ts.map

package/dist/body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"body.d.ts","sourceRoot":"","sources":["../src/body.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,wDAAwD;AACxD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG;IAClC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0BAA0B;IAC1B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qEAAqE;IACrE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC;CACjE,CAAC;AAcF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAqD,CAAC;AAEpF;oBACoB;AACpB,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,MAAM,CAuBT;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,sBAAsB,EAAE,GAC7C,kBAAkB,CA2DpB;AAoJD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsE5E;AAED,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIlD"}