@mulmoclaude/core 0.24.0 → 0.25.1

package/dist/collection/server/index.cjs

@@ -1,81 +1,85 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_promptSafety = require("../../promptSafety-DI_1Rvhk.cjs");
-const require_server = require("../../server-CkysfLh4.cjs");
-const require_collection_paths = require("../paths.cjs");
-exports.COMPUTED_TYPES = require_promptSafety.COMPUTED_TYPES;
-exports.CollectionQueryZ = require_server.CollectionQueryZ;
-exports.CollectionSchemaZ = require_server.CollectionSchemaZ;
-exports.DEFAULT_QUERY_ROWS = require_server.DEFAULT_QUERY_ROWS;
-exports.MAX_CSV_ROWS = require_server.MAX_CSV_ROWS;
-exports.MAX_QUERY_ROWS = require_server.MAX_QUERY_ROWS;
+const require_ids = require("../../ids-Dl9Ij63K.cjs");
+const require_discovery = require("../../discovery-cwtfyDxl.cjs");
+const require_templatePath = require("../../templatePath-27vUZowm.cjs");
+const require_server = require("../../server-CKdWENZ-.cjs");
+exports.COMPUTED_TYPES = require_ids.COMPUTED_TYPES;
+exports.CollectionQueryZ = require_discovery.CollectionQueryZ;
+exports.CollectionSchemaZ = require_discovery.CollectionSchemaZ;
+exports.DEFAULT_QUERY_ROWS = require_discovery.DEFAULT_QUERY_ROWS;
+exports.MAX_CSV_ROWS = require_discovery.MAX_CSV_ROWS;
+exports.MAX_QUERY_ROWS = require_discovery.MAX_QUERY_ROWS;
 exports.MAX_SCHEMA_ISSUES = require_server.MAX_SCHEMA_ISSUES;
 exports.MAX_UNSELECTIVE_ITEMS = require_server.MAX_UNSELECTIVE_ITEMS;
-exports.SCHEMA_FILE = require_server.SCHEMA_FILE;
-exports.acceptParsedSchema = require_server.acceptParsedSchema;
+exports.SCHEMA_FILE = require_discovery.SCHEMA_FILE;
+exports.acceptParsedSchema = require_discovery.acceptParsedSchema;
 exports.advanceTriggerDate = require_server.advanceTriggerDate;
 exports.applyMutateAction = require_server.applyMutateAction;
-exports.buildActionSeedPrompt = require_server.buildActionSeedPrompt;
-exports.buildCollectionActionSeedPrompt = require_server.buildCollectionActionSeedPrompt;
+exports.buildActionSeedPrompt = require_discovery.buildActionSeedPrompt;
+exports.buildCollectionActionSeedPrompt = require_discovery.buildCollectionActionSeedPrompt;
 exports.buildWorkspaceOntology = require_server.buildWorkspaceOntology;
-exports.collectionWritable = require_server.collectionWritable;
-exports.compileCsvQuery = require_server.compileCsvQuery;
-exports.compileJsonlQuery = require_server.compileJsonlQuery;
+exports.collectionWritable = require_discovery.collectionWritable;
+exports.compileCsvQuery = require_discovery.compileCsvQuery;
+exports.compileJsonlQuery = require_discovery.compileJsonlQuery;
 exports.compileRecordZ = require_server.compileRecordZ;
 exports.computeCollectionIcon = require_server.computeCollectionIcon;
 exports.computeSuccessor = require_server.computeSuccessor;
-exports.configureCollectionHost = require_server.configureCollectionHost;
-exports.csvRowToItem = require_server.csvRowToItem;
+exports.configureCollectionHost = require_discovery.configureCollectionHost;
+exports.csvRowToItem = require_discovery.csvRowToItem;
 exports.daysInMonth = require_server.daysInMonth;
-exports.decodeCsvRecordId = require_server.decodeCsvRecordId;
-exports.dedupeByRecordId = require_server.dedupeByRecordId;
+exports.decodeCsvRecordId = require_discovery.decodeCsvRecordId;
+exports.dedupeByRecordId = require_discovery.dedupeByRecordId;
 exports.deleteCollection = require_server.deleteCollection;
 exports.deleteCollectionRefusalMessage = require_server.deleteCollectionRefusalMessage;
 exports.deleteCustomView = require_server.deleteCustomView;
