@elaraai/e3 1.0.78 → 1.0.80

package/dist/src/package.js

@@ -2,6 +2,12 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
+/**
+ * Package definitions for e3.
+ */
+import { printType } from '@elaraai/east';
+import { nameProblem } from '@elaraai/e3-types';
+import { sameEastType } from './record-guards.js';
 /**
  * Creates a package definition from items.
  *
@@ -18,6 +24,11 @@
  * @param version - Package version
  * @param items - Items to include (datasets, tasks)
  * @returns A PackageDef with typed access to contents
+ * @throws {Error} When the name or the version cannot be a file name — a
+ *   repository keeps the package at `packages/<name>/<version>` — when a
+ *   record is given two different mutations, indexes or migrations of one
+ *   name, or when a record's migrations are not one chain that leaves it as
+ *   its declared type
  *
  * @example
  * ```ts
@@ -41,6 +52,11 @@
 // and forced authors to hand-annotate. Access datasets via the exported
 // task/input consts (`myTask.output`, `myInput.path`) instead — fully typed.
 export function package_(name, version, ...items) {
+    for (const [kind, value] of [['package', name], ['package version', version]]) {
+        const problem = nameProblem(kind, value);
+        if (problem !== null)
+            throw new Error(`e3.package: the ${kind} name ${JSON.stringify(value)} ${problem}`);
+    }
     // Recursively collect all items and their transitive dependencies
     const all_items = new Set();
     const visited = new Set();
@@ -51,6 +67,12 @@ export function package_(name, version, ...items) {
     // folded onto their record below. Records themselves are datasets, so they
     // ride `all_items` and only need a separate RecordObject channel.
     const mutationsByRecord = new Map();
+    // Indexes are collected onto their record the same way, and for the same
+    // reason: an index is declared beside the record and belongs to it.
+    const indexesByRecord = new Map();
+    // Migrations are collected onto their record too, each with the steps before
+    // it, which its `after` names: passing a chain's last step passes the chain.
+    const migrationsByRecord = new Map();
     const importedRecords = {};
     function collect(item) {
         if (visited.has(item))
@@ -77,9 +99,18 @@ export function package_(name, version, ...items) {
         else if (item.kind === "mutation") {
             // Pull in the owning record's dataset and register the mutation onto it.
             collect(item.record);
-            const muts = mutationsByRecord.get(item.record.name) ?? {};
-            muts[item.name] = item;
-            mutationsByRecord.set(item.record.name, muts);
+            mutationsByRecord.set(item.record.name, [...(mutationsByRecord.get(item.record.name) ?? []), item]);
+        }
+        else if (item.kind === "recordIndex") {
+            collect(item.record);
+            indexesByRecord.set(item.record.name, [...(indexesByRecord.get(item.record.name) ?? []), item]);
+        }
+        else if (item.kind === "migration") {
+            collect(item.record);
+            const steps = migrationsByRecord.get(item.record.name) ?? [];
+            for (let step = item; step !== undefined; step = step.after)
+                steps.push(step);
+            migrationsByRecord.set(item.record.name, steps);
         }
         else {
             collect(item);
@@ -127,6 +158,55 @@ export function package_(name, version, ...items) {
             tasks[item.name] = item;
         }
     }
+    // One declaration per name on a record: given two different mutations, or
+    // two different indexes, under one name, the record would keep whichever
+    // came last.
+    const byName = (record, kind, defs) => {
+        const named = {};
+        for (const def of defs) {
+            const taken = named[def.name];
+            if (taken !== undefined && taken !== def) {
+                throw new Error(`e3.package '${name}': record '${record}' declares two ${kind} named '${def.name}' — pass each declaration once`);
+            }
+            named[def.name] = def;
+        }
+        return named;
+    };
+    // A record's migrations in the order they run. They are one chain: exactly
+    // one step has no `after`, no two name the same one, and the last leaves the
+    // record as it is declared, since a deploy leaves a migrated record at the
+    // package's type.
+    const chainOf = (rec, steps) => {
+        const all = Object.values(byName(rec.name, 'migrations', steps));
+        if (all.length === 0)
+            return [];
+        const where = `e3.package '${name}': record '${rec.name}'`;
+        const firsts = all.filter((step) => step.after === undefined);
+        if (firsts.length !== 1) {
+            throw new Error(`${where} has ${firsts.length} migrations with no 'after' (${firsts.map((step) => `'${step.name}'`).join(', ')}) — ` +
+                `its migrations are one chain, and only the first step names none`);
+        }
+        const next = new Map();
+        for (const step of all) {
+            if (step.after === undefined)
+                continue;
+            const taken = next.get(step.after.name);
+            if (taken !== undefined) {
+                throw new Error(`${where} has two migrations after '${step.after.name}', '${taken.name}' and '${step.name}' — ` +
+                    `its migrations are one chain`);
+            }
+            next.set(step.after.name, step);
+        }
+        const chain = [firsts[0]];
+        for (let step = next.get(firsts[0].name); step !== undefined; step = next.get(step.name))
+            chain.push(step);
+        const last = chain[chain.length - 1];
+        if (!sameEastType(last.to, rec.type)) {
+            throw new Error(`${where} is declared as ${printType(rec.type)}, but its last migration, '${last.name}', ` +
+                `leaves it as ${printType(last.to)}`);
+        }
+        return chain;
+    };
     // Assemble records: a record's dataset rides `all_items`; fold in any
     // mutations collected for it. A record imported via a package arrives twice —
     // its bare dataset (mutations `{}`) in `all_items` and its already-assembled
@@ -139,11 +219,21 @@ export function package_(name, version, ...items) {
             const rec = item;
             records[rec.name] = {
                 ...rec,
-                mutations: {
-                    ...records[rec.name]?.mutations,
-                    ...rec.mutations,
-                    ...mutationsByRecord.get(rec.name),
-                },
+                mutations: byName(rec.name, 'mutations', [
+                    ...Object.values(records[rec.name]?.mutations ?? {}),
+                    ...Object.values(rec.mutations),
+                    ...(mutationsByRecord.get(rec.name) ?? []),
+                ]),
+                indexes: byName(rec.name, 'indexes', [
+                    ...Object.values(records[rec.name]?.indexes ?? {}),
+                    ...Object.values(rec.indexes),
+                    ...(indexesByRecord.get(rec.name) ?? []),
+                ]),
+                migrations: chainOf(rec, [
+                    ...(records[rec.name]?.migrations ?? []),
+                    ...rec.migrations,
+                    ...(migrationsByRecord.get(rec.name) ?? []),
+                ]),
             };
         }
     }

package/dist/src/package.js.map

@@ -1 +1 @@
-{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"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"}

package/dist/src/package.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=package.spec.d.ts.map

package/dist/src/package.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.spec.d.ts","sourceRoot":"","sources":["../../src/package.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/package.spec.js

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { describe, it } from 'node:test';
+import * as assert from 'node:assert';
+import { package_ } from './package.js';
+describe('package', () => {
+    it('refuses a name or a version no path can hold, since a repository keeps a package under both', () => {
+        assert.throws(() => package_('../escape', '1.0.0'), /^Error: e3\.package: the package name "\.\.\/escape" holds "\/", which a file name cannot$/);
+        assert.throws(() => package_('pkg', '..'), /^Error: e3\.package: the package version name "\.\." is a path of its own$/);
+        assert.throws(() => package_('pkg', ''), /^Error: e3\.package: the package version name "" is empty$/);
+        assert.strictEqual(package_('pkg', '1.0.0-rc.1').version, '1.0.0-rc.1');
+    });
+});
+//# sourceMappingURL=package.spec.js.map

package/dist/src/package.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.spec.js","sourceRoot":"","sources":["../../src/package.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,EAAE,CAAC,6FAA6F,EAAE,GAAG,EAAE;QACrG,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE,4FAA4F,CAAC,CAAC;QAClJ,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,4EAA4E,CAAC,CAAC;QACzH,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,4DAA4D,CAAC,CAAC;QACvG,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/record-guards.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The guards a record's declarations share. A mutation, an index and a
+ * migration each run an author's function where the data is, again and again,
+ * and each must give the same result every time it runs.
+ *
+ * @packageDocumentation
+ */
+import type { EastType } from '@elaraai/east';
+/**
+ * Whether two East types are the same type.
+ *
+ * @param a - One type
+ * @param b - The other
+ * @returns Whether their type values are equal
+ */
+export declare function sameEastType(a: EastType, b: EastType): boolean;
+/**
+ * Refuses an author's function that is async or reaches a platform function.
+ *
+ * @remarks
+ * An async function implies platform IO. A synchronous platform call is an
+ * ordinary function IR, so the whole body is walked for one: `walkIR` descends
+ * into nested closures, loop bodies and collection-op lambdas.
+ *
+ * @param subject - The function as the error names it, such as
+ *   `e3.mutation.reduce 'place' body`
+ * @param fn - The function
+ * @param why - Why the declaration refuses each, which ends its error
+ * @throws {Error} When the function is async, or calls a platform function.
+ */
+export declare function checkPure(subject: string, fn: {
+    toIR(): unknown;
+}, why: {
+    async: string;
+    platform: string;
+}): void;
+//# sourceMappingURL=record-guards.d.ts.map

