@ekka-ai/shelves 0.2.2

package/dist/protocol.js

@@ -0,0 +1,166 @@
+/**
+ * THE SHELF PROTOCOL v1, as the Business API side sees it (E1 spec, section 2). 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.
+ *
+ *   POST /ekka/shelves/v1/invoke    request -> response (exactly one of result or refusal)
+ *   GET  /ekka/shelves/v1/manifest  bearer-authenticated; names only the presenting principal's shelves
+ *   GET  /ekka/shelves/v1/ping      the one public route: { protocol: 1 } and nothing else
+ *
+ * ⛔ EVERY OBJECT IS CLOSED (additionalProperties: false), and a record is checked against the shelf's
+ * EXACT field set on the way OUT, so a method that returns one field too many, or one too few, fails
+ * here rather than handing EKKA a record the plan was never consented to read.
+ */
+import { createHash } from 'node:crypto';
+import { Type } from 'typebox';
+import { Compile } from 'typebox/compile';
+import { SEGMENT, SHELF_ID } from './registry.js';
+export const PROTOCOL = 1;
+export const ROUTES = {
+    ping: '/ekka/shelves/v1/ping',
+    manifest: '/ekka/shelves/v1/manifest',
+    invoke: '/ekka/shelves/v1/invoke',
+};
+export const SHELF_ROUTE_PREFIX = '/ekka/shelves/';
+/** Protocol-reserved verbs: named so a caller gets `not_implemented`, not "no such verb". */
+export const RESERVED_VERBS = ['write', 'update', 'delete', 'send'];
+const SAFE = { minimum: -9007199254740991, maximum: 9007199254740991 };
+const scalar = Type.Union([Type.String({ maxLength: 1024 }), Type.Integer(SAFE), Type.Boolean()]);
+const b64 = (maxLength) => Type.String({ minLength: 1, maxLength, pattern: '^[A-Za-z0-9+/]+={0,2}$' });
+/** protocol-v1 `invocation_assertion`: the Enclave's signed invocation. v1 providers MAY verify it. */
+export const InvocationAssertion = Type.Object({ alg: Type.Literal('ed25519'), key_id: Type.String({ minLength: 1, maxLength: 128 }), payload_b64: b64(4096), sig_b64: b64(256) }, { additionalProperties: false });
+export const InvokeRequest = Type.Object({
+    protocol: Type.Literal(PROTOCOL),
+    request_id: Type.String({ minLength: 1, maxLength: 128 }),
+    shelf: Type.String({ maxLength: 200, pattern: SHELF_ID.source }),
+    interface_major: Type.Integer({ minimum: 1 }),
+    // Any verb word here, so a reserved verb gets `not_implemented` rather than a bare `shape`.
+    verb: Type.String({ minLength: 1, maxLength: 16 }),
+    by: Type.Record(Type.String({ pattern: SEGMENT.source }), scalar, { maxProperties: 16 }),
+    page: Type.Optional(Type.Object({ limit: Type.Integer({ minimum: 1, maximum: 1000 }), cursor: Type.Optional(Type.Union([Type.String({ maxLength: 1024 }), Type.Null()])) }, { additionalProperties: false })),
+    auth: InvocationAssertion,
+}, { additionalProperties: false });
+const checkRequest = Compile(InvokeRequest);
+export const isInvokeRequest = (v) => checkRequest.Check(v);
+/** The HTTP status for each typed refusal; the body always carries the refusal itself. */
+export const REFUSAL_STATUS = {
+    unknown_key: 400,
+    shape: 400,
+    forbidden: 403,
+    not_implemented: 501,
+    provider_error: 502,
+};
+/** protocol-v1 `refusal.message` is at most 500 characters, and never a record value. */
+export const refusalMessage = (m) => (m.length <= 500 ? m : `${m.slice(0, 497)}...`);
+/** The wire form of each value type (registry.schema `value_type`). */
+const typeSchema = (t) => {
+    switch (t) {
+        case 'string':
+            return Type.String({ maxLength: 4096 });
+        case 'integer':
+        case 'money_minor':
+            return Type.Integer(SAFE);
+        case 'boolean':
+            return Type.Boolean();
+        case 'month':
+            return Type.String({ pattern: '^[0-9]{4}-(0[1-9]|1[0-2])$' });
+        case 'date':
+            return Type.String({ pattern: '^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$' });
+        case 'currency_code':
+            return Type.String({ pattern: '^[A-Z]{3}$' });
+    }
+};
+export const compileShelf = (shape) => {
+    const unique = shape.keys.filter((k) => k.unique);
+    const readBy = Compile(Type.Object(Object.fromEntries(unique.map((k) => [k.name, typeSchema(k.type)])), { additionalProperties: false }));
+    const listBy = Compile(Type.Object(Object.fromEntries(shape.keys.map((k) => [k.name, Type.Optional(typeSchema(k.type))])), { additionalProperties: false }));
+    const record = Compile(Type.Object(Object.fromEntries(shape.fields.map((f) => [f.name, f.required ? typeSchema(f.type) : Type.Optional(typeSchema(f.type))])), { additionalProperties: false }));
+    return {
+        readKeys: unique.map((k) => k.name),
+        listKeys: shape.keys.map((k) => k.name),
+        readBy: (v) => readBy.Check(v),
+        listBy: (v) => listBy.Check(v),
+        record: (v) => record.Check(v),
+    };
+};
+/** Which names in `by` this verb does not accept. Non-empty means `unknown_key`, never a guess. */
+export const undeclaredKeys = (v, verb, by) => {
+    const allowed = verb === 'read' ? v.readKeys : v.listKeys;
+    return Object.keys(by).filter((k) => !allowed.includes(k));
+};
+/** Why a returned record is not a record of this shelf, in words, never with its values. */
+export const recordProblem = (shape, r) => {
+    if (typeof r !== 'object' || r === null || Array.isArray(r))
+        return 'not an object';
+    const names = Object.keys(r);
+    const declared = shape.fields.map((f) => f.name);
+    const extra = names.filter((n) => !declared.includes(n));
+    const missing = shape.fields.filter((f) => f.required && !names.includes(f.name)).map((f) => f.name);
+    if (extra.length)
+        return `fields not in the shelf: ${extra.join(', ')}`;
+    if (missing.length)
+        return `required fields missing: ${missing.join(', ')}`;
+    return 'a field has the wrong type or format';
+};
+/* ------------------------------------------------------------------ the manifest */
+/** Sorted keys, no whitespace (SECURITY.CANONICALIZE.V1 for integer-only JSON): same object, same bytes. */
+export const canonicalJson = (v) => {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(canonicalJson).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o)
+        .filter((k) => o[k] !== undefined)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`)
+        .join(',')}}`;
+};
+export const sha256 = (s) => `sha256:${createHash('sha256').update(s, 'utf8').digest('hex')}`;
+export const PROVIDER_ID = /^[a-z][a-z0-9-]{0,62}$/;
+export const manifestShelf = (s) => {
+    const { id, isPrivate, interfaceMajor, shape } = s.descriptor;
+    const probe = { synthetic: true };
+    if (s.fixtures.read)
+        probe.read = s.fixtures.read.by;
+    if (s.fixtures.list)
+        probe.list = s.fixtures.list.by;
+    return {
+        id,
+        origin: isPrivate ? 'private' : 'predefined',
+        ...(isPrivate
+            ? {
+                shape: {
+                    keys: shape.keys.map((k) => ({ name: k.name, type: k.type, unique: k.unique })),
+                    fields: shape.fields.map((f) => ({ name: f.name, type: f.type, required: f.required })),
+                    page_cap: shape.pageCap,
+                },
+            }
+            : { interface_major: interfaceMajor }),
+        verbs: [...shape.verbs],
+        required_role: { ...s.roles },
+        probe_fixture: probe,
+    };
+};
+export const buildOffer = (provider, shelves) => {
+    if (!PROVIDER_ID.test(provider.id))
+        throw new Error(`provider id "${provider.id}" must be lowercase letters, digits and hyphens`);
+    if (provider.offerVersion.length < 1 || provider.offerVersion.length > 64)
+        throw new Error('offer version must be 1 to 64 characters');
+    const entries = shelves.map(manifestShelf).sort((a, b) => a.id.localeCompare(b.id));
+    const digest = sha256(canonicalJson({ provider_id: provider.id, offer_version: provider.offerVersion, shelves: entries }));
+    return { provider_id: provider.id, offer_version: provider.offerVersion, digest, shelves: entries };
+};
+/** The manifest ONE principal is shown: only the shelves it serves, with the whole offer's digest. */
+export const manifestFor = (offer, principal, capabilities) => ({
+    protocol: PROTOCOL,
+    provider_id: offer.provider_id,
+    offer_version: offer.offer_version,
+    digest: offer.digest,
+    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). */
+export const capabilityOf = (shelfId) => `shelf.${shelfId}.read`;
+/** One principal per shelf, so one key per shelf (spec P4; v3.2 section 12). */
+export const principalOf = (shelfId) => `ekka-shelf-${shelfId}`;

package/dist/registry.d.ts

@@ -0,0 +1,46 @@
+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). */
+export type Verb = 'read' | 'list';
+export declare const VERBS: readonly Verb[];
+export interface KeyDecl {
+    readonly name: string;
+    readonly type: FieldType;
+    /** The unique keys, together, name exactly one record: `read` takes exactly this set. */
+    readonly unique: boolean;
+}
+export interface FieldDecl {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+}
+export interface ShelfShape {
+    readonly keys: readonly KeyDecl[];
+    readonly fields: readonly FieldDecl[];
+    readonly verbs: readonly Verb[];
+    readonly pageCap: number;
+}
+export interface PredefinedShelf extends ShelfShape {
+    readonly id: string;
+    readonly category: string;
+    readonly interfaceMajor: number;
+    readonly ownerRule: string;
+}
+export interface Registry {
+    readonly version: number;
+    readonly categories: readonly string[];
+    readonly shelves: ReadonlyMap<string, PredefinedShelf>;
+}
+/** Any shelf id on the wire (protocol-v1 `shelf_id`): lowercase dotted segments, 200 at most. */
+export declare const SHELF_ID: RegExp;
+/** A predefined id is exactly `<category>.<shelf>` (registry.schema `shelf_id`). */
+export declare const PREDEFINED_ID: RegExp;
+/** A key, a field, or a provider role name: one lowercase segment. */
+export declare const SEGMENT: RegExp;
+export declare const isShelfId: (id: string) => boolean;
+/** Validate one shape, wherever it came from: the registry or a private declaration. */
+export declare const assertShape: (id: string, shape: ShelfShape) => void;
+export declare const parseRegistry: (raw: unknown) => Registry;
+/** Where the registry is read from: the bundled copy when installed, the pinned devDependency in src/. */
+export declare const registrySource: (path?: string | undefined) => string;
+export declare const loadRegistry: (path?: string | undefined) => Registry;