-exports.deleteItem = require_server.deleteItem;
-exports.discoverCollections = require_server.discoverCollections;
-exports.encodeCsvRecordId = require_server.encodeCsvRecordId;
+exports.deleteItem = require_discovery.deleteItem;
+exports.discoverCollections = require_discovery.discoverCollections;
+exports.encodeCsvRecordId = require_discovery.encodeCsvRecordId;
 exports.enrichItems = require_server.enrichItems;
 exports.firstMutateParamProblem = require_server.firstMutateParamProblem;
 exports.formatCivil = require_server.formatCivil;
-exports.generateItemId = require_server.generateItemId;
-exports.getWorkspaceRoot = require_server.getWorkspaceRoot;
-exports.isContainedInRoot = require_server.isContainedInRoot;
-exports.isContainedInWorkspace = require_server.isContainedInWorkspace;
-exports.isRegularFile = require_server.isRegularFile;
-exports.isSafeActionTemplatePath = require_collection_paths.isSafeActionTemplatePath;
-exports.isSafeCustomViewI18nPath = require_collection_paths.isSafeCustomViewI18nPath;
-exports.isSafeCustomViewPath = require_collection_paths.isSafeCustomViewPath;
-exports.isSafeTemplatePath = require_collection_paths.isSafeTemplatePath;
+exports.generateItemId = require_discovery.generateItemId;
+exports.getWorkspaceRoot = require_discovery.getWorkspaceRoot;
+exports.isContainedInRoot = require_discovery.isContainedInRoot;
+exports.isContainedInWorkspace = require_discovery.isContainedInWorkspace;
+exports.isRegularFile = require_discovery.isRegularFile;
+exports.isSafeActionTemplatePath = require_templatePath.isSafeActionTemplatePath;
+exports.isSafeCustomViewI18nPath = require_templatePath.isSafeCustomViewI18nPath;
+exports.isSafeCustomViewPath = require_templatePath.isSafeCustomViewPath;
+exports.isSafeTemplatePath = require_templatePath.isSafeTemplatePath;
 exports.isTriggerDue = require_server.isTriggerDue;
-exports.itemFilePath = require_server.itemFilePath;
-exports.listItems = require_server.listItems;
-exports.loadCollection = require_server.loadCollection;
-exports.log = require_server.log;
+exports.itemFilePath = require_discovery.itemFilePath;
+exports.listItems = require_discovery.listItems;
+exports.loadCollection = require_discovery.loadCollection;
+exports.log = require_discovery.log;
 exports.makeManageCollectionTool = require_server.makeManageCollectionTool;
 exports.maybeSpawnSuccessor = require_server.maybeSpawnSuccessor;
-exports.normalizeCsvValue = require_server.normalizeCsvValue;
+exports.normalizeCsvValue = require_discovery.normalizeCsvValue;
+exports.pageFromFullRead = require_discovery.pageFromFullRead;
 exports.parseCivil = require_server.parseCivil;
-exports.promptPathsFor = require_server.promptPathsFor;
-exports.publishCollectionChange = require_server.publishCollectionChange;
-exports.readCustomViewHtml = require_server.readCustomViewHtml;
-exports.readCustomViewI18n = require_server.readCustomViewI18n;
-exports.readItem = require_server.readItem;
-exports.readOnlyRefusal = require_server.readOnlyRefusal;
-exports.readSkillTemplate = require_server.readSkillTemplate;
+exports.projectItemFields = require_discovery.projectItemFields;
+exports.promptPathsFor = require_discovery.promptPathsFor;
+exports.publishCollectionChange = require_discovery.publishCollectionChange;
+exports.readCustomViewHtml = require_discovery.readCustomViewHtml;
+exports.readCustomViewI18n = require_discovery.readCustomViewI18n;
+exports.readItem = require_discovery.readItem;
+exports.readOnlyRefusal = require_discovery.readOnlyRefusal;
+exports.readSkillTemplate = require_discovery.readSkillTemplate;
 exports.recordFieldProblem = require_server.recordFieldProblem;
-exports.resolveCreateItemId = require_server.resolveCreateItemId;
-exports.resolveDataDir = require_server.resolveDataDir;
+exports.resolveCreateItemId = require_discovery.resolveCreateItemId;
+exports.resolveDataDir = require_discovery.resolveDataDir;
 exports.resolveEvery = require_server.resolveEvery;
-exports.resolveTemplatePath = require_server.resolveTemplatePath;
+exports.resolveTemplatePath = require_discovery.resolveTemplatePath;
+exports.runCollectionQuery = require_server.runCollectionQuery;
 exports.runQueryOverRows = require_server.runQueryOverRows;
