@ekka-ai/shelves 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# 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).

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 EKKA Inc. All rights reserved.
+
+Proprietary. Use permitted for EKKA customers under their EKKA agreement; no redistribution.
+
+This software may be installed and used only by an EKKA customer, and only to serve EKKA shelves
+from that customer's own services, as its EKKA agreement allows. It may not be copied, modified for
+redistribution, sublicensed, sold, or distributed, in whole or in part, except as that agreement
+permits. It is provided "as is", without warranty of any kind, except as that agreement provides.

package/README.md

@@ -0,0 +1,70 @@
+# ekka-shelves
+
+`@ekka-ai/shelves`: the Business API side of EKKA shelves (E1, ekka-ai/.github#674).
+
+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 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.
+
+## Use it
+
+```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
+```
+
+`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:
+
+```ts
+await app.register(ekkaShelves({ provider, shelves, authenticate, authorize, capabilitiesOf, principalOf }));
+```
+
+`authenticate` and `authorize(capability)` are YOUR service's own bearer check and capability guard;
+the plugin never decides who a caller is.
+
+```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
+```
+
+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`.
+
+## Develop
+
+```
+pnpm install    # needs NODE_AUTH_TOKEN with read:packages for the org registry
+pnpm test
+pnpm run build
+```
+
+## Release
+
+- **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).
+
+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.

package/dist/check.d.ts

@@ -0,0 +1,26 @@
+export interface Answer {
+    readonly status: number;
+    readonly json: unknown;
+}
+/** How check talks to the endpoint: fastify.inject in-process, or fetch against a URL. */
+export type Transport = (req: {
+    method: 'GET' | 'POST';
+    path: string;
+    bearer?: string;
+    body?: unknown;
+}) => Promise<Answer>;
+export interface CheckTarget {
+    readonly transport: Transport;
+    /** The bearer key of each shelf's principal. */
+    readonly bearerFor: (shelfId: string) => string;
+    /** The shelf ids this service should serve (from its own shelf list). */
+    readonly shelves: readonly string[];
+}
+export interface CheckLine {
+    readonly ok: boolean;
+    readonly shelf: string;
+    readonly what: string;
+    readonly detail?: string;
+}
+export declare const runCheck: (t: CheckTarget) => Promise<CheckLine[]>;
+export declare const formatCheck: (lines: readonly CheckLine[]) => string;

package/dist/check.js