package/dist/registry.js

@@ -0,0 +1,131 @@
+/**
+ * THE SHELF REGISTRY: EKKA's fixed vocabulary of predefined shelves (E1 spec, section 3 A1).
+ *
+ * ⛔ 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.
+ *
+ * ⛔ AN INSTALLED PACKAGE READS ONLY ITS BUNDLED COPY. `npm run build` copies the pinned file into
+ * dist/contracts/ (scripts/bundle-contracts.mjs, with PINNED.json), so a client installs this
+ * package alone and never needs the internal contracts catalog. A missing bundle is an error, never
+ * a silent fallback to whatever else is installed. Only when running from src/ (this repo's own
+ * tests) does it read the pinned devDependency. `EKKA_SHELF_REGISTRY` may name another copy of the
+ * same file (a test, or a newer registry being tried before its release).
+ *
+ * The rules every registry shelf follows are the registry's own: a read key set is an identifier set,
+ * never a human name; money is `money_minor` (an integer count of minor units) beside a
+ * `currency_code`; no floats anywhere, because canonical JSON is byte-deterministic only for integers.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+export const FIELD_TYPES = ['string', 'integer', 'boolean', 'month', 'date', 'currency_code', 'money_minor'];
+export const VERBS = ['read', 'list'];
+/** Any shelf id on the wire (protocol-v1 `shelf_id`): lowercase dotted segments, 200 at most. */
+export const SHELF_ID = /^[a-z][a-z0-9_]{0,31}(\.[a-z][a-z0-9_]{0,31})+$/;
+/** A predefined id is exactly `<category>.<shelf>` (registry.schema `shelf_id`). */
+export const PREDEFINED_ID = /^[a-z][a-z0-9_]{0,31}\.[a-z][a-z0-9_]{0,31}$/;
+/** A key, a field, or a provider role name: one lowercase segment. */
+export const SEGMENT = /^[a-z][a-z0-9_]{0,31}$/;
+const fail = (msg) => {
+    throw new Error(`shelf registry: ${msg}`);
+};
+export const isShelfId = (id) => id.length <= 200 && SHELF_ID.test(id);
+/** Validate one shape, wherever it came from: the registry or a private declaration. */
+export const assertShape = (id, shape) => {
+    if (!isShelfId(id))
+        fail(`"${id}" is not a shelf id (lowercase dotted segments, e.g. hr.salary)`);
+    if (shape.keys.length === 0 || shape.keys.length > 16)
+        fail(`${id} must declare 1 to 16 keys`);
+    if (!shape.keys.some((k) => k.unique))
+        fail(`${id} has no unique key, so "read" could not name one record`);
+    if (shape.fields.length === 0 || shape.fields.length > 64)
+        fail(`${id} must declare 1 to 64 fields`);
+    if (shape.verbs.length === 0)
+        fail(`${id} serves no verb`);
+    if (!Number.isInteger(shape.pageCap) || shape.pageCap < 1 || shape.pageCap > 1000)
+        fail(`${id} page cap must be 1 to 1000`);
+    const seen = new Set();
+    for (const f of shape.fields) {
+        if (!SEGMENT.test(f.name))
+            fail(`${id} field "${f.name}" is not a field name (one lowercase segment)`);
+        if (!FIELD_TYPES.includes(f.type))
+            fail(`${id} field "${f.name}" has type "${String(f.type)}" (${FIELD_TYPES.join(', ')}; never a float)`);
+        if (seen.has(f.name))
+            fail(`${id} declares field "${f.name}" twice`);
+        seen.add(f.name);
+    }
+    // Money without its currency is a number nobody can read correctly.
+    if (shape.fields.some((f) => f.type === 'money_minor') && !shape.fields.some((f) => f.type === 'currency_code')) {
+        fail(`${id} has a money_minor field but no currency_code field beside it`);
+    }
+    const keys = new Set();
+    for (const k of shape.keys) {
+        if (keys.has(k.name))
+            fail(`${id} declares key "${k.name}" twice`);
+        keys.add(k.name);
+        const field = shape.fields.find((f) => f.name === k.name);
+        // A key the record does not carry could not be checked against what came back.
+        if (!field)
+            fail(`${id} key "${k.name}" is not one of its fields`);
+        else if (field.type !== k.type)
+            fail(`${id} key "${k.name}" is ${k.type} but the field is ${field.type}`);
+    }
+    for (const v of shape.verbs)
+        if (!VERBS.includes(v))
+            fail(`${id} verb "${String(v)}" is not shipped in protocol v1`);
+};
+export const parseRegistry = (raw) => {
+    const r = raw;
+    if (!Number.isInteger(r.registry_version))
+        fail('registry_version is missing');
+    const categories = (r.categories ?? []).map((c) => c.id);
+    const shelves = new Map();
+    for (const s of r.shelves ?? []) {
+        if (shelves.has(s.id))
+            fail(`${s.id} is declared twice`);
+        if (!PREDEFINED_ID.test(s.id))
+            fail(`${s.id}: a predefined id is exactly <category>.<shelf>`);
+        if (!categories.includes(s.category))
+            fail(`${s.id} names category "${s.category}", which is not in the registry`);
+        if (!s.id.startsWith(`${s.category}.`))
+            fail(`${s.id} is not inside its category "${s.category}"`);
+        if (!Number.isInteger(s.interface_major) || s.interface_major < 1)
+            fail(`${s.id} interface_major must be a positive integer`);
+        const shelf = {
+            id: s.id,
+            category: s.category,
+            interfaceMajor: s.interface_major,
+            ownerRule: s.owner_rule,
+            keys: s.keys,
+            verbs: s.verbs,
+            fields: s.fields,
+            pageCap: s.page_cap,
+        };
+        assertShape(s.id, shelf);
+        shelves.set(s.id, shelf);
+    }
+    return { version: r.registry_version, categories, shelves };
+};
+let cached;
+let cachedFrom = '';
+/** Where the registry is read from: the bundled copy when installed, the pinned devDependency in src/. */
+export const registrySource = (path = process.env['EKKA_SHELF_REGISTRY']) => {
+    if (path)
+        return path;
+    const here = fileURLToPath(import.meta.url);
+    const bundled = fileURLToPath(new URL('./contracts/shelves/registry.json', import.meta.url));
+    if (existsSync(bundled))
+        return bundled;
+    if (/[\\/]src[\\/]registry\.ts$/.test(here))
+        return createRequire(import.meta.url).resolve('@ekka-ai/contracts/shelves/registry.json');
+    return fail(`the bundled registry is missing (${bundled}); this install of @ekka-ai/shelves is broken`);
+};
+export const loadRegistry = (path = process.env['EKKA_SHELF_REGISTRY']) => {
+    const file = registrySource(path);
+    if (cached && cachedFrom === file)
+        return cached;
+    const reg = parseRegistry(JSON.parse(readFileSync(file, 'utf8')));
+    cached = reg;
+    cachedFrom = file;
+    return reg;
+};