-exports.safeRecordId = require_server.safeRecordId;
-exports.safeSlugName = require_server.safeSlugName;
+exports.safeRecordId = require_discovery.safeRecordId;
+exports.safeSlugName = require_discovery.safeSlugName;
 exports.schemaRelations = require_server.schemaRelations;
-exports.setCollectionChangePublisher = require_server.setCollectionChangePublisher;
-exports.storeFor = require_server.storeFor;
+exports.setCollectionChangePublisher = require_discovery.setCollectionChangePublisher;
+exports.storeFor = require_discovery.storeFor;
 exports.successorId = require_server.successorId;
-exports.toDetail = require_server.toDetail;
-exports.toSummary = require_server.toSummary;
+exports.toDetail = require_discovery.toDetail;
+exports.toSummary = require_discovery.toSummary;
 exports.validateCollectionRecords = require_server.validateCollectionRecords;
 exports.validateRecordObject = require_server.validateRecordObject;
-exports.writeItem = require_server.writeItem;
+exports.writeItem = require_discovery.writeItem;

package/dist/collection/server/index.d.ts

@@ -7,6 +7,7 @@ export * from './store';
 export { MAX_CSV_ROWS, encodeCsvRecordId, decodeCsvRecordId, normalizeCsvValue, csvRowToItem, dedupeByRecordId } from './csvStore';
 export { compileCsvQuery, compileJsonlQuery } from './csvQuery';
 export { runQueryOverRows } from './jsonlQuery';
+export { runCollectionQuery } from './queryRunner';
 export { CollectionQueryZ, MAX_QUERY_ROWS, DEFAULT_QUERY_ROWS } from '../core/queryZ';
 export type { CollectionQuery, CollectionQueryAggregate, CollectionQueryOrder, CollectionQueryWhere } from '../core/queryZ';
 export * from './validate';

package/dist/collection/server/index.js