@@ -0,0 +1,151 @@
+/**
+ * `npx @ekka-ai/shelves check` (E1 spec, section 6 P2): 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
+ * endpoint itself served, so a Business API that bypasses the plugin, or a plugin bug, is red here
+ * before an Enclave's import probe ever meets it. Red on: a record with the wrong field set, a
+ * missing not-found, a missing next cursor, an ACCEPTED undeclared key, a page over the cap, a
+ * manifest that shows another credential's shelves, a ping that says more than its version.
+ */
+import { capabilityOf, PROTOCOL, ROUTES } from './protocol.js';
+import { loadRegistry } from './registry.js';
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** A predefined shelf's shape is the REGISTRY's (the manifest carries only its major); a private one's is its own. */
+const shapeOf = (m) => {
+    if (m.origin === 'private')
+        return m.shape ? { keys: m.shape.keys, fields: m.shape.fields, pageCap: m.shape.page_cap } : undefined;
+    const known = loadRegistry().shelves.get(m.id);
+    return known && known.interfaceMajor === m.interface_major ? known : undefined;
+};
+const FORMAT = {
+    month: /^[0-9]{4}-(0[1-9]|1[0-2])$/,
+    date: /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$/,
+    currency_code: /^[A-Z]{3}$/,
+};
+const typeOk = (t, v) => t === 'integer' || t === 'money_minor'
+    ? Number.isSafeInteger(v)
+    : t === 'boolean'
+        ? typeof v === 'boolean'
+        : typeof v === 'string' && (!FORMAT[t] || FORMAT[t].test(v));
+const exactFields = (m, r) => {
+    if (!isObj(r))
+        return 'not an object';
+    const declared = m.fields.map((f) => f.name);
+    const extra = Object.keys(r).filter((k) => !declared.includes(k));
+    const missing = m.fields.filter((f) => f.required && !(f.name in r)).map((f) => f.name);
+    const wrong = m.fields
+        .filter((f) => f.name in r)
+        .filter((f) => !typeOk(f.type, r[f.name]))
+        .map((f) => f.name);
+    return [extra.length ? `extra: ${extra.join(',')}` : '', missing.length ? `missing: ${missing.join(',')}` : '', wrong.length ? `wrong type: ${wrong.join(',')}` : '']
+        .filter(Boolean)
+        .join('; ');
+};
+const refusalCode = (a) => isObj(a.json) && isObj(a.json['refusal']) && typeof a.json['refusal']['code'] === 'string' ? a.json['refusal']['code'] : undefined;
+const result = (a) => (isObj(a.json) && isObj(a.json['result']) ? a.json['result'] : undefined);
+let seq = 0;
+/** A well-formed assertion. v1 providers MAY verify it; `check` does not sign, so a verifying provider is run with verification off. */
+const CHECK_AUTH = { alg: 'ed25519', key_id: 'ekka-shelves-check', payload_b64: 'Y2hlY2s=', sig_b64: 'Y2hlY2s=' };
+const invoke = (shelf, major, verb, by, page) => ({
+    protocol: PROTOCOL,
+    request_id: `check-${++seq}`,
+    shelf,
+    interface_major: major,
+    verb,
+    by,
+    ...(page ? { page } : {}),
+    auth: CHECK_AUTH,
+});
+/** A key set that finds nothing: the first string unique key, changed to a value no fixture uses. */
+const missingFrom = (shape, by) => {
+    const k = shape.keys.find((x) => x.unique && x.type === 'string');
+    return k ? { ...by, [k.name]: `ekka-check-missing-${k.name}` } : undefined;
+};
+export const runCheck = async (t) => {
+    const lines = [];
+    const say = (ok, shelf, what, detail) => lines.push({ ok, shelf, what, ...(detail ? { detail } : {}) });
+    const reg = loadRegistry();
+    const ping = await t.transport({ method: 'GET', path: ROUTES.ping });
+    say(ping.status === 200 && isObj(ping.json) && Object.keys(ping.json).join() === 'protocol' && ping.json['protocol'] === PROTOCOL, '-', 'ping answers { protocol: 1 } and nothing else, with no credential', JSON.stringify(ping.json));
+    const anon = await t.transport({ method: 'GET', path: ROUTES.manifest });
+    say(anon.status === 401 || anon.status === 403, '-', 'the manifest refuses a caller with no credential', `HTTP ${anon.status}`);
+    for (const id of t.shelves) {
+        const bearer = t.bearerFor(id);
+        const man = await t.transport({ method: 'GET', path: ROUTES.manifest, bearer });
+        const listed = isObj(man.json) && Array.isArray(man.json['shelves']) ? man.json['shelves'] : [];
+        const m = listed.find((s) => s.id === id);
+        say(man.status === 200 && !!m, id, 'the manifest, with this shelf’s key, lists it', `HTTP ${man.status}`);
+        const others = listed.filter((s) => s.id !== id).map((s) => s.id);
+        say(others.length === 0, id, 'the manifest shows this key no other shelf', others.join(', ') || undefined);
+        if (!m)
+            continue;
+        const shape = shapeOf(m);
+        const known = reg.shelves.get(id);
+        if (m.origin === 'predefined') {
+            say(!!shape && !!known, id, known ? `served as EKKA\u2019s ${id}@${known.interfaceMajor} (registry ${reg.version})` : `${id} is not in the registry`, `interface_major ${String(m.interface_major)}`);
+        }
+        else {
+            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');
+        if (!shape)
+            continue;
+        const major = m.interface_major ?? 1;
+        const fx = m.probe_fixture;
+        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);
+            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) {
+                const miss = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'read', missing) });
+                say(result(miss)?.['not_found'] === true, id, 'read with a key that finds nothing says not_found', `HTTP ${miss.status}`);
+            }
+            const extra = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'read', { ...fx.read, ekka_check_undeclared: 'x' }) });
+            say(extra.status >= 400 && refusalCode(extra) === 'unknown_key', id, 'read REFUSES an undeclared key (unknown_key), never ignores it', extra.status < 400 ? `ACCEPTED: HTTP ${extra.status}` : `${refusalCode(extra)}`);
+            const first = Object.keys(fx.read)[0];
+            if (first) {
+                const partial = Object.fromEntries(Object.entries(fx.read).filter(([k]) => k !== first));
+                const short = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'read', partial) });
+                say(short.status >= 400, id, `read refuses a key set without ${first} (it would not name one record)`, `HTTP ${short.status}`);
+            }
+            const paged = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'read', fx.read, { limit: 1 }) });
+            say(paged.status >= 400 && refusalCode(paged) === 'shape', id, 'read refuses a page (a page is for list only)', `HTTP ${paged.status}`);
+            const wrongMajor = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major + 1, 'read', fx.read) });
+            say(wrongMajor.status >= 400, id, `read refuses interface ${major + 1} (it serves ${major})`, `HTTP ${wrongMajor.status}`);
+        }
+        if (m.verbs.includes('list') && fx.list) {
+            const page = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'list', fx.list, { limit: shape.pageCap }) });
+            const r = result(page);
+            const records = r?.['records'];
+            const cursorOk = !!r && 'next_cursor' in r && (typeof r['next_cursor'] === 'string' || r['next_cursor'] === null);
+            const recBad = Array.isArray(records) ? records.map((x, i) => [i, exactFields(shape, x)]).find(([, p]) => p) : undefined;
+            say(Array.isArray(records) && cursorOk && !recBad && records.length <= shape.pageCap, id, 'list with the fixture returns records and a next cursor, every record exactly the shelf\u2019s fields', !Array.isArray(records)
+                ? `no records (HTTP ${page.status}${refusalCode(page) ? `, ${refusalCode(page)}` : ''})`
+                : !cursorOk
+                    ? 'no next_cursor'
+                    : recBad
+                        ? `record ${recBad[0]}: ${recBad[1]}`
+                        : `EKKA sees ${records.length} record(s), next_cursor ${JSON.stringify(r?.['next_cursor'])}`);
+            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}`);
+            const extra = await t.transport({ method: 'POST', path: ROUTES.invoke, bearer, body: invoke(id, major, 'list', { ...fx.list, ekka_check_undeclared: 'x' }) });
+            say(extra.status >= 400 && refusalCode(extra) === 'unknown_key', id, 'list REFUSES an undeclared key', extra.status < 400 ? `ACCEPTED: HTTP ${extra.status}` : `${refusalCode(extra)}`);
+        }
+        // Another shelf's key must not reach this one: one key per shelf is the point.
+        for (const other of t.shelves.filter((o) => o !== id)) {
+            const cross = await t.transport({
+                method: 'POST',
+                path: ROUTES.invoke,
+                bearer: t.bearerFor(other),
+                body: invoke(id, m.interface_major ?? 1, m.verbs[0] ?? 'read', m.probe_fixture.read ?? m.probe_fixture.list ?? {}),
+            });
+            say(cross.status === 403 && refusalCode(cross) === 'forbidden', id, `the ${other} key is refused here (${capabilityOf(id)} is not its capability)`, `HTTP ${cross.status}`);
+        }
+    }
+    return lines;
+};
+export const formatCheck = (lines) => lines.map((l) => `  ${l.ok ? 'ok  ' : 'FAIL'} ${l.shelf === '-' ? '' : `${l.shelf}: `}${l.what}${l.detail ? `\n         ${l.detail}` : ''}`).join('\n');

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare const main: (argv: string[]) => Promise<number>;

package/dist/cli.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/**
+ * npx @ekka-ai/shelves add <id> [--keys … --fields … --verbs …]
+ * npx @ekka-ai/shelves generate [--check]
+ * npx @ekka-ai/shelves check [--app src/ekka/check-app.ts]
+ *
+ * Run from the Business API's root. `generate` and `check` read src/ekka/index.ts (TypeScript, loaded
+ * through tsx, which the service already has); `check --app` names a module whose default export is
+ * `async () => ({ app, bearerFor })`, with `app` a Fastify instance built as it runs in production.
+ */
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { formatCheck, runCheck } from './check.js';
+import { generate } from './generate.js';
+import { add } from './scaffold.js';
+const flag = (args, name) => {
+    const i = args.indexOf(`--${name}`);
+    if (i >= 0)
+        return args[i + 1];
+    return args.find((a) => a.startsWith(`--${name}=`))?.slice(name.length + 3);
+};
+const loadTs = async (file) => {
+    const abs = resolve(file);
+    if (!existsSync(abs))
+        throw new Error(`${file} does not exist (run from the service root)`);
+    try {
+        const { tsImport } = (await import('tsx/esm/api'));
+        return await tsImport(pathToFileURL(abs).href, import.meta.url);
+    }
+    catch (e) {
+        if (e.code !== 'ERR_MODULE_NOT_FOUND')
+            throw e;
+        return (await import(pathToFileURL(abs).href));
+    }
+};
+const loadShelves = async (root) => {
+    const m = await loadTs(resolve(root, 'src/ekka/index.ts'));
+    if (!m.provider?.id)
+        throw new Error('src/ekka/index.ts: provider.id is empty; name this service (it is how EKKA shows it at import)');
+    if (!m.shelves?.length)
+        throw new Error('src/ekka/index.ts: no shelves');
+    return { provider: m.provider, shelves: m.shelves };
+};
+export const main = async (argv) => {
+    const [cmd, ...args] = argv;
+    const root = process.cwd();
+    if (cmd === 'add') {
+        const id = args.find((a) => !a.startsWith('--') && !args[args.indexOf(a) - 1]?.startsWith('--'));
+        if (!id)
+            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');
+        return 0;
+    }
+    if (cmd === 'generate') {
+        const { provider, shelves } = await loadShelves(root);
+        const out = resolve(root, flag(args, 'out') ?? 'src/ekka/shelves.generated.ts');
+        const text = generate(provider, shelves);
+        if (args.includes('--check')) {
+            const now = existsSync(out) ? readFileSync(out, 'utf8') : '';
+            if (now !== text) {
+                process.stderr.write(`${out} is out of date: run \`npx @ekka-ai/shelves generate\` and commit it.\n`);
+                return 1;
+            }
+            process.stdout.write('no drift: the generated shelf ids match the code\n');
+            return 0;
+        }
+        writeFileSync(out, text);
+        process.stdout.write(`wrote ${out}\n`);
+        return 0;
+    }
+    if (cmd === 'check') {
+        const { shelves } = await loadShelves(root);
+        const mod = await loadTs(resolve(root, flag(args, 'app') ?? 'src/ekka/check-app.ts'));
+        const { app, bearerFor } = await mod.default();
+        const transport = async (req) => {
+            const res = await app.inject({
+                method: req.method,
+                url: req.path,
+                headers: req.bearer ? { authorization: `Bearer ${req.bearer}` } : {},
+                ...(req.body !== undefined ? { payload: req.body } : {}),
+            });
+            let json = null;
+            try {
+                json = JSON.parse(res.body);
+            }
+            catch {
+                json = res.body;
+            }
+            return { status: res.statusCode, json };
+        };
+        const lines = await runCheck({ transport, bearerFor, shelves: shelves.map((s) => s.descriptor.id) });
+        await app.close();
+        process.stdout.write(`${formatCheck(lines)}\n`);
+        const bad = lines.filter((l) => !l.ok).length;
+        process.stdout.write(bad ? `\n${bad} check(s) FAILED\n` : `\nall ${lines.length} checks passed: this is what EKKA will see\n`);
+        return bad ? 1 : 0;
+    }
+    process.stderr.write('usage: ekka-shelves add <id> [--keys --fields --verbs] | generate [--check] | check [--app <module>]\n');
+    return 2;
+};
+// Run when invoked as the `ekka-shelves` binary, not when imported by a test.
+// ⛔ COMPARE REAL PATHS. npm runs a bin through a SYMLINK (node_modules/.bin/ekka-shelves), so
+// argv[1] is the link and import.meta.url the file it points at. Compared as given they never match,
+// main never ran, and the process exited 0: `check` "passed" in CI without checking anything.
+const invokedAsBinary = () => {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+};
+if (invokedAsBinary()) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`ekka-shelves: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/contracts/PINNED.json

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

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

@@ -0,0 +1,77 @@
+{
+  "$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.",
+  "type": "object",
+  "properties": {
+    "op": {
+      "type": "string",
+      "enum": [
+        "read",
+        "list"
+      ],
+      "description": "The verb performed."
+    },
+    "resource": {
+      "type": "string",
+      "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)."
+    },
+    "offer_version": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "The provider offer version pinned for the run and echoed by the provider."
+    },
+    "request_sha256_b64": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Base64 SHA-256 over the request body sent to the provider: proves what was asked without copying the lookup values."
+    },
+    "request_bytes": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "response_sha256_b64": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Base64 SHA-256 over the provider's response body: binds the receipt to exactly what came back."
+    },
+    "bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Size of the response body."
+    },
+    "count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Records returned: 0 or 1 for `read`, the page size for `list`."
+    },
+    "found": {
+      "type": "boolean",
+      "description": "`read` only: whether the record existed. Absent for `list`."
+    },
+    "http_status": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 599
+    },
+    "duration_ms": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "truncated": {
+      "type": "boolean",
+      "description": "Whether the response hit the Enclave's size ceiling, so a digest over a cut body never reads as one over the whole."
+    }
+  },
+  "required": [
+    "op",
+    "resource",
+    "offer_version"
+  ],
+  "additionalProperties": false
+}