outask 0.0.0-stage → 1.7.0

package/src/stores.mjs

@@ -0,0 +1,337 @@
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { knownCounter, prepareService, readService } from './service.mjs';
+import { fail } from './errors.mjs';
+import { validateFieldRules } from './field-rules.mjs';
+import { validateTimestamp } from './timestamps.mjs';
+import { projectBudget, readArray, readJson } from './input.mjs';
+
+// Service fingerprints and recovery journals use portable project-relative keys.
+export const projectRelative = (root, path) => relative(root, path).split(sep).join('/');
+
+export const serviceFile = '.task-tracker.json';
+export const pendingFile = '.task-tracker.pending';
+
+export const standardStores = {
+  'active.json': { statuses: ['pending', 'in_progress', 'review'], missing_status: 'pending' },
+  'done.json': { statuses: ['done'], missing_status: 'done' },
+  'archive.json': { statuses: ['cancelled'] },
+};
+export const defaultSearch = { mode: 'scan' };
+const standardGroups = {
+  Active: ['pending', 'in_progress', 'review'], Done: ['done'], Archive: ['cancelled'],
+};
+const fileGroups = { 'active.json': 'Active', 'done.json': 'Done', 'archive.json': 'Archive' };
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+const isStrings = (value) => Array.isArray(value) && value.every(isText);
+
+function storeName(name) {
+  return isText(name) && name.endsWith('.json') && !/[\\/\0]/.test(name)
+    && ![serviceFile, 'task-schema.json'].includes(name);
+}
+
+export const defaultSchema = 'tasks/task-schema.json';
+export const legacySchema = 'docs/task-schema.json';
+const selectedSchema = Symbol('selectedSchema');
+
+function contained(root, path) {
+  const name = relative(root, path);
+  return name !== '' && !name.startsWith('..') && !isAbsolute(name);
+}
+
+function inspectSchema(root, path, required) {
+  const tail = relative(root, path);
+  let current = root;
+  for (const part of tail.split(sep)) {
+    current = join(current, part);
+    let stat;
+    try { stat = lstatSync(current); } catch (error) {
+      if (error.code === 'ENOENT') {
+        if (!required) return false;
+        fail('READ_ERROR', `${path}: selected schema does not exist`);
+      }
+      fail('READ_ERROR', `${current}: cannot inspect schema path (${error.code})`);
+    }
+    if (stat.isSymbolicLink()) fail('INVALID_CONFIG', `${current}: schema path must not contain symbolic links`);
+    const final = current === path;
+    if (final ? !stat.isFile() : !stat.isDirectory()) {
+      fail('INVALID_CONFIG', `${current}: schema path must use ordinary directories and a regular file`);
+    }
+  }
+  return true;
+}
+
+export function selectSchema(root, schemaPath) {
+  if (schemaPath?.[selectedSchema] === true && contained(root, schemaPath.path)) {
+    inspectSchema(root, schemaPath.path, schemaPath.explicit);
+    return schemaPath;
+  }
+  if (schemaPath !== undefined) {
+    if (!isText(schemaPath) || schemaPath.includes('\0')) fail('INVALID_INPUT', 'schemaPath must be a non-empty project file path');
+    const path = resolve(root, schemaPath);
+    if (!contained(root, path)) fail('INVALID_INPUT', 'schemaPath must stay inside the selected project');
+    inspectSchema(root, path, true);
+    return { path, explicit: true, [selectedSchema]: true };
+  }
+  const preferred = join(root, defaultSchema);
+  const legacy = join(root, legacySchema);
+  const hasPreferred = inspectSchema(root, preferred, false);
+  const hasLegacy = inspectSchema(root, legacy, false);
+  if (hasPreferred && hasLegacy) {
+    fail('INVALID_CONFIG', `${defaultSchema} and ${legacySchema} both exist; select one explicitly with schemaPath or --schema-path`);
+  }
+  return { path: hasLegacy ? legacy : preferred, explicit: false, [selectedSchema]: true };
+}
+
+function readConfig(path, budget, explicit, directory) {
+  const config = readJson(path, budget, !explicit);
+  if (config === undefined) return undefined;
+  const invalid = (message) => fail('INVALID_CONFIG', `${path}: ${message}`);
+  if (!isObject(config) || !isObject(config.stores) || Object.keys(config.stores).length === 0) {
+    invalid('stores must be a non-empty object');
+  }
+  for (const [name, store] of Object.entries(config.stores)) {
+    if (!storeName(name) || (dirname(path) === directory && name === basename(path))) {
+      invalid(`invalid or reserved store name ${name}`);
+    }
+    if (!isObject(store) || !isStrings(store.statuses) || store.statuses.length === 0) {
+      invalid(`store ${name} must define a non-empty statuses array`);
+    }
+    if (store.validate !== undefined && typeof store.validate !== 'boolean') {
+      invalid(`store ${name} validate must be a boolean`);
+    }
+  }
+  for (const [name, store] of Object.entries(config.stores)) {
+    if (Object.hasOwn(store, 'missing_status') && (!isText(store.missing_status)
+      || !store.statuses.includes(store.missing_status)
+      || ['in_progress', 'review', ...(Array.isArray(config.working_statuses) ? config.working_statuses : [])].includes(store.missing_status))) {
+      invalid(`store ${name} missing_status must name a status in stores["${name}"].statuses that is not a working status; set a compatible missing_status manually`);
+    }
+  }
+  const statuses = new Set(Object.values(config.stores).flatMap((store) => store.statuses));
+  validateFieldRules(config.fields, path, statuses);
+  for (const [name, store] of Object.entries(config.stores)) {
+    validateFieldRules(store.fields, `${path}: store ${name}`, statuses);
+  }
+  if (config.format !== undefined && !['standard', 'minimal'].includes(config.format)) {
+    invalid('format must be standard or minimal');
+  }
+  if (config.default_status !== undefined && (!isText(config.default_status) || !statuses.has(config.default_status))) {
+    invalid('default_status must be a declared status');
+  }
+  if (config.working_statuses !== undefined && (!isStrings(config.working_statuses)
+    || !config.working_statuses.every((status) => statuses.has(status)))) {
+    invalid('working_statuses must be an array of declared statuses');
+  }
+  if (config.plan !== undefined && (!isObject(config.plan)
+    || (config.plan.required_for_statuses !== undefined && !isStrings(config.plan.required_for_statuses)))) {
+    invalid('plan.required_for_statuses must be an array of non-empty strings');
+  }
+  if (config.search !== undefined) {
+    if (!isObject(config.search)) invalid('search must be an object');
+    const unknown = Object.keys(config.search).find((key) => key !== 'mode');
+    if (unknown) invalid(`unknown search setting ${unknown}`);
+    if (config.search.mode !== undefined && !['scan', 'indexed', 'auto'].includes(config.search.mode)) {
+      invalid('search.mode must be scan, indexed or auto');
+    }
+  }
+  if (config.groups !== undefined) {
+    if (!isObject(config.groups)) invalid('groups must map Active, Done or Archive to status arrays');
+    const seen = new Set();
+    const statuses = new Set(Object.values(config.stores).flatMap((store) => store.statuses));
+    for (const [group, members] of Object.entries(config.groups)) {
+      if (!Object.hasOwn(standardGroups, group) || !isStrings(members)) {
+        invalid(`invalid group ${group}; use Active, Done or Archive with status arrays`);
+      }
+      for (const status of members) {
+        if (seen.has(status)) invalid(`status ${status} belongs to more than one group`);
+        if (!statuses.has(status)) invalid(`group status ${status} is not declared in stores`);
+        seen.add(status);
+      }
+    }
+    for (const status of statuses) {
+      if (!seen.has(status)) invalid(`status ${status} needs an activity group`);
+    }
+  }
+  return config;
+}
+
+function checkPending(directory) {
+  if (existsSync(join(directory, pendingFile))) {
+    fail('RECOVERY_REQUIRED', 'a lifecycle move is pending; run validation to recover before reading tasks');
+  }
+}
+
+export function openProject(projectPath, budget = projectBudget(), allowPending = false, prepare = true, schemaPath) {
+  if (!isText(projectPath)) fail('INVALID_INPUT', 'select one project with an explicit directory path');
+  const root = resolve(projectPath);
+  try {
+    if (!statSync(root).isDirectory()) fail('PROJECT_NOT_FOUND', `${root}: project path must be a directory`);
+  } catch (error) {
+    if (error.code === 'PROJECT_NOT_FOUND') throw error;
+    fail(error.code === 'ENOENT' ? 'PROJECT_NOT_FOUND' : 'READ_ERROR', `${root}: cannot open project (${error.code})`);
+  }
+  const directory = join(root, 'tasks');
+  const schema = selectSchema(root, schemaPath);
+  const config = readConfig(schema.path, budget, schema.explicit, directory);
+  if (prepare) prepareService({ root, directory, schema, schemaPath: schema.path });
+  if (!allowPending) checkPending(directory);
+  let available;
+  try {
+    const schemaName = dirname(schema.path) === directory ? basename(schema.path) : undefined;
+    available = readdirSync(directory).filter((name) => name.endsWith('.json')
+      && ![serviceFile, 'task-schema.json', schemaName].includes(name)).sort();
+  } catch (error) {
+    fail('READ_ERROR', `${directory}: cannot list task stores (${error.code}); check the directory and permissions`);
+  }
+  // Done and Archive are optional in existing projects that only have Active.
+  const stores = config?.stores ?? Object.fromEntries(Object.entries(standardStores)
+    .filter(([name]) => name === 'active.json' || available.includes(name)));
+  const groups = new Map();
+  if (config?.groups !== undefined) {
+    for (const [group, statuses] of Object.entries(config.groups)) {
+      for (const status of statuses) groups.set(status, group);
+    }
+  } else {
+    for (const [group, statuses] of Object.entries(standardGroups)) {
+      for (const status of statuses) groups.set(status, group);
+    }
+    const inferred = new Map();
+    for (const [name, store] of Object.entries(stores)) {
+      const group = fileGroups[name];
+      if (!group) continue;
+      for (const status of store.statuses) {
+        if (inferred.has(status) && inferred.get(status) !== group) {
+          fail('INVALID_CONFIG', `${schema.path}: ambiguous group for ${status}; configure groups explicitly`);
+        }
+        inferred.set(status, group);
+        groups.set(status, group);
+      }
+    }
+  }
+  for (const status of config?.working_statuses ?? []) {
+    if (groups.get(status) !== 'Active') {
+      fail('INVALID_CONFIG', `${schema.path}: working status ${status} must map to Active`);
+    }
+  }
+  return { root, directory, available, stores, groups, budget, config, schema, schemaPath: schema.path };
+}
+
+export function checkSelection({ stores = [], group } = {}) {
+  if (!Array.isArray(stores) || !stores.every(isText)) fail('INVALID_INPUT', 'stores must be an array of store names');
+  if (group !== undefined && !Object.hasOwn(standardGroups, group)) {
+    fail('INVALID_INPUT', 'group must be Active, Done or Archive');
+  }
+  if (stores.length && group !== undefined) fail('INVALID_INPUT', 'select stores or an activity group, not both');
+  if (stores.includes('all') && stores.length !== 1) fail('INVALID_INPUT', 'all must be the only requested store');
+  for (const entry of stores) {
+    if (entry !== 'all' && !storeName(entry.endsWith('.json') ? entry : `${entry}.json`)) {
+      fail('INVALID_INPUT', `invalid or reserved store ${entry}`);
+    }
+  }
+}
+
+function isUninitialised(project) {
+  if (project.config !== undefined) return false;
+  const service = readService(project);
+  if (knownCounter(service) !== 0) return false;
+  if (service.validated === undefined) return true;
+  const { validated } = service;
+  if (!isObject(validated) || validated.counter !== 0 || !isObject(validated.files)) return false;
+  const schema = projectRelative(project.root, project.schemaPath);
+  return Object.entries(validated.files).every(([path, hash]) => path === schema && hash === null);
+}
+
+export function selectStoreFiles(project, { stores = [], group } = {}) {
+  checkPending(project.directory);
+  checkSelection({ stores, group });
+  const uninitialised = !project.available.length && isUninitialised(project);
+  if (!project.available.length && !uninitialised) {
+    fail('READ_ERROR', `${project.directory}: no task stores exist; create a task first`);
+  }
+  const selectedGroup = stores.length ? undefined : (group ?? 'Active');
+  const known = [...new Set([...Object.keys(project.stores), ...project.available])].sort();
+  let files;
+  if (selectedGroup !== undefined) {
+    files = Object.keys(project.stores).filter((name) => project.stores[name].statuses
+      .some((status) => project.groups.get(status) === selectedGroup)).sort();
+    if (selectedGroup === 'Active' && files.length === 0) {
+      fail('INVALID_CONFIG', `no stores map to Active; configure groups in ${relative(project.root, project.schemaPath)} or select --store explicitly`);
+    }
+  } else if (stores.includes('all')) {
+    files = known;
+  } else {
+    files = [...new Set(stores.map((entry) => {
+      const name = entry.endsWith('.json') ? entry : `${entry}.json`;
+      if (!known.includes(name)) {
+        fail('INVALID_INPUT', `unknown or reserved store ${entry}; available: ${known.join(', ')}`);
+      }
+      return name;
+    }))].sort();
+  }
+  return { files: uninitialised ? [] : files, selectedGroup };
+}
+
+// Keep persisted records separate: inference is read-only until an actual mutation.
+export function effectiveRecord(task, project, file, label) {
+  if (!isObject(task) || Object.hasOwn(task, 'status')) return task;
+  const status = project.stores[file]?.missing_status;
+  if (status === undefined) {
+    const correction = project.config === undefined
+      ? 'set an explicit status on this record or configure its store with a non-working missing_status'
+      : `set stores["${file}"].missing_status in ${project.schemaPath} to a declared non-working status allowed by this store`;
+    fail('INVALID_STORE', `${label}: missing status; ${correction}; no fallback is configured for ${file}`);
+  }
+  return { ...task, status };
+}
+
+export function recordEntries(project, options = {}) {
+  const { files, selectedGroup } = selectStoreFiles(project, options);
+  const entries = (function* iterate() {
+    const seen = new Map();
+    for (const file of files) {
+      const path = join(project.directory, file);
+      const { records: tasks } = readArray(path, project.budget);
+      for (const { value, index } of tasks) {
+        const label = `${path}[${index}]`;
+        let task = value;
+        if (!isObject(task)) {
+          fail('INVALID_STORE', `${label}: task must be an object; correct this record to include id, title and status`);
+        }
+        if (Number.isSafeInteger(task.id) && task.id > 0 && isText(task.title)) task = effectiveRecord(task, project, file, label);
+        const invalidField = !Number.isSafeInteger(task.id) || task.id <= 0 ? 'id'
+          : !isText(task.title) ? 'title' : !isText(task.status) ? 'status' : undefined;
+        if (invalidField) {
+          const expected = invalidField === 'id' ? 'a positive safe integer unique across retained tasks'
+            : invalidField === 'status' ? "a non-empty string matching the project's workflow" : 'a non-empty string';
+          const problem = Object.hasOwn(task, invalidField) ? 'incompatible' : 'missing';
+          fail('INVALID_STORE', `${label}: ${problem} ${invalidField}; set ${invalidField} to ${expected}. Schema rules cannot waive this read minimum`);
+        }
+        validateTimestamp(task, label);
+        const rules = project.stores[file];
+        if (rules && rules.validate !== false && !rules.statuses.includes(task.status)) {
+          fail('INVALID_STORE', `${label}: status ${task.status} is not allowed in ${file}; expected ${rules.statuses.join(', ')}`);
+        }
+        if (seen.has(task.id)) fail('INVALID_STORE', `${label}: duplicate id ${task.id}; first seen at ${seen.get(task.id)}`);
+        seen.set(task.id, label);
+        if (selectedGroup === undefined || project.groups.get(task.status) === selectedGroup) {
+          yield { record: task, store: file };
+        }
+      }
+    }
+    checkPending(project.directory);
+  }());
+  return { entries, stores: files };
+}
+
+export function readRecords(project, options = {}) {
+  const source = recordEntries(project, options);
+  const entries = [...source.entries];
+  return { records: entries.map((entry) => entry.record), entries, stores: source.stores };
+}
+
+export function retainedFiles(project) {
+  return [...new Set([...project.available, ...Object.keys(project.stores)])]
+    .filter((name) => project.available.includes(name) || !Object.hasOwn(standardStores, name)).sort();
+}