package/dist/scaffold.d.ts

@@ -0,0 +1,20 @@
+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[];
+/** `id:string,subject:string,sent_at:string?` (a trailing ? is optional) */
+export declare const parseFields: (spec: string) => FieldDecl[];
+export interface AddOptions {
+    readonly root: string;
+    readonly id: string;
+    readonly keys?: string;
+    readonly fields?: string;
+    readonly verbs?: string;
+    readonly pkg?: string;
+}
+export interface AddResult {
+    readonly file: string;
+    readonly isPrivate: boolean;
+    readonly touched: readonly string[];
+}
+export declare const add: (o: AddOptions) => AddResult;

package/dist/scaffold.js

@@ -0,0 +1,200 @@
+/**
+ * `npx @ekka-ai/shelves add <id> [--keys … --fields … --verbs …]` (E1 spec, section 6 P1).
+ *
+ * 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.
+ *
+ *   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
+ * --keys or --fields: its shape is EKKA's, not the company's.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { assertShape, FIELD_TYPES, isShelfId, loadRegistry, VERBS } from './registry.js';
+export const className = (id) => id
+    .split(/[._]/)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('');
+const tsType = (t) => (t === 'integer' || t === 'money_minor' ? 'number' : t === 'boolean' ? 'boolean' : 'string');
+const parseType = (t, where) => {
+    if (!t || !FIELD_TYPES.includes(t))
+        throw new Error(`${where}: type must be one of ${FIELD_TYPES.join(', ')} (no floats)`);
+    return t;
+};
+/** `id:string:unique,month:string:unique,name:string` */
+export const parseKeys = (spec) => spec.split(',').map((part) => {
+    const [name, type, flag] = part.trim().split(':');
+    if (!name)
+        throw new Error(`--keys: empty entry in "${spec}"`);
+    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) => {
+    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}"`);
+    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. */
+const fixtureValue = (k) => {
+    switch (k.type) {
+        case 'string':
+            return `'fixture-${k.name}'`;
+        case 'month':
+            return "'2000-01'";
+        case 'date':
+            return "'2000-01-01'";
+        case 'currency_code':
+            return "'XTS'";
+        case 'boolean':
+            return 'true';
+        default:
+            return '1';
+    }
+};
+export const add = (o) => {
+    const reg = loadRegistry();
+    const pkg = o.pkg ?? '@ekka-ai/shelves';
+    if (!isShelfId(o.id))
+        throw new Error(`"${o.id}" is not a shelf id: lowercase dotted segments, e.g. hr.salary`);
+    const known = reg.shelves.get(o.id);
+    const declares = o.keys !== undefined || o.fields !== undefined;
+    let shape;
+    if (known) {
+        if (declares) {
+            throw new Error(`"${o.id}" is a predefined EKKA shelf (registry ${reg.version}); its keys and fields are EKKA's. ` +
+                `A private shelf may not reuse a predefined id. Run: add ${o.id}  (no --keys, no --fields)`);
+        }
+        shape = known;
+    }
+    else {
+        if (!o.keys || !o.fields) {
+            throw new Error(`"${o.id}" is not a predefined shelf, so it is private: declare its shape with --keys and --fields`);
+        }
+        const verbs = (o.verbs ?? 'read,list').split(',').map((v) => v.trim());
+        for (const v of verbs)
+            if (!VERBS.includes(v))
+                throw new Error(`--verbs: "${v}" is not served in protocol v1 (${VERBS.join(', ')})`);
+        shape = { keys: parseKeys(o.keys), fields: parseFields(o.fields), verbs, pageCap: 100 };
+        assertShape(o.id, shape);
+    }
+    const dir = join(o.root, 'src', 'ekka');
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${o.id}.ts`);
+    if (existsSync(file))
+        throw new Error(`${file} already exists; nothing was changed`);
+    const C = className(o.id);
+    const unique = shape.keys.filter((k) => k.unique);
+    const verbs = shape.verbs;
+    const byType = `export type ${C}By = {\n${unique.map((k) => `  readonly ${k.name}: ${tsType(k.type)};`).join('\n')}\n};`;
+    const filterType = `export type ${C}Filter = {\n${shape.keys.map((k) => `  readonly ${k.name}?: ${tsType(k.type)};`).join('\n')}\n};`;
+    const recordType = `export type ${C}Record = {\n${shape.fields.map((f) => `  readonly ${f.name}${f.required ? '' : '?'}: ${tsType(f.type)};`).join('\n')}\n};`;
+    const descriptor = known
+        ? `predefined('${o.id}')`
+        : `privateShelf('${o.id}', {\n    keys: ${JSON.stringify(shape.keys)},\n    fields: ${JSON.stringify(shape.fields)},\n    verbs: ${JSON.stringify(shape.verbs)},\n  })`;
+    const fixtures = [
+        verbs.includes('read')
+            ? `    read: { by: { ${unique.map((k) => `${k.name}: ${fixtureValue(k)}`).join(', ')} } },`
+            : '',
+        verbs.includes('list') ? '    list: { by: {} },' : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    const methods = [
+        verbs.includes('read')
+            ? `  override async read(by: ${C}By): Promise<${C}Record | null> {\n    // Fill in: find the ONE record these keys name, in your own data; return null when there is none.\n    void by;\n    throw notImplemented('${o.id}', 'read');\n  }`
+            : '',
+        verbs.includes('list')
+            ? `  override async list(by: ${C}Filter, page: Page): Promise<ListResult<${C}Record>> {\n    // Fill in: at most page.limit records matching every key given; nextCursor is null on the last page.\n    void by;\n    void page;\n    throw notImplemented('${o.id}', 'list');\n  }`
+            : '',
+    ]
+        .filter(Boolean)
+        .join('\n\n');
+    const source = `/**
+ * ${o.id}${known ? `@${known.interfaceMajor}: an EKKA predefined shelf (registry ${reg.version}). Its keys and fields are EKKA's.` : ': a PRIVATE shelf of this company. Its shape is declared here.'}
+ *
+ * Fill the method bodies with this service's own code: that code is the mapping from your data to
+ * the shelf. The provider role each verb needs is written in ./policy.ts, and only there.
+ * The fixtures are SYNTHETIC: \`check\` and the Enclave's import probe send them, and the manifest
+ * carries them to EKKA marked synthetic. Never a real person.
+ */
+import { ${known ? 'predefined' : 'privateShelf'}, notImplemented, Shelf, type Fixtures, type ListResult, type Page } from '${pkg}';
+
+import { policy } from './policy.js';
+
+${byType}
+
+${filterType}
+
+${recordType}
+
+export class ${C} extends Shelf<${C}By, ${C}Filter, ${C}Record> {
+  readonly descriptor = ${descriptor};
+  readonly roles = policy['${o.id}'];
+  readonly fixtures: Fixtures<${C}By, ${C}Filter> = {
+${fixtures}
+  };
+
+${methods}
+}
+`;
+    writeFileSync(file, source);
+    const touched = [file, addToPolicy(dir, o.id, verbs), addToIndex(dir, o.id, C)];
+    return { file, isPrivate: !known, touched };
+};
+const POLICY_HEADER = `/**
+ * WHICH PROVIDER ROLE MAY SERVE WHICH SHELF VERB: the ONE place a provider role is written.
+ *
+ * An organization maps these roles to its own roles when it imports this service into EKKA. A verb
+ * with an empty role refuses to start: that decision is a person's, never a default.
+ */
+import type { Roles } from '@ekka-ai/shelves';
+
+export const policy = {
+  // @ekka-ai/shelves: entries
+} as const satisfies Record<string, Roles>;
+`;
+const addToPolicy = (dir, id, verbs) => {
+    const file = join(dir, 'policy.ts');
+    const src = existsSync(file) ? readFileSync(file, 'utf8') : POLICY_HEADER;
+    if (src.includes(`'${id}':`))
+        return file;
+    const marker = '  // @ekka-ai/shelves: entries';
+    if (!src.includes(marker))
+        throw new Error(`${file} has lost its "${marker.trim()}" line; add the entry for ${id} by hand`);
+    const entry = `  '${id}': { ${verbs.map((v) => `${v}: ''`).join(', ')} },`;
+    writeFileSync(file, src.replace(marker, `${entry}\n${marker}`));
+    return file;
+};
+const INDEX_HEADER = `/**
+ * The shelves this service serves. \`app.register(ekkaShelves({ provider, shelves, … }))\` mounts them;
+ * \`npx @ekka-ai/shelves generate\` and \`check\` read this file.
+ */
+import type { AnyShelf } from '@ekka-ai/shelves';
+// @ekka-ai/shelves: imports
+
+/** Who this service is to EKKA. offerVersion is immutable: change a shelf, bump it. */
+export const provider = { id: '', offerVersion: '1' } as const;
+
+export const shelves: readonly AnyShelf[] = [
+  // @ekka-ai/shelves: shelves
+];
+`;
+const addToIndex = (dir, id, C) => {
+    const file = join(dir, 'index.ts');
+    let src = existsSync(file) ? readFileSync(file, 'utf8') : INDEX_HEADER;
+    if (src.includes(`new ${C}()`))
+        return file;
+    for (const m of ['// @ekka-ai/shelves: imports', '  // @ekka-ai/shelves: shelves']) {
+        if (!src.includes(m))
+            throw new Error(`${file} has lost its "${m.trim()}" line; add ${C} by hand`);
+    }
+    src = src.replace('// @ekka-ai/shelves: imports', `import { ${C} } from './${id}.js';\n// @ekka-ai/shelves: imports`);
+    src = src.replace('  // @ekka-ai/shelves: shelves', `  new ${C}(),\n  // @ekka-ai/shelves: shelves`);
+    writeFileSync(file, src);
+    return file;
+};

package/dist/shelf.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A SHELF, AS A BUSINESS API WRITES IT (E1 spec, section 6 P1).
+ *
+ * `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).
+ *
+ *   - 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`.
+ *   - `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).
+ */
+import { type FieldType, type ShelfShape, type Verb } from './registry.js';
+export type Scalar = string | number | boolean;
+export type Row = Readonly<Record<string, Scalar>>;
+export interface Page {
+    readonly limit: number;
+    readonly cursor: string | null;
+}
+export interface ListResult<R extends Row> {
+    readonly records: readonly R[];
+    /** Opaque to EKKA; null when this is the last page. Missing is a failed call, never "no more". */
+    readonly nextCursor: string | null;
+}
+/** The provider role each verb requires. Written in src/ekka/policy.ts, nowhere else. */
+export type Roles = Partial<Readonly<Record<Verb, string>>>;
+/**
+ * SYNTHETIC inputs `check` and the Enclave's import probe send. Never real people: the manifest
+ * carries them to EKKA, marked `synthetic: true`.
+ */
+export interface Fixtures<By extends Row, Filter extends Partial<Row> = Partial<Row>> {
+    /** `by` must find a synthetic record. `check` derives a key that finds none from it. */
+    readonly read?: {
+        readonly by: By;
+    };
+    readonly list?: {
+        readonly by: Filter;
+    };
+}
+export interface ShelfDescriptor {
+    readonly id: string;
+    /** The EKKA interface major for a predefined shelf; null for a private one. */
+    readonly interfaceMajor: number | null;
+    readonly isPrivate: boolean;
+    readonly shape: ShelfShape;
+}
+export declare const predefined: (id: string) => ShelfDescriptor;
+export interface PrivateShapeInput {
+    readonly keys: readonly {
+        readonly name: string;
+        readonly type: FieldType;
+        readonly unique: boolean;
+    }[];
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: FieldType;
+        readonly required: boolean;
+    }[];
+    readonly verbs: readonly Verb[];
+    readonly pageCap?: number;
+}
+export declare const privateShelf: (id: string, shape: PrivateShapeInput) => ShelfDescriptor;
+/** A refusal a method may throw on purpose, for example its own row policy. */
+export type RefusalCode = 'unknown_key' | 'forbidden' | 'not_implemented' | 'shape' | 'provider_error';
+export declare class ShelfRefusal extends Error {
+    readonly code: RefusalCode;
+    constructor(code: RefusalCode, message: string);
+}
+export declare const notImplemented: (id: string, verb: Verb) => ShelfRefusal;
+/**
+ * `By` is the unique key set `read` takes; `Filter` is the equality filter `list` takes (any subset
+ * of the declared keys, unique or not); `R` is one record, exactly the shelf's fields.
+ */
+export declare abstract class Shelf<By extends Row = Row, Filter extends Partial<Row> = Partial<Row>, R extends Row = Row> {
+    abstract readonly descriptor: ShelfDescriptor;
+    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>;
+/** 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[];