@@ -1,4 +1,5 @@
-import { L as COMPUTED_TYPES } from "../../promptSafety-BLUcImzd.js";
-import { $ as isRegularFile, A as validateCollectionRecords, B as decodeCsvRecordId, C as discoverCollections, D as CollectionSchemaZ, E as toSummary, F as collectionWritable, G as compileJsonlQuery, H as encodeCsvRecordId, I as readOnlyRefusal, J as MAX_QUERY_ROWS, K as CollectionQueryZ, L as storeFor, M as compileRecordZ, N as recordFieldProblem, O as applyMutateAction, P as runQueryOverRows, Q as generateItemId, R as MAX_CSV_ROWS, S as acceptParsedSchema, St as setCollectionChangePublisher, T as toDetail, U as normalizeCsvValue, V as dedupeByRecordId, W as compileCsvQuery, X as buildCollectionActionSeedPrompt, Y as buildActionSeedPrompt, Z as deleteItem, a as deleteCollection, at as readSkillTemplate, b as buildWorkspaceOntology, bt as log, c as computeSuccessor, d as isTriggerDue, dt as isContainedInWorkspace, et as listItems, f as maybeSpawnSuccessor, ft as itemFilePath, gt as safeSlugName, h as successorId, ht as safeRecordId, i as deleteCustomView, it as readItem, j as validateRecordObject, k as firstMutateParamProblem, l as daysInMonth, lt as SCHEMA_FILE, m as resolveEvery, mt as resolveTemplatePath, n as MAX_UNSELECTIVE_ITEMS, nt as readCustomViewHtml, o as deleteCollectionRefusalMessage, ot as resolveCreateItemId, p as parseCivil, pt as resolveDataDir, q as DEFAULT_QUERY_ROWS, r as makeManageCollectionTool, rt as readCustomViewI18n, s as advanceTriggerDate, st as writeItem, t as MAX_SCHEMA_ISSUES, tt as promptPathsFor, u as formatCivil, ut as isContainedInRoot, v as computeCollectionIcon, vt as configureCollectionHost, w as loadCollection, x as schemaRelations, xt as publishCollectionChange, y as enrichItems, yt as getWorkspaceRoot, z as csvRowToItem } from "../../server-BpEo0FOd.js";
-import { isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath } from "../paths.js";
-export { COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileJsonlQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, parseCivil, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, runQueryOverRows, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };
+import { o as COMPUTED_TYPES } from "../../ids-P2T89Gou.js";
+import { A as generateItemId, C as compileJsonlQuery, D as buildActionSeedPrompt, E as MAX_QUERY_ROWS, F as readCustomViewI18n, G as resolveDataDir, H as isContainedInRoot, I as readItem, J as safeSlugName, K as resolveTemplatePath, L as readSkillTemplate, M as listItems, N as promptPathsFor, O as buildCollectionActionSeedPrompt, P as readCustomViewHtml, Q as getWorkspaceRoot, R as resolveCreateItemId, S as compileCsvQuery, T as DEFAULT_QUERY_ROWS, U as isContainedInWorkspace, V as SCHEMA_FILE, W as itemFilePath, Z as configureCollectionHost, _ as decodeCsvRecordId, a as toSummary, b as normalizeCsvValue, c as collectionWritable, et as log, f as pageFromFullRead, g as csvRowToItem, i as toDetail, j as isRegularFile, k as deleteItem, l as readOnlyRefusal, m as MAX_CSV_ROWS, n as discoverCollections, nt as setCollectionChangePublisher, o as CollectionSchemaZ, p as projectItemFields, q as safeRecordId, r as loadCollection, t as acceptParsedSchema, tt as publishCollectionChange, u as storeFor, v as dedupeByRecordId, w as CollectionQueryZ, y as encodeCsvRecordId, z as writeItem } from "../../discovery-QUi_7aNG.js";
+import { i as isSafeTemplatePath, n as isSafeCustomViewI18nPath, r as isSafeCustomViewPath, t as isSafeActionTemplatePath } from "../../templatePath-k_WNbL_Q.js";
+import { C as validateCollectionRecords, D as runCollectionQuery, E as recordFieldProblem, O as enrichItems, S as firstMutateParamProblem, T as compileRecordZ, a as deleteCollection, b as schemaRelations, c as computeSuccessor, d as isTriggerDue, f as maybeSpawnSuccessor, h as successorId, i as deleteCustomView, k as runQueryOverRows, l as daysInMonth, m as resolveEvery, n as MAX_UNSELECTIVE_ITEMS, o as deleteCollectionRefusalMessage, p as parseCivil, r as makeManageCollectionTool, s as advanceTriggerDate, t as MAX_SCHEMA_ISSUES, u as formatCivil, v as computeCollectionIcon, w as validateRecordObject, x as applyMutateAction, y as buildWorkspaceOntology } from "../../server-BI3wnTwl.js";
+export { COMPUTED_TYPES, CollectionQueryZ, CollectionSchemaZ, DEFAULT_QUERY_ROWS, MAX_CSV_ROWS, MAX_QUERY_ROWS, MAX_SCHEMA_ISSUES, MAX_UNSELECTIVE_ITEMS, SCHEMA_FILE, acceptParsedSchema, advanceTriggerDate, applyMutateAction, buildActionSeedPrompt, buildCollectionActionSeedPrompt, buildWorkspaceOntology, collectionWritable, compileCsvQuery, compileJsonlQuery, compileRecordZ, computeCollectionIcon, computeSuccessor, configureCollectionHost, csvRowToItem, daysInMonth, decodeCsvRecordId, dedupeByRecordId, deleteCollection, deleteCollectionRefusalMessage, deleteCustomView, deleteItem, discoverCollections, encodeCsvRecordId, enrichItems, firstMutateParamProblem, formatCivil, generateItemId, getWorkspaceRoot, isContainedInRoot, isContainedInWorkspace, isRegularFile, isSafeActionTemplatePath, isSafeCustomViewI18nPath, isSafeCustomViewPath, isSafeTemplatePath, isTriggerDue, itemFilePath, listItems, loadCollection, log, makeManageCollectionTool, maybeSpawnSuccessor, normalizeCsvValue, pageFromFullRead, parseCivil, projectItemFields, promptPathsFor, publishCollectionChange, readCustomViewHtml, readCustomViewI18n, readItem, readOnlyRefusal, readSkillTemplate, recordFieldProblem, resolveCreateItemId, resolveDataDir, resolveEvery, resolveTemplatePath, runCollectionQuery, runQueryOverRows, safeRecordId, safeSlugName, schemaRelations, setCollectionChangePublisher, storeFor, successorId, toDetail, toSummary, validateCollectionRecords, validateRecordObject, writeItem };

package/dist/collection/server/queryRunner.d.ts

@@ -0,0 +1,4 @@
+import { CollectionQuery } from '../core/queryZ';
+import { LoadedCollection } from './discoveredCollection';
+import { DiscoveryOptions } from './discovery';
+export declare function runCollectionQuery(collection: LoadedCollection, query: CollectionQuery, opts?: DiscoveryOptions): Promise<Record<string, unknown>[]>;