package/dist/src/record-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-guards.d.ts","sourceRoot":"","sources":["../../src/record-guards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAO9C;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAE9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE;IAAE,IAAI,IAAI,OAAO,CAAA;CAAE,EAAE,GAAG,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUlH"}

package/dist/src/record-guards.js

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { AsyncEastIR, EastTypeType, equalFor, toEastTypeValue, walkIR } from '@elaraai/east';
+// Structural East-type equality, the same primitive the redeploy type-change
+// guard uses (e3-core workspaces.ts): compare the encoded EastTypeValues.
+const typeValueEqual = equalFor(EastTypeType);
+/**
+ * Whether two East types are the same type.
+ *
+ * @param a - One type
+ * @param b - The other
+ * @returns Whether their type values are equal
+ */
+export function sameEastType(a, b) {
+    return typeValueEqual(toEastTypeValue(a), toEastTypeValue(b));
+}
+/**
+ * Refuses an author's function that is async or reaches a platform function.
+ *
+ * @remarks
+ * An async function implies platform IO. A synchronous platform call is an
+ * ordinary function IR, so the whole body is walked for one: `walkIR` descends
+ * into nested closures, loop bodies and collection-op lambdas.
+ *
+ * @param subject - The function as the error names it, such as
+ *   `e3.mutation.reduce 'place' body`
+ * @param fn - The function
+ * @param why - Why the declaration refuses each, which ends its error
+ * @throws {Error} When the function is async, or calls a platform function.
+ */
+export function checkPure(subject, fn, why) {
+    const ir = fn.toIR();
+    if (ir instanceof AsyncEastIR) {
+        throw new Error(`${subject} must be a synchronous East function — ${why.async}`);
+    }
+    walkIR(ir.ir, (node) => {
+        if (node.type === 'Platform') {
+            throw new Error(`${subject} must not call platform functions (found '${node.value.name}') — ${why.platform}`);
+        }
+    });
+}
+//# sourceMappingURL=record-guards.js.map