package/src/tasks.mjs

@@ -0,0 +1,290 @@
+import { fail } from './errors.mjs';
+import { advise, cacheFallback, cacheSupported, cacheUnavailable, checkCacheOptions, onceAdvisory } from './cache.mjs';
+import { cursorBinding, decodeCursor, encodeCursor } from './cursor.mjs';
+import { checkFields, defaultFields, fieldsFor, ownValue, projectFields } from './fields.mjs';
+import { projectBudget } from './input.mjs';
+import { defaultLimit, maxLimit, responseBytes } from './limits.mjs';
+import { taskPage } from './pagination.mjs';
+import { jsonBytes } from './response.mjs';
+import {
+  indexedList, indexedTask, indexedTasks, scheduleSearchRefresh, searchSourceState,
+} from './search-index.mjs';
+import { checkSelection, defaultSearch, openProject, recordEntries } from './stores.mjs';
+
+const priorityRank = new Map([['high', 0], ['medium', 1], ['low', 2]]);
+const isText = (value) => typeof value === 'string' && value.trim() !== '';
+
+function checkOptions(options) {
+  if (options === null || typeof options !== 'object' || Array.isArray(options)) {
+    fail('INVALID_INPUT', 'options must be an object');
+  }
+}
+
+function matches(actual, expected) {
+  if (actual === undefined || actual === null) return false;
+  if (Array.isArray(actual)) return actual.some((value) => matches(value, expected));
+  if (typeof actual === 'number' || typeof actual === 'boolean') return String(actual) === expected;
+  const text = typeof actual === 'object' ? JSON.stringify(actual) : String(actual);
+  return text.toLowerCase().includes(expected.toLowerCase());
+}
+
+function compareValues(left, right) {
+  if (left === right) return 0;
+  if (left === undefined || left === null) return right === undefined || right === null ? 0 : 1;
+  if (right === undefined || right === null) return -1;
+  if (typeof left === 'number' && typeof right === 'number') return left - right;
+  const a = typeof left === 'object' ? JSON.stringify(left) : String(left);
+  const b = typeof right === 'object' ? JSON.stringify(right) : String(right);
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function compareTasks(left, right, sort, descending) {
+  const a = sort === 'priority' ? (priorityRank.get(left.priority) ?? 1) : ownValue(left, sort);
+  const b = sort === 'priority' ? (priorityRank.get(right.priority) ?? 1) : ownValue(right, sort);
+  return compareValues(a, b) * (descending ? -1 : 1) || left.id - right.id;
+}
+
+function keepBest(heap, record, capacity, compare) {
+  if (capacity === 0) return;
+  if (heap.length < capacity) {
+    heap.push(record);
+    let index = heap.length - 1;
+    while (index > 0) {
+      const parent = Math.floor((index - 1) / 2);
+      if (compare(heap[parent], heap[index]) >= 0) break;
+      [heap[parent], heap[index]] = [heap[index], heap[parent]];
+      index = parent;
+    }
+  } else if (compare(record, heap[0]) < 0) {
+    heap[0] = record;
+    let index = 0;
+    while (index * 2 + 1 < heap.length) {
+      let child = index * 2 + 1;
+      if (child + 1 < heap.length && compare(heap[child], heap[child + 1]) < 0) child++;
+      if (compare(heap[index], heap[child]) >= 0) break;
+      [heap[index], heap[child]] = [heap[child], heap[index]];
+      index = child;
+    }
+  }
+}
+
+function selectTasks(projectPath, options, countOnly = false) {
+  checkOptions(options);
+  const { stores = [], group, fields = defaultFields, filters = [], ids = [], sort = 'id',
+    descending = false, limit = defaultLimit, offset = 0, schemaPath, refreshMode = 'local',
+    noCache = false, onAdvisory } = options;
+  checkCacheOptions(noCache, onAdvisory);
+  const notify = onceAdvisory(onAdvisory);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxLimit) fail('INVALID_INPUT', `limit must be an integer from 1 to ${maxLimit}`);
+  if (!Number.isSafeInteger(offset) || offset < 0) fail('INVALID_INPUT', 'offset must be a non-negative safe integer');
+  if (!isText(sort) || typeof descending !== 'boolean') fail('INVALID_INPUT', 'sort must be a field name and descending must be a boolean');
+  if (!Array.isArray(ids) || !ids.every((id) => Number.isSafeInteger(id) && id > 0)) {
+    fail('INVALID_INPUT', 'ids must be an array of positive safe integers');
+  }
+  if (!Array.isArray(filters) || !filters.every((filter) => filter && isText(filter.field) && typeof filter.value === 'string')) {
+    fail('INVALID_INPUT', 'filters must contain field names and string values');
+  }
+  fieldsFor(fields, []);
+  checkSelection({ stores, group });
+  const budget = projectBudget();
+  budget.fingerprints = {};
+  const project = openProject(projectPath, budget, false, true, schemaPath);
+  const useCache = !noCache && cacheSupported(notify);
+  const state = useCache ? searchSourceState(project) : undefined;
+  const replica = useCache ? indexedList(project, state, { stores, group }, { filters, ids, sort }) : undefined;
+  if (replica && !replica.mixedSort) {
+    try {
+      const fieldRecord = Object.fromEntries(replica.available.map((field) => [field, null]));
+      const projection = fieldsFor(fields, replica.sourceTotal ? [fieldRecord] : []);
+      checkFields([...projection, sort, ...filters.map((filter) => filter.field)], replica.sourceTotal ? [fieldRecord] : []);
+      return {
+        records: countOnly ? [] : replica.records(offset, limit, descending), stores: replica.stores,
+        fields: projection, sort, descending, limit, offset, total: replica.count,
+        recordsOffset: 0, preSorted: true,
+      };
+    } finally {
+      replica.close();
+    }
+  }
+  if (useCache && !replica?.mixedSort) {
+    try { scheduleSearchRefresh(project.root, { schemaPath, detached: refreshMode === 'detached' }); }
+    catch { advise(notify, cacheUnavailable); }
+  }
+  const source = recordEntries(project, { stores, group });
+  const available = {};
+  const selected = [];
+  const wanted = new Set(ids);
+  const compare = (left, right) => compareTasks(left, right, sort, descending);
+  const deepPage = !countOnly && offset + limit > 10_000;
+  const capacity = countOnly || deepPage ? 0 : offset + limit;
+  const scanBudget = project.budget.remaining;
+  let total = 0;
+  let sourceTotal = 0;
+  const selectedTask = (record) => (!ids.length || wanted.has(record.id)) && filters.every(({ field, value }) => {
+    const actual = ownValue(record, field);
+    return field === 'status' ? actual === value : matches(actual, value);
+  });
+  for (const { record } of source.entries) {
+    sourceTotal++;
+    for (const field of Object.keys(record)) available[field] = null;
+    if (selectedTask(record)) {
+      total++;
+      keepBest(selected, record, capacity, compare);
+    }
+  }
+  const fieldRecords = sourceTotal ? [available] : [];
+  const projection = fieldsFor(fields, fieldRecords);
+  checkFields([...projection, sort, ...filters.map((filter) => filter.field)], fieldRecords);
+  if (deepPage && offset < total) {
+    const sourceHashes = { ...project.budget.fingerprints };
+    const fromEnd = total - offset < offset + limit;
+    const pageSize = fromEnd ? total - offset : offset + limit;
+    const rank = fromEnd ? (left, right) => -compare(left, right) : compare;
+    project.budget = { remaining: scanBudget, limit: budget.limit, fingerprints: {} };
+    const again = recordEntries(project, { stores, group });
+    for (const { record } of again.entries) {
+      if (selectedTask(record)) keepBest(selected, record, pageSize, rank);
+    }
+    if (Object.entries(project.budget.fingerprints).some(([path, hash]) => sourceHashes[path] !== hash)) {
+      fail('PROJECT_CHANGED', 'task files changed during listing; retry after edits finish');
+    }
+    selected.sort(compare);
+    return { records: fromEnd ? selected.slice(0, limit) : selected.slice(offset),
+      stores: source.stores, fields: projection, sort, descending, limit, offset, total,
+      recordsOffset: 0, preSorted: true };
+  }
+  if (!countOnly) selected.sort(compare);
+  return { records: selected.slice(offset), stores: source.stores, fields: projection,
+    sort, descending, limit, offset, total, recordsOffset: 0, preSorted: true };
+}
+
+export function countTasks(projectPath, options = {}) {
+  const query = selectTasks(projectPath, options, true);
+  return query.total ?? query.records.length;
+}
+
+export function listTasks(projectPath, options = {}) {
+  const query = selectTasks(projectPath, options);
+  const { sort, descending } = query;
+  if (!query.preSorted) query.records.sort((left, right) => compareTasks(left, right, sort, descending));
+  return taskPage(query.records, query);
+}
+
+export function getTask(projectPath, id, options = {}) {
+  checkOptions(options);
+  const { stores = [], group, fields = ['all'], schemaPath, refreshMode = 'local',
+    noCache = false, onAdvisory } = options;
+  checkCacheOptions(noCache, onAdvisory);
+  const notify = onceAdvisory(onAdvisory);
+  if (!Number.isSafeInteger(id) || id <= 0) fail('INVALID_INPUT', 'id must be a positive safe integer');
+  fieldsFor(fields, []);
+  checkSelection({ stores, group });
+  const budget = projectBudget();
+  budget.fingerprints = {};
+  const project = openProject(projectPath, budget, false, true, schemaPath);
+  const useCache = !noCache && cacheSupported(notify);
+  const state = useCache ? searchSourceState(project) : undefined;
+  const replica = useCache ? indexedTask(project, state, { stores, group }, id) : undefined;
+  let task;
+  let files;
+  if (replica) {
+    task = replica.task;
+    files = replica.stores;
+  } else {
+    if (useCache) {
+      try { scheduleSearchRefresh(project.root, { schemaPath, detached: refreshMode === 'detached' }); }
+      catch { advise(notify, cacheUnavailable); }
+    }
+    const source = recordEntries(project, { stores, group });
+    for (const entry of source.entries) {
+      if (entry.record.id === id) task = entry.record;
+    }
+    files = source.stores;
+  }
+  if (!task) fail('TASK_NOT_FOUND', `task ${id} was not found in ${files.join(', ') || 'the selected group'}; select --store all to include history`);
+  const projection = fieldsFor(fields, [task]);
+  checkFields(projection, [task]);
+  const projected = projectFields(task, projection);
+  if (jsonBytes(projected) + 1 > responseBytes) {
+    fail('OUTPUT_TOO_LARGE', `task ${id} exceeds the 32 KiB response budget; select fewer --fields`);
+  }
+  return projected;
+}
+
+export function getTasks(projectPath, ids, options = {}) {
+  checkOptions(options);
+  if (!Array.isArray(ids) || ids.length === 0
+    || !ids.every((id) => Number.isSafeInteger(id) && id > 0)) {
+    fail('INVALID_INPUT', 'ids must be a non-empty array of positive safe integers');
+  }
+  if (new Set(ids).size !== ids.length) fail('INVALID_INPUT', 'ids must not contain duplicates');
+  const { stores = [], group, fields = defaultFields, limit = defaultLimit, cursor,
+    schemaPath, refreshMode = 'local', noCache = false, onAdvisory } = options;
+  checkCacheOptions(noCache, onAdvisory);
+  const notify = onceAdvisory(onAdvisory);
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxLimit) {
+    fail('INVALID_INPUT', `limit must be an integer from 1 to ${maxLimit}`);
+  }
+  fieldsFor(fields, []);
+  checkSelection({ stores, group });
+  const budget = projectBudget();
+  budget.fingerprints = {};
+  const project = openProject(projectPath, budget, false, true, schemaPath);
+  const settings = { ...defaultSearch, ...project.config?.search };
+  let source;
+  const useCache = !noCache && settings.mode !== 'scan' && cacheSupported(notify);
+  if (useCache) {
+    const state = searchSourceState(project);
+    source = indexedTasks(project, state, { stores, group }, ids);
+  }
+  if (!source) {
+    const scan = recordEntries(project, { stores, group });
+    const wanted = new Set(ids);
+    const records = new Map();
+    for (const entry of scan.entries) {
+      if (wanted.has(entry.record.id)) records.set(entry.record.id, entry.record);
+    }
+    source = { records: ids.flatMap((id) => records.has(id) ? [records.get(id)] : []), stores: scan.stores };
+    if (useCache) {
+      try {
+        scheduleSearchRefresh(project.root, { schemaPath, detached: refreshMode === 'detached' });
+        if (settings.mode === 'indexed') advise(notify, cacheFallback);
+      }
+      catch { advise(notify, cacheUnavailable); }
+    }
+  }
+  const projection = fieldsFor(fields, source.records);
+  checkFields(projection, source.records);
+  const binding = cursorBinding({
+    ids, fields: projection, group: group ?? (stores.length ? null : 'Active'),
+    stores: [...new Set(stores)].sort(),
+  });
+  const offset = decodeCursor(cursor, binding, 'batch request');
+  if (offset > ids.length) fail('INVALID_CURSOR', 'cursor is past the requested IDs; start a new batch request');
+  const found = new Map(source.records.map((record) => [record.id, record]));
+  const page = {
+    tasks: [], not_found: [], hasMore: false, next_cursor: null,
+    stores: source.stores, fields: projection,
+  };
+  if (jsonBytes(page) + 1 > responseBytes) {
+    fail('OUTPUT_TOO_LARGE', 'batch metadata exceeds 32 KiB; select fewer --fields or stores');
+  }
+  for (let index = offset; index < ids.length && index < offset + limit; index++) {
+    const task = found.get(ids[index]);
+    if (task) page.tasks.push(projectFields(task, projection));
+    else page.not_found.push(ids[index]);
+    page.hasMore = index + 1 < ids.length;
+    page.next_cursor = page.hasMore ? encodeCursor(index + 1, binding) : null;
+    if (jsonBytes(page) + 1 > responseBytes) {
+      if (task) page.tasks.pop();
+      else page.not_found.pop();
+      page.hasMore = true;
+      page.next_cursor = encodeCursor(index, binding);
+      if (!page.tasks.length && !page.not_found.length) {
+        fail('OUTPUT_TOO_LARGE', `task ${ids[index]} cannot fit in a 32 KiB batch page; select fewer --fields`);
+      }
+      break;
+    }
+  }
+  return page;
+}

package/src/timestamps.mjs

@@ -0,0 +1,22 @@
+import { fail } from './errors.mjs';
+
+export function timestampValue(value, code = 'INVALID_STORE', label = 'updated_at') {
+  const milliseconds = typeof value === 'string' ? Date.parse(value) : NaN;
+  if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value) {
+    fail(code, `${label} must be a canonical UTC millisecond timestamp, for example 2026-09-19T12:00:00.000Z`);
+  }
+  return milliseconds;
+}
+
+export function validateTimestamp(task, label) {
+  if (task.updated_at !== undefined) timestampValue(task.updated_at, 'INVALID_STORE', `${label}: updated_at`);
+}
+
+export function nextTimestamp(previous) {
+  const minimum = previous === undefined ? -Infinity : timestampValue(previous) + 1;
+  const milliseconds = Math.max(Date.now(), minimum);
+  if (!Number.isFinite(milliseconds) || Math.abs(milliseconds) > 8640000000000000) {
+    fail('TIMESTAMP_EXHAUSTED', 'updated_at cannot advance beyond the supported date range; correct the task timestamp before changing it');
+  }
+  return new Date(milliseconds).toISOString();
+}