package/dist/collection/server/spawn.d.ts

@@ -1,4 +1,5 @@
 import { IoOptions } from './io';
+import { LoadedCollection } from './discoveredCollection';
 import { CollectionEvery, CollectionItem, CollectionSchema, CollectionSpawnEvery } from '../core/schema';
 /** A timezone-free calendar date. `m` is 1-12. */
 export interface CivilDate {
@@ -52,4 +53,4 @@ export declare function computeSuccessor(schema: CollectionSchema, sourceItem: C
  *  predicate doesn't match, the trigger date is unparseable, or the
  *  successor already exists (create-if-absent). Never overwrites an
  *  existing successor — protects any edits the user made to it. */
-export declare function maybeSpawnSuccessor(slug: string, schema: CollectionSchema, dataDir: string, sourceItem: CollectionItem, sourceId: string, ioOpts?: IoOptions): Promise<void>;
+export declare function maybeSpawnSuccessor(collection: LoadedCollection, sourceItem: CollectionItem, sourceId: string, ioOpts?: IoOptions): Promise<void>;

package/dist/collection/server/sqliteStore.d.ts

@@ -0,0 +1,14 @@
+import { LoadedCollection } from './discoveredCollection';
+import { IoOptions } from './io';
+import { CollectionStore } from './store';
+/** Best-effort full WAL checkpoint so the MAIN db file alone is a
+ *  complete snapshot (committed pages in `<db>-wal` are folded in and the
+ *  WAL truncated). Used by `deleteCollection` before archiving. Returns
+ *  false on any failure (runtime without node:sqlite, locked db, missing
+ *  file) — the caller then archives the sidecar files alongside the db so
+ *  no committed data is lost either way. */
+export declare function checkpointSqliteDatabase(absPath: string): Promise<boolean>;
+/** A `storage: sqlite` store over `collection.storageFile`. A schema whose
+ *  `storageFile` failed to resolve yields a read-only EMPTY store rather
+ *  than a writable one — same fail-closed rule as the CSV store. */
+export declare function sqliteStoreFor(collection: LoadedCollection, opts: IoOptions): CollectionStore;

package/dist/collection/server/store.d.ts

@@ -1,21 +1,55 @@
 import { CollectionItem } from '../core/schema';
 import { CollectionQuery } from '../core/queryZ';
 import { LoadedCollection } from './discoveredCollection';
-import { IoOptions } from './io';
+import { DeleteItemResult, IoOptions, WriteItemResult } from './io';
+import { ListOptions, ListPage, WriteOptions } from './storePage';
+export { pageFromFullRead, projectItemFields, type ListOptions, type ListPage, type WriteOptions } from './storePage';
 export interface CollectionStoreCapabilities {
     readonly writable: boolean;
+    /** Native aggregation engine for the structured DSL (`core/queryZ.ts`).
+     *  False ⇒ `query` is absent; the engine-level fallback (enrich →
+     *  JSONL → DuckDB, `queryRunner.ts`) answers aggregations instead. */
+    readonly nativeQuery: boolean;
+    /** True when `page` resolves offset/limit inside the backend. False ⇒
+     *  `page` is emulated (full read, then slice) — same result, no saving. */
+    readonly nativePaging: boolean;
 }
+/** The storage contract every backend must satisfy (verified by the shared
+ *  contract test suite, `test/workspace/collections/test_storeContract.ts`):
+ *
+ *  1. STABLE ORDER — `page` walks a documented deterministic order (file
+ *     store: lexicographic by record id; CSV store: file row order; SQLite
+ *     store: `ORDER BY id`), so `offset`-paging never skips or repeats
+ *     records between calls. Sorting by arbitrary fields is NOT the
+ *     store's job.
+ *  2. IDS — minting/resolving record ids is the store's job (the CSV
+ *     store's `id0x…` encoding stays inside it); `read` resolves every id
+ *     `list`/`page` returned.
+ *  3. CONTAINMENT — a store never serves data from outside the workspace;
+ *     symlink/realpath defenses are each implementation's obligation
+ *     (io.ts is the reference).
+ *  4. HONEST AGGREGATION — `query`, when present, is computed over the
+ *     WHOLE data set, never from a capped read. */
 export interface CollectionStore {
     readonly capabilities: CollectionStoreCapabilities;
-    /** Every record. CSV store: capped at `MAX_CSV_ROWS` (see csvStore.ts). */
+    /** Every record, in the store's stable order. CSV store: capped at
+     *  `MAX_CSV_ROWS` (see csvStore.ts). Prefer `page` in new code. */
     list: () => Promise<CollectionItem[]>;
+    /** One page of records — offset/limit/projection over the stable order. */
+    page: (opts?: ListOptions) => Promise<ListPage>;
     /** One record by id, or null when missing/invalid. */
     read: (itemId: string) => Promise<CollectionItem | null>;
     /** Aggregation over the WHOLE data set (the structured DSL,
      *  `core/queryZ.ts`) — present only on stores with a native query
-     *  engine (the CSV store). Absent ⇒ the collection doesn't support
-     *  queries yet; callers surface a clear error, never emulate. */
+     *  engine (the CSV store). Absent ⇒ use the engine-level fallback
+     *  (`runCollectionQuery`), never emulate ad hoc. */
     query?: (query: CollectionQuery) => Promise<Record<string, unknown>[]>;
+    /** Present ONLY when `capabilities.writable` — absence IS the read-only
+     *  refusal (surface it with `readOnlyRefusal`). A successful write/delete
+     *  publishes a collection-change event: the store always threads the
+     *  collection's slug into the publish hook, so no writer can forget it. */
+    write?: (itemId: string, item: CollectionItem, opts?: WriteOptions) => Promise<WriteItemResult>;
+    delete?: (itemId: string) => Promise<DeleteItemResult>;
 }
 /** True when the collection accepts UI/tool writes. A `dataSource`
  *  collection is read-only: updates happen by editing/replacing the
@@ -24,8 +58,9 @@ export interface CollectionStore {
 export declare function collectionWritable(collection: Pick<LoadedCollection, "schema">): boolean;
 /** The one-line refusal write paths surface (HTTP 405 / MCP error text). */
 export declare function readOnlyRefusal(slug: string): string;
-/** Pick the store implementation for a discovered collection. A
- *  `dataSource` schema whose `dataSourceFile` failed to resolve yields a
- *  read-only EMPTY store rather than falling back to the (writable) file
- *  store — a half-loaded read-only collection must never become writable. */
+export type CollectionStoreFactory = (collection: LoadedCollection, opts: IoOptions) => CollectionStore;
+/** Pick the store implementation for a discovered collection via the
+ *  factory registry. An unknown kind cannot normally reach here (the
+ *  schema's `StorageZ` union gates it), so the throw is a loud invariant
+ *  breach, not a user-facing path. */
 export declare function storeFor(collection: LoadedCollection, opts?: IoOptions): CollectionStore;

package/dist/collection/server/storePage.d.ts

@@ -0,0 +1,32 @@
+import { CollectionItem } from '../core/schema';
+/** Options for `page`. STORED fields only — computed fields (`derived` /
+ *  `toggle` / `embed` / rollups) never reach the store; project them at the
+ *  engine level after enrichment. */
+export interface ListOptions {
+    /** 0-based offset into the store's stable order (see the contract). */
+    offset?: number;
+    /** Max records returned. Absent = all remaining (subject to store caps). */
+    limit?: number;
+    /** Keep only these fields per record (the primary key is always kept). */
+    fields?: readonly string[];
+}
+export interface ListPage {
+    items: CollectionItem[];
+    /** Records in the collection before offset/limit — a lower bound when
+     *  `truncated` (the store capped its scan, e.g. `MAX_CSV_ROWS`). */
+    total: number;
+    truncated: boolean;
+}
+export interface WriteOptions {
+    /** Create semantics: fail with `kind: "conflict"` when the record
+     *  already exists (an O_EXCL open in the file store — race-safe). */
+    refuseOverwrite?: boolean;
+}
+/** Project `fields` (+ the primary key, always) out of each record. Thin
+ *  server-typed alias over the shared isomorphic `projectRecordFields`
+ *  (../core/project.ts) — kept as the store layer's exported name. */
+export declare function projectItemFields(items: CollectionItem[], fields: readonly string[] | undefined, primaryKey: string): CollectionItem[];
+/** Slice + project an already-ordered full read into a `ListPage` — the
+ *  shared emulation for stores without native paging. Pure, exported for
+ *  tests. `limit: 0` is a valid "count only" page. */
+export declare function pageFromFullRead(items: CollectionItem[], opts: ListOptions, primaryKey: string, truncated: boolean): ListPage;