package/dist/src/record-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-guards.js","sourceRoot":"","sources":["../../src/record-guards.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE7F,6EAA6E;AAC7E,0EAA0E;AAC1E,MAAM,cAAc,GAAG,QAAQ,CAAC,YAAY,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,CAAW,EAAE,CAAW;IACnD,OAAO,cAAc,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,EAAuB,EAAE,GAAwC;IAC1G,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC;IACrB,IAAI,EAAE,YAAY,WAAW,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,0CAA0C,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;IACD,MAAM,CAAE,EAAoB,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QACxC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,OAAO,6CAA6C,IAAI,CAAC,KAAK,CAAC,IAAI,QAAQ,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC;QAChH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/record-index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Secondary index definitions for e3 records.
+ *
+ * A record is paged and searched in its primary key order and nothing else.
+ * The views over a planning record have more than one order — by status, by
+ * the resources a plan consumes, by time across every plan — and only the ones
+ * contiguous in primary order are addressable without scanning it. An index
+ * closes that gap without a new storage structure: it is a second canonical
+ * collection whose sort order IS the query order, stored as a segment manifest
+ * exactly like the primary, maintained inside the same commit, and read with
+ * the same paging machinery.
+ *
+ * The functions are pure for the reason a reducer is: they run again on every
+ * commit and in every bulk build, and a maintained index must equal a rebuilt
+ * one to the byte.
+ */
+import type { EastType, FunctionExpr, SetType } from '@elaraai/east';
+import { NullType } from '@elaraai/east';
+import type { RecordDef, RecordIndexDef } from './types.js';
+import { type FunctionRunner } from './runner.js';
+/**
+ * What an index declaration needs of a function: a way to reach its IR, and
+ * through that its signature.
+ *
+ * @remarks
+ * Deliberately the weakest shape that works, because a stronger one silently
+ * breaks the authored surface. An index reads
+ * `key: East.function([K, V], IK, ($, k, v) => …)` written INLINE in the spec,
+ * and `East.function` infers its callback's parameters from its own first
+ * argument — but only if nothing is imposed on it from outside. Both a
+ * callable contextual type (`FunctionExpr<any, any>`) and a generic return
+ * type here (`toIR(): EastIR<any, any>`) make TypeScript infer against the
+ * expected type instead, and the body's `k` and `v` come out as the union of
+ * every expression class. `unknown` imposes nothing; the guards below read the
+ * signature at run time regardless.
+ */
+export interface IndexFunction {
+    /** The function's IR bundle, as `EastIR` or `AsyncEastIR`. */
+    toIR(): unknown;
+}
+/** What an index keys on: exactly one of `key` (one entry per row) or `keys`
+ *  (one per element of a returned Set), and an optional covering projection. */
+export type RecordIndexSpec = {
+    /** `(K, V) -> IK` — one index entry per row. */
+    key?: IndexFunction;
+    /** `(K, V) -> Set<IK>` — one index entry per element, so a row that names
+     *  five resources appears under five keys. An empty set is a row the index
+     *  does not carry, which is how a partial index is written. */
+    keys?: IndexFunction;
+    /** `(K, V) -> P` — the fields a view renders from the index alone, so it
+     *  never touches the primary's segments. */
+    value?: IndexFunction;
+};
+/** The type an East function returns, read off the expression itself. */
+type OutputOf<F> = F extends FunctionExpr<any, infer O> ? (O extends EastType ? O : EastType) : EastType;
+/**
+ * The index key a spec declares: `key`'s return, or the element of the Set
+ * `keys` returns.
+ *
+ * @remarks
+ * Read off the spec the caller actually wrote, so the factory's parameter
+ * keeps the weak {@link IndexFunction} shape the inline callbacks need while
+ * its result carries the precise key type — which is what types a window read
+ * through the index, and so every component that renders one.
+ */
+export type IndexKeyOf<S> = S extends {
+    key: infer F;
+} ? OutputOf<F> : S extends {
+    keys: infer F;
+} ? (OutputOf<F> extends SetType<infer IK> ? IK : EastType) : EastType;
+/** The covering projection a spec declares: `value`'s return, Null when the
+ *  spec has no `value`, and any type when it only might. */
+export type ProjectionOf<S> = S extends {
+    value: infer F;
+} ? OutputOf<F> : 'value' extends keyof S ? EastType : NullType;
+/**
+ * Defines a secondary index over a record.
+ *
+ * The index is a collection `Dict<{ik, k}, P>` — the index key first, the
+ * primary key second — so every entry sharing an index key is one contiguous
+ * run ordered by primary key inside it, and a RANGE of index keys is one
+ * contiguous run too. Pages and key searches take the index by name; a view
+ * that renders from the index alone declares its fields as `value` and never
+ * reads the primary at all.
+ *
+ * Every guard here is a definition-time error rather than a deploy failure.
+ *
+ * @typeParam Name - Index name (literal type)
+ * @typeParam T - The owning record's state type (a Dict)
+ * @typeParam S - The spec as written, from which the index key and covering
+ *   projection types are read
+ * @param name - Index name: never `primary`, and one declaration per name on
+ *   the record, which `e3.package` enforces when it folds indexes onto it
+ * @param rec - The record to index
+ * @param spec - Exactly one of `key` / `keys`, and an optional `value`
+ * @param config - Optional runner selection (known runtimes only)
+ * @returns A RecordIndexDef to pass to `e3.package`
+ *
+ * @example
+ * ```ts
+ * const plans = e3.record('plans', DictType(PlanKeyType, PlanRowType), new Map());
+ *
+ * // One key per row, with a covering projection: a queue renders from the
+ * // index alone.
+ * const byStatus = e3.recordIndex('by_status', plans, {
+ *   key:   East.function([PlanKeyType, PlanRowType], StatusKeyType,
+ *            ($, k, v) => ({ status: v.status, due: v.due })),
+ *   value: East.function([PlanKeyType, PlanRowType], QueueCardType,
+ *            ($, k, v) => ({ title: v.title, owner: v.owner })),
+ * });
+ *
+ * // Many keys per row: a Set return.
+ * const byResource = e3.recordIndex('by_resource', plans, {
+ *   keys: East.function([PlanKeyType, PlanRowType], SetType(ResourceRefType),
+ *           ($, k, v) => v.resources),
+ * });
+ *
+ * const pkg = e3.package('planning', '1.0.0', plans, byStatus, byResource);
+ * ```
+ */
+export declare function recordIndex<Name extends string, T extends EastType, S extends RecordIndexSpec>(name: Name, rec: RecordDef<T>, spec: S, config?: {
+    runner?: FunctionRunner;
+}): RecordIndexDef<Name, T, IndexKeyOf<S>, ProjectionOf<S>>;
+export {};
+//# sourceMappingURL=record-index.d.ts.map

