@ekka-ai/shelves 0.2.2 → 0.3.0

package/README.md

@@ -1,70 +1,172 @@
-# ekka-shelves
+# @ekka-ai/shelves
 
-`@ekka-ai/shelves`: the Business API side of EKKA shelves (E1, ekka-ai/.github#674).
+Serve an **EKKA shelf** from your own Fastify API.
 
-A Business API that wants to serve an EKKA shelf, for example `hr.salary`, scaffolds a typed class, fills the method body, registers one plugin, and runs `check`. The plugin mounts the shelf protocol v1: `ping`, `manifest` and `invoke` under `/ekka/shelves/v1/`.
+A shelf is a small, typed, read-only view of your data, for example `hr.salary`: one person's pay
+for one month. An EKKA customer's AI plans read a shelf through their own EKKA Enclave. It calls your
+API with a key you issued, asks for exactly the records the plan is allowed to read, and checks every
+record it gets back. This package gives your API the three endpoints that make that work, under
+`/ekka/shelves/v1/` (`ping`, `manifest`, `invoke`). It also gives you a CLI that scaffolds the shelf
+and then checks your API the way EKKA will.
 
-- A Business API installs `@ekka-ai/shelves` ALONE, from public npm. The shelf contracts it needs are bundled at build
-  (`dist/contracts/`, with `PINNED.json`: the contracts version and a sha256 per file); the full
-  `@ekka-ai/contracts` catalog is a devDependency and stays internal.
-- `v0.1.0`, `v0.2.0` and `v0.2.1` are tags that were never published; `0.2.2` is the first published version (CHANGELOG.md).
-- The shelf registry and the protocol are NOT defined here. They come from `@ekka-ai/contracts` (pinned), `shelves/registry.json` and `shelves/protocol-v1.schema.json`.
-- Spec: `codex-hub/ekka-memory-api-provider/E1-V3-SPEC.md`, section 6.
+Your code stays yours: you write the lookup from your data to the shelf's fields, and your auth
+decides who may call.
 
 ## Use it
 
+You need Node 22 or later, a Fastify 5 service, and TypeScript run through `tsx`. The example adds
+`hr.salary` (EKKA's predefined salary shelf) to a service that already has its own bearer-token auth.
+
+### 0. Install
+
+```sh
+npm i @ekka-ai/shelves
+npm i -D tsx            # the CLI loads your TypeScript shelf files through it
+```
+
+Run every command below from the service's root, with `npx ekka-shelves …` (the copy you just installed).
+
+### 1. Scaffold the shelf
+
 ```sh
-npx @ekka-ai/shelves add hr.salary                       # a predefined shelf: its shape is EKKA's registry
-npx @ekka-ai/shelves add communications.email \
-    --keys id:string:unique --fields id:string,subject:string,sent_on:date --verbs read
+npx ekka-shelves add hr.salary      # a predefined shelf: its keys and fields are EKKA's
+npx ekka-shelves add communications.email \
+    --keys id:string:unique --fields id:string,subject:string,sent_on:date --verbs read   # a private shelf of your own
 ```
 
-`add` writes `src/ekka/<id>.ts` (a class with empty typed methods), an empty role entry in
-`src/ekka/policy.ts` (the ONE place a provider role is written; an empty role refuses to start) and
-the shelf into `src/ekka/index.ts`. Fill the method bodies with your own code, then:
+`add` writes three files under `src/ekka/`:
+- `hr.salary.ts`: a class with empty typed methods and its fixtures;
+- `policy.ts`: an empty role per verb;
+- `index.ts`: your `provider` and the list of shelves.
+
+### 2. Fill in the three files
+
+- **`index.ts` › `provider.id`**: how EKKA names your service, in lowercase letters, digits and hyphens (for example `acme-payroll`). Keep `offerVersion` as it is until you change a shelf; then bump it.
+- **`policy.ts`**: a ROLE for each verb, one lowercase word (letters, digits, `_`), for example `payroll_reader`. A role is the name for "who may read this shelf". Your customer's EKKA admin maps it to their own roles when they import your service. An empty role refuses to start: it is a person's decision, never a default.
+- **`hr.salary.ts` › `read` and `list`**: your own code, from your own data to the shelf's fields. That code IS the mapping, and EKKA keeps no mapping table.
+- **The fixtures in `hr.salary.ts`** are the ONE record that `check` and EKKA's import probe ask for:
+  - The record must EXIST in your data. It must be a SYNTHETIC person, never a real one. The scaffold names `{ id: 'fixture-id', month: '2000-01' }`. Add that made-up row to every environment EKKA imports from, production included if EKKA imports from production (use currency `XTS`, the ISO code reserved for testing), or point both fixtures at a synthetic record you already have.
+  - The `list` fixture names the SAME record by every unique key. Never `{}`: it would match every row, and the probe would carry real records to EKKA. Startup refuses it, and `check` fails if listing the fixture returns any other record.
+
+### 3. Mount the plugin with YOUR auth
 
 ```ts
-await app.register(ekkaShelves({ provider, shelves, authenticate, authorize, capabilitiesOf, principalOf }));
+import { ekkaShelves } from '@ekka-ai/shelves';
+import { provider, shelves } from './ekka/index.js';
+
+await app.register(ekkaShelves({
+  provider,
+  shelves,
+  authenticate: requireUser,                       // your existing bearer check: sets who the caller is, or throws 401
+  authorize: (capability) => async (req) => {      // your capability guard: throw 403 if the caller lacks it
+    if (!req.user?.scopes.includes(capability)) throw Object.assign(new Error('forbidden'), { statusCode: 403 });
+  },
+  capabilitiesOf: (req) => req.user?.scopes ?? [], // the capabilities the caller holds
+  principalOf: (req) => req.user?.id ?? '',        // the caller's principal name
+}));
 ```
 
-`authenticate` and `authorize(capability)` are YOUR service's own bearer check and capability guard;
-the plugin never decides who a caller is.
+The plugin never decides who a caller is; your hooks do.
+
+### 4. One key per shelf: add the shelf's principal to your auth
 
 ```sh
-npx @ekka-ai/shelves generate [--check]   # src/ekka/shelves.generated.ts: capabilities, one principal per shelf, routes, the offer
-npx @ekka-ai/shelves check                # the real endpoint through src/ekka/check-app.ts; prints what EKKA will see
+npx ekka-shelves generate    # writes src/ekka/shelves.generated.ts; `generate --check` fails in CI when it is stale
 ```
 
-What is enforced, and tested (`test/`):
-- `read` takes EXACTLY the unique key set; `list` any subset of the declared keys. An undeclared key is
-  `unknown_key`, never ignored. `list` returns at most min(limit, page_cap), with `next_cursor`.
-- Every record leaving the service is checked against the shelf's exact field set and value types
-  (`month`, `date`, `currency_code`, `money_minor`, never a float); a bad one is `provider_error`, and
-  neither its values nor a thrown error's cause travel.
-- The manifest is authenticated and lists only the presenting principal's shelves; a shelf this key does
-  not serve and a shelf that does not exist get the same answer. Only `ping` is public.
-- A private shelf may never take a predefined id (at `add`, and at declaration).
-- `test/conformance.test.ts` checks everything served against the OFFICIAL `protocol-v1.schema.json`.
+For each shelf, your auth needs:
+- ONE principal, named `ekka-shelf-<shelf id>` (here `ekka-shelf-hr.salary`);
+- holding exactly ONE capability, `shelf.<shelf id>.read` (here `shelf.hr.salary.read`);
+- with its OWN key: a random secret of 32 bytes or more that your auth accepts as a bearer token, and nothing else.
+
+`shelves.generated.ts` lists these names (`SHELF_PRINCIPAL_CAPABILITIES`), so your auth table can import them instead of typing them. Keep the key where you keep your other service secrets. When your customer's admin imports your service into EKKA (`ekka shelf import <your https origin>`), they paste that key at a hidden prompt. EKKA keeps it in the customer's vault and presents it only to your origin.
+
+### 5. `check`: see what EKKA will see
+
+`check` calls your REAL app in-process. It needs one small file that you write, `src/ekka/check-app.ts`:
 
-## Develop
+```ts
+// src/ekka/check-app.ts: your app, built as production builds it, and a key for each shelf's principal.
+import { randomBytes } from 'node:crypto';
 
+export default async () => {
+  const key = randomBytes(32).toString('base64url');
+  // Make YOUR auth accept `key` as the principal ekka-shelf-hr.salary with capability shelf.hr.salary.read.
+  // For a token table read from the environment, set it BEFORE importing your app:
+  process.env.API_TOKENS = JSON.stringify({ [key]: { id: 'ekka-shelf-hr.salary', scopes: ['shelf.hr.salary.read'] } });
+  const { buildApp } = await import('../app.js');
+  const app = await buildApp();
+  await app.ready();
+  return { app, bearerFor: (_shelfId: string) => key };
+};
 ```
-pnpm install    # needs NODE_AUTH_TOKEN with read:packages for the org registry
-pnpm test
-pnpm run build
+
+```sh
+npx ekka-shelves check       # every line ok, or the line that is not, with what to change
 ```
 
-## Release
+### 6. Go live: how EKKA reaches your service
+
+- Deploy as usual. The shelf endpoints are served by your app, on your origin.
+- The origin EKKA is given must be a bare **https** origin, like `https://payroll-api.example.com`:
+  no path, no query, no user info. EKKA follows no redirects, and it caps the size of an answer.
+- A **public** address works as it is. A **private** address (on the customer's own network) works
+  only when the customer's admin imports with `--reach private`. `localhost` and `127.0.0.1` are
+  never reachable: the import refuses them on purpose. To try it on your laptop, use `check` (step 5).
+- The customer's EKKA admin imports your service with `ekka shelf import https://your-origin`. The
+  command:
+  1. calls `ping`;
+  2. shows the origin for them to confirm;
+  3. asks for each shelf's key (step 4) at a hidden prompt;
+  4. reads your manifest;
+  5. probes each shelf once with your fixture, and once with a key you do not declare, which must
+     be refused.
+
+  They then map your roles to their own roles.
+- Change a shelf later (a role, a fixture, a field)? Bump `offerVersion` in `src/ekka/index.ts`.
+  EKKA refuses a changed offer under the same version.
+
+**Real or synthetic data (the whole store).** If ALL of a shelf's rows are generated (a staging or
+demo store), say so in its class: `override readonly data = 'synthetic' as const`. The customer's
+admin then sees "synthetic" beside the shelf, and every signed receipt says so. Leave it unset for a
+system of record, even when you have added one synthetic fixture person to it: `data` is about the
+store, and the fixture is always synthetic.
+
+## A shelf of your own (a private shelf)
+
+When no EKKA shelf fits, declare your own shape:
+
+```sh
+npx ekka-shelves add acme.expense \
+  --keys id:integer:unique,employee_id:string \
+  --fields id:integer,employee_id:string,spent_on:date,currency:currency_code,amount_minor:money_minor,approved:boolean \
+  --verbs read,list
+```
+
+- **Read keys:** read by an identifier, never by a person's name: two people can share a name.
+- **Money:** an integer in the currency's minor unit (`money_minor`), always with a `currency_code`.
+  There are no floats anywhere.
+- **Types:** `string`, `integer`, `boolean`, `month` (YYYY-MM), `date` (YYYY-MM-DD), `currency_code`
+  (ISO 4217) and `money_minor`.
+- **Id:** a private id may not reuse one of EKKA's (`hr.salary` is EKKA's).
+
+EKKA's own reference provider is a service like this. It serves `hr.salary` and a private
+`reference.expense` (an integer id key, money in minor units), both from synthetic data. Its fixtures
+are `{ id: 'fixture-0001', month: '2000-01' }` and `{ id: 1 }`, and `check` passes all 33 checks on it.
+
+## What the plugin guarantees
+
+- `read` takes EXACTLY the shelf's unique keys. `list` takes any of its declared keys. A key the shelf
+  does not declare is refused (`unknown_key`), never ignored. `list` returns at most the page size
+  asked for, never more than the shelf's cap, and a `next_cursor`.
+- Every record leaving your service is checked against the shelf's exact fields and types. A bad one
+  becomes a `provider_error`, and neither its values nor your error's details leave your service.
+- `manifest` needs a key, and it lists only that key's shelves. A shelf that key does not serve, and
+  a shelf that does not exist, get the same answer. Only `ping` is public.
+- Startup refuses a shelf with no role, no fixture, or a list fixture that could match real records.
 
-- **Public npm, proprietary licence** (the owner's decision): `@ekka-ai/shelves` publishes to
-  registry.npmjs.org, under LICENSE ("Proprietary. Use permitted for EKKA customers
-  under their EKKA agreement; no redistribution"). Publish ONLY with `node scripts/publish.mjs` (the workflow does): it
-  asks npm where it would publish and refuses anything but registry.npmjs.org. `publishConfig.registry`
-  alone is not enough, because the `@ekka-ai:registry` line in .npmrc beats it (the v0.2.0 failure).
-  A bare `npm publish` or `pnpm publish` is refused by the prepublishOnly guard. `@ekka-ai/contracts` stays internal: it is a devDependency, and only its three shelf files
-  are bundled.
-- ⚠️ **The `NPM_TOKEN` secret EXPIRES ON 2026-11-29.** After that every publish fails at the npm
-  step. Renewing it is a publish blocker: the owner replaces the secret on this repo before then
-  (tracked on ekka-ai/.github#672).
+## Versions and license
 
-Bump `version` in `package.json` in a PR, merge it, then push the tag `v<version>` on that commit. The publish workflow refuses a tag that does not match the version.
+- `0.2.2` is the first published version.
+- Proprietary: use is permitted for EKKA customers under their EKKA agreement; no redistribution
+  (`LICENSE`).

package/dist/check.js

@@ -1,5 +1,5 @@
 /**
- * `npx @ekka-ai/shelves check` (E1 spec, section 6 P2): the real endpoint, the real fixtures, and what
+ * `npx @ekka-ai/shelves check`: the real endpoint, the real fixtures, and what
  * EKKA will see. The same command runs in CI.
  *
  * ⛔ IT TRUSTS NOTHING IT IS CHECKING. Every answer is re-checked here against the manifest the
@@ -89,6 +89,7 @@ export const runCheck = async (t) => {
             say(!!shape && !known, id, known ? `a private shelf may not reuse the predefined id ${id}` : 'a private shelf, with the shape it declares', shape?.fields.map((f) => f.name).join(', '));
         }
         say(m.probe_fixture.synthetic === true, id, 'its probe fixture is marked synthetic');
+        say(m.data === undefined || m.data === 'real' || m.data === 'synthetic', id, `its data is declared ${m.data ?? 'real (unset)'}`, m.data === 'synthetic' ? 'synthetic rows: an importer and the receipt will say so' : undefined);
         if (!shape)
             continue;
         const major = m.interface_major ?? 1;
@@ -96,7 +97,11 @@ export const runCheck = async (t) => {
         if (m.verbs.includes('read') && fx.read) {
             const hit = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'read', fx.read) });
             const rec = result(hit)?.['record'];
-            const bad = rec === undefined ? `no record (HTTP ${hit.status}${refusalCode(hit) ? `, ${refusalCode(hit)}` : ''})` : exactFields(shape, rec);
+            const bad = rec === undefined
+                ? result(hit)?.['not_found'] === true
+                    ? `no record for the read fixture ${JSON.stringify(fx.read)}: your data needs this ONE synthetic record (a made-up person is fine), or change \`fixtures.read\` in src/ekka/${id}.ts to a synthetic record you have`
+                    : `no record (HTTP ${hit.status}${refusalCode(hit) ? `, ${refusalCode(hit)}` : ''})`
+                : exactFields(shape, rec);
             say(!bad, id, 'read with the fixture returns one record, exactly the shelf\u2019s fields', bad || `EKKA sees: ${JSON.stringify(rec)}`);
             const missing = missingFrom(shape, fx.read);
             if (missing) {
@@ -129,6 +134,22 @@ export const runCheck = async (t) => {
                     : recBad
                         ? `record ${recBad[0]}: ${recBad[1]}`
                         : `EKKA sees ${records.length} record(s), next_cursor ${JSON.stringify(r?.['next_cursor'])}`);
+            // ⛔ ONLY THE FIXTURE ROW. A list fixture names one synthetic record by
+            // its unique keys; any other record here is a record the import probe would carry to EKKA. The
+            // detail names only unique-key values, never a record.
+            const lf = fx.list;
+            if (Array.isArray(records)) {
+                const pin = shape.keys.filter((k) => k.unique && k.name in lf).map((k) => k.name);
+                const keysOf = (x) => Object.fromEntries(pin.map((k) => [k, isObj(x) ? x[k] : undefined]));
+                const stray = pin.length ? records.findIndex((x) => pin.some((k) => !isObj(x) || x[k] !== lf[k])) : -1;
+                say(pin.length > 0 && records.length > 0 && stray < 0, id, 'list with the fixture returns ONLY the fixture row, never another record', pin.length === 0
+                    ? 'the list fixture names no unique key, so it could match real records'
+                    : records.length === 0
+                        ? `no record for ${JSON.stringify(fx.list)}: your data needs this synthetic record`
+                        : stray >= 0
+                            ? `record ${stray} is ${JSON.stringify(keysOf(records[stray]))}, not the fixture ${JSON.stringify(keysOf(lf))}: the import probe would carry it to EKKA`
+                            : `${records.length} record(s), all ${JSON.stringify(keysOf(lf))}`);
+            }
             const over = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'list', fx.list, { limit: Math.min(1000, shape.pageCap + 1) }) });
             const overRecords = result(over)?.['records'];
             say(over.status === 200 && Array.isArray(overRecords) && overRecords.length <= shape.pageCap, id, `list asked for more than its cap returns at most ${shape.pageCap} records`, `HTTP ${over.status}`);

package/dist/cli.js

@@ -20,19 +20,29 @@ const flag = (args, name) => {
         return args[i + 1];
     return args.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
 };
-const loadTs = async (file) => {
+const CHECK_APP_HELP = 'create it: its default export is `async () => ({ app, bearerFor })`, where `app` is your Fastify app built exactly as ' +
+    'production builds it (your auth included) and `bearerFor(shelfId)` returns a key your auth accepts for the principal ' +
+    '`ekka-shelf-<shelfId>`. README › "5. check" has a complete example.';
+const loadTs = async (file, missing = 'run from the service root') => {
     const abs = resolve(file);
     if (!existsSync(abs))
-        throw new Error(`${file} does not exist (run from the service root)`);
+        throw new Error(`${file} does not exist (${missing})`);
+    let tsImport;
     try {
-        const { tsImport } = (await import('tsx/esm/api'));
-        return await tsImport(pathToFileURL(abs).href, import.meta.url);
+        ({ tsImport } = (await import('tsx/esm/api')));
     }
     catch (e) {
         if (e.code !== 'ERR_MODULE_NOT_FOUND')
             throw e;
-        return (await import(pathToFileURL(abs).href));
     }
+    if (tsImport)
+        return tsImport(pathToFileURL(abs).href, import.meta.url);
+    // Without tsx, Node cannot load TypeScript, and its own error ("Cannot find module …/x.js") hides why.
+    if (/\.[cm]?ts$/.test(abs)) {
+        throw new Error(`${file} is TypeScript and tsx is not installed where @ekka-ai/shelves can load it. In this service run: ` +
+            '`npm i @ekka-ai/shelves && npm i -D tsx`, then use `npx ekka-shelves …` (the local copy, not a one-off npx download).');
+    }
+    return (await import(pathToFileURL(abs).href));
 };
 const loadShelves = async (root) => {
     const m = await loadTs(resolve(root, 'src/ekka/index.ts'));
@@ -51,7 +61,16 @@ export const main = async (argv) => {
             throw new Error('usage: ekka-shelves add <id> [--keys … --fields … --verbs …]');
         const r = add({ root, id, keys: flag(args, 'keys'), fields: flag(args, 'fields'), verbs: flag(args, 'verbs') });
         process.stdout.write(`${r.isPrivate ? 'private' : 'predefined'} shelf ${id}\n${r.touched.map((f) => `  wrote ${f}`).join('\n')}\n`);
-        process.stdout.write('Next: fill the method bodies, the roles in src/ekka/policy.ts, then `ekka-shelves generate`.\n');
+        process.stdout.write([
+            'Next (README › "Use it"):',
+            '  1. install, if you have not: npm i @ekka-ai/shelves && npm i -D tsx',
+            "  2. src/ekka/index.ts: name this service in provider.id (lowercase letters, digits, hyphens)",
+            '  3. src/ekka/policy.ts: a role for each verb, one lowercase word, e.g. payroll_reader',
+            `  4. src/ekka/${id}.ts: fill read/list from your data; make the fixture record exist (a synthetic one)`,
+            '  5. mount ekkaShelves in your app; give your auth one principal and key per shelf (ekka-shelf-<id>)',
+            '  6. npx ekka-shelves generate, then write src/ekka/check-app.ts and run npx ekka-shelves check',
+            '',
+        ].join('\n'));
         return 0;
     }
     if (cmd === 'generate') {
@@ -73,7 +92,7 @@ export const main = async (argv) => {
     }
     if (cmd === 'check') {
         const { shelves } = await loadShelves(root);
-        const mod = await loadTs(resolve(root, flag(args, 'app') ?? 'src/ekka/check-app.ts'));
+        const mod = await loadTs(resolve(root, flag(args, 'app') ?? 'src/ekka/check-app.ts'), CHECK_APP_HELP);
         const { app, bearerFor } = await mod.default();
         const transport = async (req) => {
             const res = await app.inject({

package/dist/contracts/PINNED.json

@@ -1,8 +1,8 @@
 {
-  "contracts_version": "0.42.0",
+  "contracts_version": "0.43.1",
   "files": {
-    "shelves/registry.json": "bce1309515d952e9df42d79a3f2ca2ce908b3f2e1481ecbfe416c6016930573a",
-    "shelves/protocol-v1.schema.json": "53505506ea9ee9a163bf888c16d8d0c6470cc3377c9f72d8f3d9e6e108f20d1d",
-    "gate/attested/shelf.v1.json": "267e084fbc2e7cb16dd3c8c99fa9f7d4c460d43042304e689419544b80a1a91a"
+    "shelves/registry.json": "62d5214d5e36569595c6251501c1465efa6bead4ea7cea5836d5d9a1a4d6bbfa",
+    "shelves/protocol-v1.schema.json": "f791b722223f2359222b7230a19da93b58998a222dd1007284c2d858ae0e4aa7",
+    "gate/attested/shelf.v1.json": "eea0957687e78312bca5cc30f2c5bb02778702aa45184465bb76208b781b9641"
   }
 }

package/dist/contracts/gate/attested/shelf.v1.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.ekka.ai/gate/attested/shelf.v1.json",
   "title": "ShelfAttestedBody",
-  "description": "What the `shelf` gate declares as ATTESTABLE for one enforced shelf invocation (E1 v3.3; ekka-ai/.github#674). A fact reaches the signature only by being declared here; the signer canonicalizes and signs this object WHOLE and never reads a key inside it. CLOSED SHAPE ON PURPOSE: an unlisted key is refused rather than dropped. NO BODIES AND NO LOOKUP VALUES, EVER: a record is a company's data and `by` names a person, so only digests, counts and status appear. NO FLOATING-POINT NUMBERS: every numeric field is an integer.",
+  "description": "What the `shelf` gate declares as ATTESTABLE for one enforced shelf invocation. A fact reaches the signature only by being declared here; the signer canonicalizes and signs this object WHOLE and never reads a key inside it. CLOSED SHAPE ON PURPOSE: an unlisted key is refused rather than dropped. NO BODIES AND NO LOOKUP VALUES, EVER: a record is a company's data and `by` names a person, so only digests, counts and status appear. NO FLOATING-POINT NUMBERS: every numeric field is an integer.",
   "type": "object",
   "properties": {
     "op": {
@@ -18,7 +18,7 @@
       "minLength": 1,
       "maxLength": 512,
       "pattern": "^shelves/[a-z][a-z0-9_]{0,31}(\\.[a-z][a-z0-9_]{0,31})+$",
-      "description": "`shelves/<shelf_id>`, the canonical shelf string (owner rule 4)."
+      "description": "`shelves/<shelf_id>`, the canonical shelf string."
     },
     "offer_version": {
       "type": "string",
@@ -26,6 +26,14 @@
       "maxLength": 64,
       "description": "The provider offer version pinned for the run and echoed by the provider."
     },
+    "data": {
+      "type": "string",
+      "enum": [
+        "real",
+        "synthetic"
+      ],
+      "description": "Whether the data behind the shelf is `real` or `synthetic`, as the pinned offer declared it (shelves/protocol-v1.schema.json, manifest_shelf.data). Absent means real. Signed, so a receipt over a synthetic store can never be read as evidence about real people."
+    },
     "request_sha256_b64": {
       "type": "string",
       "minLength": 1,

package/dist/contracts/shelves/protocol-v1.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://schemas.ekka.ai/shelves/protocol-v1.schema.json",
   "title": "ShelfProtocolV1",
-  "description": "The shelf protocol v1 between an EKKA Enclave and a Business API (E1 v3.2, section 2; ekka-ai/.github#674). Three routes, mounted by the provider's `@ekka/shelves` plugin and nothing else: `GET /ekka/shelves/v1/ping` (public, answers `ping` below), `GET /ekka/shelves/v1/manifest` (bearer-authenticated, answers `manifest`), `POST /ekka/shelves/v1/invoke` (bearer-authenticated, takes `request`, answers `response`). The Enclave never learns another route, and a plan never supplies a URL, method or header. The bearer is the per-shelf principal key the provider issued; it is the provider's transport auth, not EKKA's authority. This file declares shapes; which definition a route uses is stated in each definition.",
+  "description": "The shelf protocol v1 between an EKKA Enclave and a Business API. Three routes, mounted by the provider's `@ekka/shelves` plugin and nothing else: `GET /ekka/shelves/v1/ping` (public, answers `ping` below), `GET /ekka/shelves/v1/manifest` (bearer-authenticated, answers `manifest`), `POST /ekka/shelves/v1/invoke` (bearer-authenticated, takes `request`, answers `response`). The Enclave never learns another route, and a plan never supplies a URL, method or header. The bearer is the per-shelf principal key the provider issued; it is the provider's transport auth, not EKKA's authority. This file declares shapes; which definition a route uses is stated in each definition.",
   "definitions": {
     "shelf_id": {
       "type": "string",
@@ -433,6 +433,14 @@
             "private"
           ]
         },
+        "data": {
+          "type": "string",
+          "enum": [
+            "real",
+            "synthetic"
+          ],
+          "description": "A FACT ABOUT THE DATA BEHIND THE SHELF, declared by the provider: `real` (a system of record) or `synthetic` (generated fixtures, e.g. a staging store). ABSENT MEANS REAL. An importer shows it beside the shelf, so nobody mistakes a synthetic store for company data, and the receipt carries it (gate/attested/shelf.v1.json `data`)."
+        },
         "interface_major": {
           "type": "integer",
           "minimum": 1,

package/dist/contracts/shelves/registry.json

@@ -1,5 +1,5 @@
 {
-  "description": "EKKA's predefined shelves (E1 v3.3; ekka-ai/.github#674). RULES EVERY SHELF HERE FOLLOWS: (1) A read key set is an IDENTIFIER set, never a human name. Names collide, so a read by name can return the wrong person's record; a name may be a field and a list filter, never a unique key. (2) Money is an integer count of minor units (`money_minor`) plus a currency code (`currency_code`, ISO 4217) on the same shelf, never a float. (3) Frozen once published: a breaking change is a new interface_major beside the old one, never an edit in place. (4) A private shelf a company declares may never reuse an id listed here.",
+  "description": "EKKA's predefined shelves. RULES EVERY SHELF HERE FOLLOWS: (1) A read key set is an IDENTIFIER set, never a human name. Names collide, so a read by name can return the wrong person's record; a name may be a field and a list filter, never a unique key. (2) Money is an integer count of minor units (`money_minor`) plus a currency code (`currency_code`, ISO 4217) on the same shelf, never a float. (3) Frozen once published: a breaking change is a new interface_major beside the old one, never an edit in place. (4) A private shelf a company declares may never reuse an id listed here.",
   "registry_version": 1,
   "categories": [
     {

package/dist/generate.js

@@ -1,23 +1,26 @@
 /**
  * THE GENERATOR: src/ekka/shelves.generated.ts, the one source for what the shelves add to the
- * Business API (E1 spec v3.4, section 6 P4).
+ * Business API.
  *
  * It writes the capability ids (`shelf.<id>.read`), ONE principal per shelf (`ekka-shelf-<id>`,
  * one key each) and the protocol routes with their prefix. The host's
  * capability table imports these instead of anyone typing them in three places.
  *
- * ⛔ NO EXPORTER ROWS, NO SURFACES (spec v3.4, section 13). A Business API's API-catalog exporter
+ * ⛔ NO EXPORTER ROWS, NO SURFACES. A Business API's API-catalog exporter
  * must never make a shelf route callable through the API gate: that would let a plan reach the
  * shelf around the shelf executor, its record check and its receipt. The host's exporter reads
  * SHELF_ROUTE_PREFIX to REFUSE any catalog rule that admits it.
  */
 import { buildOffer, capabilityOf, principalOf, ROUTES, SHELF_ROUTE_PREFIX } from './protocol.js';
 // ⛔ NO OFFER, NO DIGEST IN THIS FILE. The manifest is built at startup from the registered shelves
-// (spec P3), and a probe fixture can come from the service's configuration (a seeded synthetic
+// (the plugin does it), and a probe fixture can come from the service's configuration (a seeded synthetic
 // record), so a digest written here would disagree with the one served. One source: the startup.
 import { prepareShelves } from './plugin.js';
-export const GENERATED_HEADER = '// GENERATED by @ekka-ai/shelves (`npx @ekka-ai/shelves generate`). Do not edit: change the shelf classes or\n' +
-    '// src/ekka/policy.ts and generate again. `npx @ekka-ai/shelves generate --check` fails on drift (CI).\n';
+export const GENERATED_HEADER = '// GENERATED by @ekka-ai/shelves (`npx ekka-shelves generate`). Do not edit: change the shelf classes or\n' +
+    '// src/ekka/policy.ts and generate again. Run `npx ekka-shelves generate --check` in CI: it fails when this file is stale.\n' +
+    '//\n' +
+    '// What it is for: your auth and routing import these names instead of typing them. Give each principal\n' +
+    '// below its OWN key and exactly its capabilities (README, step 4).\n';
 const lit = (v) => JSON.stringify(v, null, 2);
 export const generate = (provider, shelves) => {
     prepareShelves(shelves); // refuses the same offers the plugin would refuse at startup
@@ -28,15 +31,16 @@ export const generate = (provider, shelves) => {
         GENERATED_HEADER,
         `export const SHELF_IDS = ${lit(ids)} as const;`,
         '',
-        '/** One capability per shelf; read and list both require it. */',
+        '/** The capability each shelf checks, one per shelf: read and list both require it. */',
         `export const SHELF_CAPABILITY_IDS = ${lit(ids.map(capabilityOf))} as const;`,
         '',
-        '/** One principal, so one key, per shelf. A key never reaches another shelf, or another shelf’s name. */',
+        '/** The principal EKKA calls as, one per shelf, so one key per shelf: a key never reaches another shelf. */',
         `export const SHELF_PRINCIPAL_IDS = ${lit(ids.map(principalOf))} as const;`,
         '',
+        '/** Principal → its capabilities: the entries to add to your auth table. */',
         `export const SHELF_PRINCIPAL_CAPABILITIES = ${lit(principalCaps)} as const;`,
         '',
-        '/** The protocol routes. The exporter REFUSES any API-catalog rule that admits one of them. */',
+        '/**\n * The routes the plugin mounts. Only EKKA\'s shelf protocol may reach them: if your service also publishes\n * its routes to EKKA as a plain API, leave everything under SHELF_ROUTE_PREFIX out of that list.\n */',
         `export const SHELF_ROUTES = ${lit(Object.values(ROUTES))} as const;`,
         `export const SHELF_ROUTE_PREFIX = ${lit(SHELF_ROUTE_PREFIX)};`,
         '',

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export declare function predefinedShelves(): {
     interface_major: number;
 }[];
 export { ekkaShelves, prepareShelves, type EkkaShelvesOptions } from './plugin.js';
-export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, verbProblems, type AnyShelf, type Fixtures, type ListResult, type Page, type RefusalCode, type Roles, type Row, type ShelfDescriptor, } from './shelf.js';
+export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, listFixtureProblems, verbProblems, DATA_KINDS, type AnyShelf, type DataKind, type Fixtures, type ListResult, type Page, type RefusalCode, type Roles, type Row, type ShelfDescriptor, } from './shelf.js';
 export { PROTOCOL, ROUTES, SHELF_ROUTE_PREFIX, buildOffer, manifestFor, canonicalJson, capabilityOf, principalOf, type Manifest, type ManifestShelf, type Offer, } from './protocol.js';
 export { loadRegistry, registrySource, parseRegistry, type Registry, type PredefinedShelf, type Verb, type FieldType } from './registry.js';
 export { generate, GENERATED_HEADER } from './generate.js';

package/dist/index.js

@@ -1,12 +1,12 @@
 /**
- * @ekka-ai/shelves: the Business API side of E1 (ekka-ai/.github#674, E1-V3-SPEC section 6).
+ * @ekka-ai/shelves: serve EKKA shelves from a Business API.
  *
- *   npx @ekka-ai/shelves add <id>     scaffold a typed shelf class (P1)
- *   npx @ekka-ai/shelves generate     write src/ekka/shelves.generated.ts (P4)
- *   npx @ekka-ai/shelves check        the real endpoint, the fixtures, what EKKA will see (P2)
- *   app.register(ekkaShelves({...}))  mount the shelf protocol v1 (P3)
+ *   npx @ekka-ai/shelves add <id>     scaffold a typed shelf class
+ *   npx @ekka-ai/shelves generate     write src/ekka/shelves.generated.ts
+ *   npx @ekka-ai/shelves check        the real endpoint, the fixtures, what EKKA will see
+ *   app.register(ekkaShelves({...}))  mount the shelf protocol v1
  *
- * The one source of truth is @ekka-ai/contracts (0.42.0): the shelf registry and protocol v1.
+ * The one source of truth is the pinned @ekka-ai/contracts: the shelf registry and protocol v1.
  */
 import { loadRegistry } from './registry.js';
 /** The predefined shelves, read from the pinned contracts package, never copied. */
@@ -14,7 +14,7 @@ export function predefinedShelves() {
     return [...loadRegistry().shelves.values()].map(({ id, interfaceMajor }) => ({ id, interface_major: interfaceMajor }));
 }
 export { ekkaShelves, prepareShelves } from './plugin.js';
-export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, verbProblems, } from './shelf.js';
+export { Shelf, ShelfRefusal, notImplemented, predefined, privateShelf, listFixtureProblems, verbProblems, DATA_KINDS, } from './shelf.js';
 export { PROTOCOL, ROUTES, SHELF_ROUTE_PREFIX, buildOffer, manifestFor, canonicalJson, capabilityOf, principalOf, } from './protocol.js';
 export { loadRegistry, registrySource, parseRegistry } from './registry.js';
 export { generate, GENERATED_HEADER } from './generate.js';

package/dist/plugin.d.ts

@@ -1,11 +1,11 @@
 /**
- * THE PLUGIN: one `register` mounts the shelf protocol on a Business API (E1 spec, section 6 P3).
+ * THE PLUGIN: one `register` mounts the shelf protocol on a Business API.
  *
  *   await app.register(ekkaShelves({ provider, shelves, authenticate, authorize, capabilitiesOf, run }));
  *
  * ⛔ THE HOST OWNS AUTHORITY. This package never decides who a caller is. `authenticate` is the
- * host's own bearer check (Trado: authenticatePrincipal + its org scope) and runs on every request
- * but ping, BEFORE the body is looked at. `authorize(capability)` is the host's own guard (Trado:
+ * host's own bearer check (for example its principal lookup and organization scope) and runs on every request
+ * but ping, BEFORE the body is looked at. `authorize(capability)` is the host's own guard (for example
  * requireCapability) and runs for the one shelf named in the body. A thrown error from either is
  * the host's answer; an authorize refusal is also mapped to the protocol's `forbidden`.
  *
@@ -24,7 +24,7 @@ export interface EkkaShelvesOptions {
     readonly shelves: readonly AnyShelf[];
     /** The host's bearer check. Throws its own 401 on a missing or unknown credential. */
     readonly authenticate: Hook;
-    /** The host's own capability guard for one capability, e.g. Trado's requireCapability. */
+    /** The host's own capability guard for one capability, e.g. a requireCapability middleware. */
     readonly authorize: (capability: string) => Hook;
     /** The capabilities of the principal `authenticate` found, read to filter the manifest. */
     readonly capabilitiesOf: (request: FastifyRequest) => readonly string[];

package/dist/protocol.d.ts

@@ -1,6 +1,6 @@
 import { Type } from 'typebox';
 import type { FieldType, ShelfShape, Verb } from './registry.js';
-import type { AnyShelf, RefusalCode, Row } from './shelf.js';
+import type { AnyShelf, DataKind, RefusalCode, Row } from './shelf.js';
 export declare const PROTOCOL: 1;
 export declare const ROUTES: {
     readonly ping: "/ekka/shelves/v1/ping";
@@ -78,6 +78,8 @@ export declare const sha256: (s: string) => string;
 export interface ManifestShelf {
     readonly id: string;
     readonly origin: 'predefined' | 'private';
+    /** Absent means real. */
+    readonly data?: DataKind;
     readonly interface_major?: number;
     readonly shape?: {
         readonly keys: readonly {
@@ -124,8 +126,8 @@ export declare const buildOffer: (provider: {
 }, shelves: readonly AnyShelf[]) => Offer;
 /** The manifest ONE principal is shown: only the shelves it serves, with the whole offer's digest. */
 export declare const manifestFor: (offer: Offer, principal: string, capabilities: readonly string[]) => Manifest;
-/** The capability a Business API checks for every verb of one shelf (spec P4). */
+/** The capability a Business API checks for every verb of one shelf. */
 export declare const capabilityOf: (shelfId: string) => string;
-/** One principal per shelf, so one key per shelf (spec P4; v3.2 section 12). */
+/** One principal per shelf, so one key per shelf. */
 export declare const principalOf: (shelfId: string) => string;
 export type { Row };

package/dist/protocol.js

@@ -1,5 +1,5 @@
 /**
- * THE SHELF PROTOCOL v1, as the Business API side sees it (E1 spec, section 2). The normative
+ * THE SHELF PROTOCOL v1, as the Business API side sees it. The normative
  * schema is `@ekka-ai/contracts/shelves/protocol-v1.schema.json`; the TypeBox schemas below mirror
  * it, and tests/conformance.test.ts checks what this package SERVES against the official file.
  *
@@ -128,6 +128,7 @@ export const manifestShelf = (s) => {
     return {
         id,
         origin: isPrivate ? 'private' : 'predefined',
+        ...(s.data ? { data: s.data } : {}),
         ...(isPrivate
             ? {
                 shape: {
@@ -160,7 +161,7 @@ export const manifestFor = (offer, principal, capabilities) => ({
     principal,
     shelves: offer.shelves.filter((s) => capabilities.includes(capabilityOf(s.id))),
 });
-/** The capability a Business API checks for every verb of one shelf (spec P4). */
+/** The capability a Business API checks for every verb of one shelf. */
 export const capabilityOf = (shelfId) => `shelf.${shelfId}.read`;
-/** One principal per shelf, so one key per shelf (spec P4; v3.2 section 12). */
+/** One principal per shelf, so one key per shelf. */
 export const principalOf = (shelfId) => `ekka-shelf-${shelfId}`;

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 export type FieldType = 'string' | 'integer' | 'boolean' | 'month' | 'date' | 'currency_code' | 'money_minor';
 export declare const FIELD_TYPES: readonly FieldType[];
-/** v1 ships these two; write, update, delete and send are protocol-reserved (spec section 2). */
+/** v1 ships these two; write, update, delete and send are reserved by the protocol. */
 export type Verb = 'read' | 'list';
 export declare const VERBS: readonly Verb[];
 export interface KeyDecl {

package/dist/registry.js

@@ -1,5 +1,5 @@
 /**
- * THE SHELF REGISTRY: EKKA's fixed vocabulary of predefined shelves (E1 spec, section 3 A1).
+ * THE SHELF REGISTRY: EKKA's fixed vocabulary of predefined shelves.
  *
  * ⛔ ONE SOURCE: `@ekka-ai/contracts/shelves/registry.json`, reviewed by PR in ekka-contracts. A
  * Business API never redefines a predefined shelf; this package only reads it.

package/dist/scaffold.d.ts

@@ -1,9 +1,9 @@
 import { type KeyDecl, type FieldDecl } from './registry.js';
 export declare const className: (id: string) => string;
 /** `id:string:unique,month:string:unique,name:string` */
-export declare const parseKeys: (spec: string) => KeyDecl[];
+export declare const parseKeys: (list: string) => KeyDecl[];
 /** `id:string,subject:string,sent_at:string?` (a trailing ? is optional) */
-export declare const parseFields: (spec: string) => FieldDecl[];
+export declare const parseFields: (list: string) => FieldDecl[];
 export interface AddOptions {
     readonly root: string;
     readonly id: string;

package/dist/scaffold.js

@@ -1,5 +1,5 @@
 /**
- * `npx @ekka-ai/shelves add <id> [--keys … --fields … --verbs …]` (E1 spec, section 6 P1).
+ * `npx @ekka-ai/shelves add <id> [--keys … --fields … --verbs …]`: scaffold a typed shelf class.
  *
  * Writes src/ekka/<id>.ts: a class with EMPTY typed methods. The person fills the method bodies with
  * their own code, which is the whole mapping from their data to the shelf.
@@ -7,7 +7,7 @@
  *   add hr.salary                                   a predefined shelf: its shape is EKKA's registry
  *   add communications.email --keys id:string:unique --fields id:string,subject:string,sent:boolean
  *
- * ⛔ A PRIVATE SHELF MAY NOT TAKE A PREDEFINED ID (owner rule 2), and a predefined shelf takes no
+ * ⛔ A PRIVATE SHELF MAY NOT TAKE A PREDEFINED ID (EKKA's registry owns those ids), and a predefined shelf takes no
  * --keys or --fields: its shape is EKKA's, not the company's.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -24,19 +24,19 @@ const parseType = (t, where) => {
     return t;
 };
 /** `id:string:unique,month:string:unique,name:string` */
-export const parseKeys = (spec) => spec.split(',').map((part) => {
+export const parseKeys = (list) => list.split(',').map((part) => {
     const [name, type, flag] = part.trim().split(':');
     if (!name)
-        throw new Error(`--keys: empty entry in "${spec}"`);
+        throw new Error(`--keys: empty entry in "${list}"`);
     return { name, type: parseType(type, `--keys ${name}`), unique: flag === 'unique' };
 });
 /** `id:string,subject:string,sent_at:string?` (a trailing ? is optional) */
-export const parseFields = (spec) => spec.split(',').map((part) => {
+export const parseFields = (list) => list.split(',').map((part) => {
     const p = part.trim();
     const optional = p.endsWith('?');
     const [name, type] = (optional ? p.slice(0, -1) : p).split(':');
     if (!name)
-        throw new Error(`--fields: empty entry in "${spec}"`);
+        throw new Error(`--fields: empty entry in "${list}"`);
     return { name, type: parseType(type, `--fields ${name}`), required: !optional };
 });
 /** Values nobody could mistake for real data: ISO 4217 reserves XTS for testing; year 2000 is not a pay month anyone reads. */
@@ -100,7 +100,8 @@ export const add = (o) => {
         verbs.includes('read')
             ? `    read: { by: { ${unique.map((k) => `${k.name}: ${fixtureValue(k)}`).join(', ')} } },`
             : '',
-        verbs.includes('list') ? '    list: { by: {} },' : '',
+        // The SAME synthetic record, by every unique key: never `{}`, which would match every real row.
+        verbs.includes('list') ? `    list: { by: { ${unique.map((k) => `${k.name}: ${fixtureValue(k)}`).join(', ')} } },` : '',
     ]
         .filter(Boolean)
         .join('\n');
@@ -134,6 +135,9 @@ ${recordType}
 
 export class ${C} extends Shelf<${C}By, ${C}Filter, ${C}Record> {
   readonly descriptor = ${descriptor};
+  // Uncomment when these rows are GENERATED (a staging or demo store), not a system of record: the
+  // manifest, the importer and the signed receipt then say "synthetic". Unset means real.
+  // override readonly data = 'synthetic' as const;
   readonly roles = policy['${o.id}'];
   readonly fixtures: Fixtures<${C}By, ${C}Filter> = {
 ${fixtures}

package/dist/shelf.d.ts

@@ -1,16 +1,16 @@
 /**
- * A SHELF, AS A BUSINESS API WRITES IT (E1 spec, section 6 P1).
+ * A SHELF, AS A BUSINESS API WRITES IT.
  *
  * `npx @ekka-ai/shelves add hr.salary` writes a class that extends `Shelf` with empty typed methods. The
  * company fills the method bodies with its own code: that code IS the mapping from its data to the
- * shelf, and EKKA keeps no mapping table (owner rule 3).
+ * shelf, and EKKA keeps no mapping table.
  *
  *   - A PREDEFINED shelf takes its keys, fields, verbs and page cap from EKKA's registry.
  *     `predefined('hr.salary')` refuses an id the registry does not define.
  *   - A PRIVATE shelf declares its shape in the file. `privateShelf(...)` refuses an id the registry
- *     DOES define (owner rule 2): a company may not publish its own `hr.salary`.
+ *     DOES define: a company may not publish its own `hr.salary`.
  *   - `roles` is read from ONE policy file, `src/ekka/policy.ts`: a provider role is written in
- *     exactly one place (spec v3.2, section 12).
+ *     exactly one place.
  */
 import { type FieldType, type ShelfShape, type Verb } from './registry.js';
 export type Scalar = string | number | boolean;
@@ -24,6 +24,9 @@ export interface ListResult<R extends Row> {
     /** Opaque to EKKA; null when this is the last page. Missing is a failed call, never "no more". */
     readonly nextCursor: string | null;
 }
+/** protocol-v1 manifest_shelf.data. */
+export type DataKind = 'real' | 'synthetic';
+export declare const DATA_KINDS: readonly DataKind[];
 /** The provider role each verb requires. Written in src/ekka/policy.ts, nowhere else. */
 export type Roles = Partial<Readonly<Record<Verb, string>>>;
 /**
@@ -75,11 +78,28 @@ export declare const notImplemented: (id: string, verb: Verb) => ShelfRefusal;
  */
 export declare abstract class Shelf<By extends Row = Row, Filter extends Partial<Row> = Partial<Row>, R extends Row = Row> {
     abstract readonly descriptor: ShelfDescriptor;
+    /**
+     * WHAT THE DATA BEHIND THIS SHELF IS (contracts 0.43.0, manifest_shelf.data): `'real'`, a system of
+     * record, or `'synthetic'`, generated fixtures such as a staging or demo store. Leave it unset for
+     * real data (absent means real). Set `'synthetic'` whenever the rows are made up: an importer shows
+     * it beside the shelf, and the signed receipt carries it, so a synthetic store is never read as
+     * evidence about real people.
+     */
+    readonly data?: DataKind;
     abstract readonly roles: Roles;
     abstract readonly fixtures: Fixtures<By, Filter>;
     read?(by: By): Promise<R | null>;
     list?(by: Filter, page: Page): Promise<ListResult<R>>;
 }
 export type AnyShelf = Shelf<any, any, any>;
+/**
+ * ⛔ THE LIST FIXTURE MUST NAME THE SYNTHETIC RECORD,, AND ONLY IT.
+ *
+ * `check` and the Enclave's import probe send it to a service holding real data. `{}` matches every
+ * row, and `{ month: '2000-01' }` matches every person paid that month, so either one could carry real
+ * records into the probe. So a list fixture names the fixture row by EVERY unique key, with the same
+ * values as the read fixture when there is one: then it can only ever match that one synthetic row.
+ */
+export declare const listFixtureProblems: (s: AnyShelf) => string[];
 /** What a verb needs before it may be served: a method, a role, and a fixture to probe it with. */
 export declare const verbProblems: (s: AnyShelf) => string[];

package/dist/shelf.js

@@ -1,18 +1,19 @@
 /**
- * A SHELF, AS A BUSINESS API WRITES IT (E1 spec, section 6 P1).
+ * A SHELF, AS A BUSINESS API WRITES IT.
  *
  * `npx @ekka-ai/shelves add hr.salary` writes a class that extends `Shelf` with empty typed methods. The
  * company fills the method bodies with its own code: that code IS the mapping from its data to the
- * shelf, and EKKA keeps no mapping table (owner rule 3).
+ * shelf, and EKKA keeps no mapping table.
  *
  *   - A PREDEFINED shelf takes its keys, fields, verbs and page cap from EKKA's registry.
  *     `predefined('hr.salary')` refuses an id the registry does not define.
  *   - A PRIVATE shelf declares its shape in the file. `privateShelf(...)` refuses an id the registry
- *     DOES define (owner rule 2): a company may not publish its own `hr.salary`.
+ *     DOES define: a company may not publish its own `hr.salary`.
  *   - `roles` is read from ONE policy file, `src/ekka/policy.ts`: a provider role is written in
- *     exactly one place (spec v3.2, section 12).
+ *     exactly one place.
  */
 import { assertShape, loadRegistry, SEGMENT } from './registry.js';
+export const DATA_KINDS = ['real', 'synthetic'];
 export const predefined = (id) => {
     const reg = loadRegistry();
     const shelf = reg.shelves.get(id);
@@ -47,11 +48,47 @@ export const notImplemented = (id, verb) => new ShelfRefusal('not_implemented',
  * of the declared keys, unique or not); `R` is one record, exactly the shelf's fields.
  */
 export class Shelf {
+    /**
+     * WHAT THE DATA BEHIND THIS SHELF IS (contracts 0.43.0, manifest_shelf.data): `'real'`, a system of
+     * record, or `'synthetic'`, generated fixtures such as a staging or demo store. Leave it unset for
+     * real data (absent means real). Set `'synthetic'` whenever the rows are made up: an importer shows
+     * it beside the shelf, and the signed receipt carries it, so a synthetic store is never read as
+     * evidence about real people.
+     */
+    data;
 }
+/**
+ * ⛔ THE LIST FIXTURE MUST NAME THE SYNTHETIC RECORD,, AND ONLY IT.
+ *
+ * `check` and the Enclave's import probe send it to a service holding real data. `{}` matches every
+ * row, and `{ month: '2000-01' }` matches every person paid that month, so either one could carry real
+ * records into the probe. So a list fixture names the fixture row by EVERY unique key, with the same
+ * values as the read fixture when there is one: then it can only ever match that one synthetic row.
+ */
+export const listFixtureProblems = (s) => {
+    const { id, shape } = s.descriptor;
+    const fl = s.fixtures.list?.by;
+    if (!shape.verbs.includes('list') || !fl)
+        return [];
+    const unique = shape.keys.filter((k) => k.unique).map((k) => k.name);
+    const example = `{ ${unique.map((k) => `${k}: …`).join(', ')} }`;
+    if (Object.keys(fl).length === 0) {
+        return [`${id} list fixture is empty ({}): it matches EVERY row, so \`check\` and the Enclave's import probe would list real records. Name the synthetic record by its unique keys: ${example}`];
+    }
+    const missing = unique.filter((k) => !(k in fl));
+    if (missing.length) {
+        return [`${id} list fixture must name the synthetic record by every unique key (${unique.join(', ')}); without ${missing.join(', ')} it can match real records. Use ${example}`];
+    }
+    const rd = s.fixtures.read?.by;
+    const differ = rd ? unique.filter((k) => rd[k] !== fl[k]) : [];
+    return differ.length ? [`${id} list and read fixtures must name the SAME synthetic record; they differ on ${differ.join(', ')}`] : [];
+};
 /** What a verb needs before it may be served: a method, a role, and a fixture to probe it with. */
 export const verbProblems = (s) => {
     const out = [];
     const { id, shape } = s.descriptor;
+    if (s.data !== undefined && !DATA_KINDS.includes(s.data))
+        out.push(`${id} data "${String(s.data)}" must be 'real' or 'synthetic' (or unset, which means real)`);
     for (const v of shape.verbs) {
         if (typeof s[v] !== 'function')
             out.push(`${id} serves "${v}" but the class has no ${v}() method`);
@@ -63,6 +100,7 @@ export const verbProblems = (s) => {
         if (!s.fixtures[v])
             out.push(`${id} "${v}" has no synthetic fixture, so it cannot be probed`);
     }
+    out.push(...listFixtureProblems(s));
     for (const v of ['read', 'list']) {
         if (!shape.verbs.includes(v) && typeof s[v] === 'function')
             out.push(`${id} has a ${v}() method but does not serve "${v}"`);

package/package.json

@@ -1,23 +1,25 @@
 {
   "name": "@ekka-ai/shelves",
-  "version": "0.2.2",
-  "description": "EKKA shelves for a Business API: scaffold a typed shelf class, check it, mount the shelf protocol v1 (E1, ekka-ai/.github#674)",
+  "version": "0.3.0",
+  "description": "Serve an EKKA shelf from your Fastify API: scaffold a typed shelf, mount the shelf protocol v1, and check it the way EKKA will",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "ekka-shelves": "dist/cli.js"
   },
   "files": [
     "dist/**/*",
     "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ekka-ai/ekka-shelves.git"
-  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -30,22 +32,24 @@
     "build": "tsc -p tsconfig.json && node scripts/bundle-contracts.mjs && chmod +x dist/cli.js",
     "typecheck": "tsc -p tsconfig.test.json",
     "test": "vitest run",
-    "prepublishOnly": "node scripts/publish-guard.mjs"
+    "prepublishOnly": "node scripts/publish-guard.mjs",
+    "example": "pnpm run build && tsx examples/reference-provider/src/server.ts",
+    "example:check": "pnpm run build && cd examples/reference-provider && node ../../dist/cli.js check"
   },
   "devDependencies": {
+    "@ekka-ai/contracts": "0.43.1",
     "@types/node": "^22.10.0",
-    "typescript": "^5.7.0",
-    "vitest": "^2.1.0",
-    "fastify": "5.12.5",
-    "typebox": "1.3.34",
     "ajv": "8.20.0",
+    "fastify": "5.12.5",
     "tsx": "4.23.15",
-    "@ekka-ai/contracts": "0.42.0"
+    "typebox": "1.3.34",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
   },
   "peerDependencies": {
     "fastify": "^5.0.0",
-    "typebox": "^1.3.0",
-    "tsx": "^4.0.0"
+    "tsx": "^4.0.0",
+    "typebox": "^1.3.0"
   },
   "peerDependenciesMeta": {
     "tsx": {

package/CHANGELOG.md

@@ -1,44 +0,0 @@
-# Changelog
-
-## 0.2.2 (the first published version)
-
-- FIXED: v0.2.1 reached the right registry and had no login for it (ENEEDAUTH). setup-node writes its
-  npmrc with no final newline, so the workflow's appended `//registry.npmjs.org/:_authToken` line was
-  glued onto the `@ekka-ai:registry=` line. The workflow now writes a leading newline, and
-  scripts/publish.mjs runs `npm whoami` against npmjs before publishing.
-- Same code as 0.2.0 otherwise.
-
-## 0.2.1 (tagged, NEVER published)
-
-`v0.2.1` exists as a tag on 43427af; its publish failed (ENEEDAUTH, above). Its registry fix stands:
-
-- FIXED: the publish went to the wrong registry. For a SCOPED package, the `@ekka-ai:registry` line in
-  .npmrc beats `publishConfig.registry`, so v0.2.0 was sent to GitHub Packages and refused (E401),
-  while the guard, which read publishConfig, printed "publish target: https://registry.npmjs.org".
-  Publishing now goes only through `scripts/publish.mjs`: it sets the scope's registry on the command
-  line, runs `npm publish --dry-run`, reads the target npm reports, and refuses anything but npmjs.
-  The prepublishOnly guard refuses any publish that did not come through it.
-- Same code as 0.2.0 otherwise.
-
-## 0.2.0 (tagged, NEVER published)
-
-`v0.2.0` exists as a tag on 16b7654. Its publish failed (E401 to GitHub Packages, above); nothing
-reached any registry. Do not re-run the 0.2.0 publish. What it contained:
-
-- The shelf contracts are BUNDLED at build (dist/contracts/, with PINNED.json: version and a sha256
-  per file): shelves/registry.json, shelves/protocol-v1.schema.json, gate/attested/shelf.v1.json from
-  @ekka-ai/contracts 0.42.0. A Business API installs this package alone; contracts is a
-  devDependency. An installed package reads only its bundled copy.
-- FIXED, fail-open: run through npm's bin symlink, the CLI compared the link to the file it points at,
-  ran nothing and exited 0, so `check` "passed" without checking. It now compares real paths;
-  test/cli.test.ts runs it through a symlink.
-- The publish guard read npm_config_registry, which under pnpm is the default registry, and refused
-  every publish. 0.2.0 made it read publishConfig.registry, which was also wrong (see 0.2.1).
-
-## 0.1.0 (tagged, NEVER published)
-
-`v0.1.0` exists as a tag on 8ed1293 but was never published: its publish run was refused by the
-publish guard above. That was fortunate: 0.1.0 carries the fail-open CLI. 0.2.1 is the first
-published version; do not re-run the 0.1.0 publish.
-
-- add, generate, check and the shelf plugin (ekka-ai/ekka-shelves#3, #4).