package/dist/src/record-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.d.ts","sourceRoot":"","sources":["../../src/record-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAQ,QAAQ,EAAa,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D,OAAO,EAAmC,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAMnF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,IAAI,IAAI,OAAO,CAAC;CACjB;AAED;gFACgF;AAChF,MAAM,MAAM,eAAe,GAAG;IAC5B,gDAAgD;IAChD,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;mEAE+D;IAC/D,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;gDAC4C;IAC5C,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF,yEAAyE;AACzE,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,SAAS,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,QAAQ,CAAC;AAEzG;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACtB,CAAC,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GACtC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,QAAQ,CAAC,GACrF,QAAQ,CAAC;AAEb;4DAC4D;AAC5D,MAAM,MAAM,YAAY,CAAC,CAAC,IACxB,CAAC,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,GACxC,OAAO,SAAS,MAAM,CAAC,GAAG,QAAQ,GAClC,QAAQ,CAAC;AA2Bb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,eAAe,EAC5F,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,EACjB,IAAI,EAAE,CAAC,EACP,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,cAAc,CAAA;CAAE,GACnC,cAAc,CAAC,IAAI,EAAE,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAoFzD"}

package/dist/src/record-index.js

@@ -0,0 +1,144 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { Expr, NullType, printType } from '@elaraai/east';
+import { checkPure, sameEastType } from './record-guards.js';
+import { DEFAULT_RUNNER, runnerToVariant } from './runner.js';
+/** The index name reserved for the record's own collection wherever an index
+ *  is selected — a page, a key search, an arm of the mutation delta. */
+const RESERVED_INDEX_NAME = 'primary';
+/** The signature of a function an index declares, as the guards see it. */
+function signatureOf(fn) {
+    return Expr.type(fn);
+}
+/** Why an index function may be neither async nor reach a platform function:
+ *  either makes the index non-deterministic, and an index that does not equal
+ *  its rebuild is worse than no index, since the view it serves is quietly
+ *  wrong. */
+const INDEX_PURITY = {
+    async: 'an async function implies platform IO, and an index is rebuilt from the record whenever it is dropped or its declaration changes.',
+    platform: 'the index is maintained on every commit and rebuilt on demand, so a platform call makes the two disagree.',
+};
+/** Refuses an index function whose parameters are not the record's entry. */
+function checkEntryParams(name, role, keyType, valueType, inputs) {
+    if (inputs.length !== 2 || !sameEastType(keyType, inputs[0]) || !sameEastType(valueType, inputs[1])) {
+        const got = inputs.length === 0 ? 'no parameters' : inputs.map((t) => printType(t)).join(', ');
+        throw new Error(`e3.recordIndex '${name}' ${role} must take the record's entry ` +
+            `(${printType(keyType)}, ${printType(valueType)}), but got ${got}.`);
+    }
+}
+/**
+ * Defines a secondary index over a record.
+ *
+ * The index is a collection `Dict<{ik, k}, P>` — the index key first, the
+ * primary key second — so every entry sharing an index key is one contiguous
+ * run ordered by primary key inside it, and a RANGE of index keys is one
+ * contiguous run too. Pages and key searches take the index by name; a view
+ * that renders from the index alone declares its fields as `value` and never
+ * reads the primary at all.
+ *
+ * Every guard here is a definition-time error rather than a deploy failure.
+ *
+ * @typeParam Name - Index name (literal type)
+ * @typeParam T - The owning record's state type (a Dict)
+ * @typeParam S - The spec as written, from which the index key and covering
+ *   projection types are read
+ * @param name - Index name: never `primary`, and one declaration per name on
+ *   the record, which `e3.package` enforces when it folds indexes onto it
+ * @param rec - The record to index
+ * @param spec - Exactly one of `key` / `keys`, and an optional `value`
+ * @param config - Optional runner selection (known runtimes only)
+ * @returns A RecordIndexDef to pass to `e3.package`
+ *
+ * @example
+ * ```ts
+ * const plans = e3.record('plans', DictType(PlanKeyType, PlanRowType), new Map());
+ *
+ * // One key per row, with a covering projection: a queue renders from the
+ * // index alone.
+ * const byStatus = e3.recordIndex('by_status', plans, {
+ *   key:   East.function([PlanKeyType, PlanRowType], StatusKeyType,
+ *            ($, k, v) => ({ status: v.status, due: v.due })),
+ *   value: East.function([PlanKeyType, PlanRowType], QueueCardType,
+ *            ($, k, v) => ({ title: v.title, owner: v.owner })),
+ * });
+ *
+ * // Many keys per row: a Set return.
+ * const byResource = e3.recordIndex('by_resource', plans, {
+ *   keys: East.function([PlanKeyType, PlanRowType], SetType(ResourceRefType),
+ *           ($, k, v) => v.resources),
+ * });
+ *
+ * const pkg = e3.package('planning', '1.0.0', plans, byStatus, byResource);
+ * ```
+ */
+export function recordIndex(name, rec, spec, config) {
+    if (!name) {
+        throw new Error('e3.recordIndex requires a non-empty name');
+    }
+    if (name === RESERVED_INDEX_NAME) {
+        throw new Error(`e3.recordIndex cannot be named '${RESERVED_INDEX_NAME}' — that name is the ` +
+            `record's own collection wherever an index is selected.`);
+    }
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`e3.recordIndex '${name}' must be an identifier — it names a query ` +
+            `selector in URLs and on the command line.`);
+    }
+    // An assembled record — a package's `records.plans` — carries its indexes
+    // already; a bare one is checked when `e3.package` folds indexes onto it.
+    if (rec.indexes[name] !== undefined) {
+        throw new Error(`e3.recordIndex '${name}' is already declared on record '${rec.name}'`);
+    }
+    const recordType = rec.type;
+    if (recordType.type !== 'Dict') {
+        throw new Error(`e3.recordIndex '${name}' indexes a Dict record — '${rec.name}' holds ` +
+            `${printType(rec.type)}, which has no (key, value) entry to index. A Set or ` +
+            `Array record is read in its own order only.`);
+    }
+    const keyType = recordType.key;
+    const valueType = recordType.value;
+    if ((spec.key === undefined) === (spec.keys === undefined)) {
+        throw new Error(`e3.recordIndex '${name}' takes exactly one of 'key' (one entry per row) ` +
+            `or 'keys' (one per element of a returned Set)`);
+    }
+    const multi = spec.keys !== undefined;
+    const keyFn = (spec.key ?? spec.keys);
+    const runner = config?.runner ?? DEFAULT_RUNNER;
+    // Validate eagerly so a bad runner fails at definition time, not export time.
+    runnerToVariant(runner);
+    checkPure(`e3.recordIndex '${name}' ${multi ? "'keys' function" : "'key' function"}`, keyFn, INDEX_PURITY);
+    const keySig = signatureOf(keyFn);
+    checkEntryParams(name, multi ? "'keys' function" : "'key' function", keyType, valueType, keySig.inputs);
+    let indexKeyType = keySig.output;
+    if (multi) {
+        const returned = keySig.output;
+        if (returned.type !== 'Set') {
+            throw new Error(`e3.recordIndex '${name}' declared with 'keys' must return a Set of index ` +
+                `keys — one entry per element — but returns ${printType(keySig.output)}. ` +
+                `For one entry per row use 'key'.`);
+        }
+        indexKeyType = returned.key;
+    }
+    let projectionType = NullType;
+    if (spec.value !== undefined) {
+        checkPure(`e3.recordIndex '${name}' 'value' projection`, spec.value, INDEX_PURITY);
+        const valueSig = signatureOf(spec.value);
+        checkEntryParams(name, "'value' projection", keyType, valueType, valueSig.inputs);
+        projectionType = valueSig.output;
+    }
+    return {
+        kind: 'recordIndex',
+        name,
+        record: rec,
+        keyFn,
+        ...(spec.value !== undefined && { valueFn: spec.value }),
+        multi,
+        // The signature read above IS the type the spec's functions declare; the
+        // casts only restate it at the TypeScript level.
+        keyType: indexKeyType,
+        valueType: projectionType,
+        runner,
+    };
+}
+//# sourceMappingURL=record-index.js.map

package/dist/src/record-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.js","sourceRoot":"","sources":["../../src/record-index.ts"],"names":[],"mappings":"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"}

package/dist/src/record-index.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=record-index.spec.d.ts.map

package/dist/src/record-index.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.spec.d.ts","sourceRoot":"","sources":["../../src/record-index.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}