@astralyn/pi 0.87.2 → 0.87.3

package/dist/extensions/todo/state.js

@@ -1,19 +1,18 @@
 /**
- * todo/state.ts — v2 pure state core: closure-scoped store, atomic actions,
- * snapshot cloning, and branch replay. No session registry, metadata,
- * dependency graph, tombstones, filters, or legacy normalizers.
+ * todo/state.ts — v3 pure state core: closure-scoped store, atomic patch
+ * application (delete, then update, then create), snapshot cloning, and
+ * branch replay. No session registry, metadata, dependency graph, tombstones,
+ * filters, or legacy normalizers.
+ *
+ * The patch shape is designed so every value a strict sampler may fill in for
+ * an unused field ([], "", null already stripped by validation) is a no-op:
+ * empty groups do nothing, blank update text keeps the current value, and
+ * deleting an absent id is recorded rather than rejected.
  */
 import { TODO_MAX_BATCH_ITEMS, TODO_MAX_DESCRIPTION_LENGTH, TODO_MAX_ITEMS, TODO_MAX_SUBJECT_LENGTH, TODO_TOOL_NAME, } from "./constants.js";
 import { EMPTY_TODO_STATE, TODO_DETAILS_SCHEMA_VERSION, } from "./schema.js";
 const TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
-const TODO_ACTIONS = new Set(["create", "update", "list", "delete"]);
-/** Parameters each action accepts; anything else is rejected with guidance. */
-const ACTION_PARAMS = {
-    create: new Set(["items"]),
-    update: new Set(["id", "subject", "description", "status"]),
-    list: new Set([]),
-    delete: new Set(["ids"]),
-};
+const GROUP_FIELDS = new Set(["create", "update", "delete"]);
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -23,12 +22,6 @@ function isPositiveSafeInteger(value) {
 function isTodoStatus(value) {
     return typeof value === "string" && TODO_STATUSES.has(value);
 }
-function isTodoAction(value) {
-    return typeof value === "string" && TODO_ACTIONS.has(value);
-}
-function findItem(state, id) {
-    return state.items.find((item) => item.id === id);
-}
 /** De-duplicate ids preserving first-seen input order. */
 function dedupeIds(ids) {
     const seen = [];
@@ -42,7 +35,8 @@ function dedupeIds(ids) {
 function normalizeText(value) {
     return value.trim().replace(/\s+/g, " ");
 }
-function validateNormalizedText(value, label, maximum) {
+/** Required text (create): normalized, non-empty, within the limit. */
+function validateRequiredText(value, label, maximum) {
     if (typeof value !== "string")
         throw new Error(`${label} must be a string`);
     const normalized = normalizeText(value);
@@ -52,170 +46,260 @@ function validateNormalizedText(value, label, maximum) {
         throw new Error(`${label} exceeds ${maximum} characters`);
     return normalized;
 }
-function findInapplicableParam(params) {
-    const allowed = ACTION_PARAMS[params.action];
-    for (const [key, value] of Object.entries(params)) {
-        if (key === "action" || value === undefined)
-            continue;
-        if (!allowed.has(key))
-            return `${key} does not apply to action ${params.action}`;
-    }
-    return undefined;
+/**
+ * Optional text (update): normalized and within the limit, where blank means
+ * "keep the current value" (undefined) so strict-mode filler stays harmless.
+ */
+function validateOptionalText(value, label, maximum) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`${label} must be a string`);
+    const normalized = normalizeText(value);
+    if (!normalized)
+        return undefined;
+    if (normalized.length > maximum)
+        throw new Error(`${label} exceeds ${maximum} characters`);
+    return normalized;
 }
-/** Snapshot clone: items are plain string/number records, so a shallow copy is safe. */
-export function cloneTodoState(state) {
-    return { items: state.items.map((item) => ({ ...item })), nextId: state.nextId };
+function validateOptionalStatus(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (!isTodoStatus(value))
+        throw new Error(`${label} is invalid`);
+    return value;
 }
-function applyCreate(state, params) {
-    const rawItems = params.items;
-    if (!Array.isArray(rawItems) || rawItems.length === 0)
-        throw new Error("items required for create");
-    if (rawItems.length > TODO_MAX_BATCH_ITEMS)
-        throw new Error(`items exceeds ${TODO_MAX_BATCH_ITEMS} tasks`);
-    if (state.items.length + rawItems.length > TODO_MAX_ITEMS) {
-        throw new Error(`todo list is full (max ${TODO_MAX_ITEMS} tasks); delete completed or obsolete tasks first`);
-    }
-    if (!Number.isSafeInteger(state.nextId) || state.nextId < 1)
-        throw new Error("next id is invalid");
-    if (state.nextId > Number.MAX_SAFE_INTEGER - rawItems.length)
-        throw new Error("next id is exhausted");
-    const sources = [];
-    for (let index = 0; index < rawItems.length; index++) {
-        const raw = rawItems[index];
-        if (!isRecord(raw))
-            throw new Error(`items[${index}] must be an object`);
-        for (const key of Object.keys(raw)) {
-            if (key !== "subject" && key !== "description") {
-                throw new Error(`items[${index}].${key} does not apply to action create`);
+function readCreateEntries(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error("create must be an array");
+    if (raw.length > TODO_MAX_BATCH_ITEMS)
+        throw new Error(`create exceeds ${TODO_MAX_BATCH_ITEMS} tasks`);
+    const entries = [];
+    for (let index = 0; index < raw.length; index++) {
+        const item = raw[index];
+        if (!isRecord(item))
+            throw new Error(`create[${index}] must be an object`);
+        for (const key of Object.keys(item)) {
+            if (key !== "subject" && key !== "description" && key !== "status") {
+                throw new Error(`create[${index}].${key} is not a create field; valid fields: subject, description, status`);
             }
         }
-        sources.push({
-            subject: validateNormalizedText(raw.subject, `items[${index}].subject`, TODO_MAX_SUBJECT_LENGTH),
-            description: validateNormalizedText(raw.description, `items[${index}].description`, TODO_MAX_DESCRIPTION_LENGTH),
-        });
+        const entry = {
+            subject: validateRequiredText(item.subject, `create[${index}].subject`, TODO_MAX_SUBJECT_LENGTH),
+            description: validateRequiredText(item.description, `create[${index}].description`, TODO_MAX_DESCRIPTION_LENGTH),
+        };
+        const status = validateOptionalStatus(item.status, `create[${index}].status`);
+        if (status !== undefined)
+            entry.status = status;
+        entries.push(entry);
     }
-    // Atomic: everything above is validated before the new state is built.
-    const created = sources.map((source, index) => ({
-        id: state.nextId + index,
-        subject: source.subject,
-        description: source.description,
-        status: "pending",
-    }));
-    return { items: [...state.items, ...created], nextId: state.nextId + created.length };
+    return entries;
 }
-function applyUpdate(state, params) {
-    const id = params.id;
-    if (!isPositiveSafeInteger(id))
-        throw new Error("id required for update");
-    const index = state.items.findIndex((item) => item.id === id);
-    if (index === -1)
-        throw new Error(`#${id} not found`);
-    if (params.subject === undefined && params.description === undefined && params.status === undefined) {
-        throw new Error("update requires at least one of subject, description, or status");
-    }
-    const subject = params.subject === undefined
-        ? undefined
-        : validateNormalizedText(params.subject, "subject", TODO_MAX_SUBJECT_LENGTH);
-    const description = params.description === undefined
-        ? undefined
-        : validateNormalizedText(params.description, "description", TODO_MAX_DESCRIPTION_LENGTH);
-    if (params.status !== undefined && !isTodoStatus(params.status))
-        throw new Error("status is invalid");
-    const current = state.items[index];
-    const updated = {
-        id: current.id,
-        subject: subject ?? current.subject,
-        description: description ?? current.description,
-        status: params.status ?? current.status,
-    };
-    // Exactly one in_progress: setting one demotes every other active task.
-    const items = state.items.map((item, itemIndex) => {
-        if (itemIndex === index)
-            return updated;
-        if (updated.status === "in_progress" && item.status === "in_progress") {
-            return { ...item, status: "pending" };
+function readUpdateEntries(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error("update must be an array");
+    if (raw.length > TODO_MAX_BATCH_ITEMS)
+        throw new Error(`update exceeds ${TODO_MAX_BATCH_ITEMS} tasks`);
+    const entries = [];
+    for (let index = 0; index < raw.length; index++) {
+        const item = raw[index];
+        if (!isRecord(item))
+            throw new Error(`update[${index}] must be an object`);
+        for (const key of Object.keys(item)) {
+            if (key !== "id" && key !== "subject" && key !== "description" && key !== "status") {
+                throw new Error(`update[${index}].${key} is not an update field; valid fields: id, subject, description, status`);
+            }
         }
-        return item;
-    });
-    return { items, nextId: state.nextId };
+        if (!isPositiveSafeInteger(item.id))
+            throw new Error(`update[${index}].id must be a positive integer`);
+        const entry = { id: item.id };
+        const subject = validateOptionalText(item.subject, `update[${index}].subject`, TODO_MAX_SUBJECT_LENGTH);
+        if (subject !== undefined)
+            entry.subject = subject;
+        const description = validateOptionalText(item.description, `update[${index}].description`, TODO_MAX_DESCRIPTION_LENGTH);
+        if (description !== undefined)
+            entry.description = description;
+        const status = validateOptionalStatus(item.status, `update[${index}].status`);
+        if (status !== undefined)
+            entry.status = status;
+        entries.push(entry);
+    }
+    return entries;
 }
-function applyDelete(state, params) {
-    const rawIds = params.ids;
-    if (!Array.isArray(rawIds) || rawIds.length === 0)
-        throw new Error("ids required for delete");
-    if (rawIds.length > TODO_MAX_BATCH_ITEMS)
-        throw new Error(`ids exceeds ${TODO_MAX_BATCH_ITEMS} ids`);
+function readDeleteIds(raw) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error("delete must be an array");
+    if (raw.length > TODO_MAX_BATCH_ITEMS)
+        throw new Error(`delete exceeds ${TODO_MAX_BATCH_ITEMS} ids`);
     const ids = [];
-    for (const raw of rawIds) {
-        if (!isPositiveSafeInteger(raw))
-            throw new Error("ids must contain positive integer ids");
-        ids.push(raw);
+    for (let index = 0; index < raw.length; index++) {
+        if (!isPositiveSafeInteger(raw[index]))
+            throw new Error(`delete[${index}] must be a positive integer id`);
+        ids.push(raw[index]);
     }
-    const idsToRemove = dedupeIds(ids);
-    // Atomic: every id must exist before anything is removed.
-    const byId = new Map(state.items.map((item) => [item.id, item]));
-    for (const candidate of idsToRemove) {
-        if (!byId.has(candidate))
-            throw new Error(`#${candidate} not found`);
-    }
-    const remove = new Set(idsToRemove);
-    return { items: state.items.filter((item) => !remove.has(item.id)), nextId: state.nextId };
+    return ids;
+}
+function currentIdsLabel(state) {
+    if (state.items.length === 0)
+        return "the list is empty";
+    return `current ids: ${state.items.map((item) => `#${item.id}`).join(", ")}`;
+}
+/** Snapshot clone: items are plain string/number records, so a shallow copy is safe. */
+export function cloneTodoState(state) {
+    return { items: state.items.map((item) => ({ ...item })), nextId: state.nextId };
 }
 /**
- * Pure action application: validates every runtime input and inapplicable
- * parameter (tool args can be tampered after schema validation), throws on
- * any invalid call, and never mutates the input state.
+ * Pure patch application: validates every runtime input (tool args can be
+ * tampered after schema validation), throws on any invalid call, and never
+ * mutates the input state. Application order is delete, then update, then
+ * create, so a delete in the same call frees capacity for the create.
  */
-export function applyTodoAction(state, params) {
+export function applyTodoPatch(before, params) {
     if (!isRecord(params))
         throw new Error("todo params must be an object");
-    if (!isTodoAction(params.action))
-        throw new Error(`unknown todo action: ${String(params.action)}`);
-    const inapplicable = findInapplicableParam(params);
-    if (inapplicable)
-        throw new Error(inapplicable);
-    switch (params.action) {
-        case "create":
-            return applyCreate(state, params);
-        case "update":
-            return applyUpdate(state, params);
-        case "list":
-            return cloneTodoState(state);
-        case "delete":
-            return applyDelete(state, params);
+    for (const key of Object.keys(params)) {
+        if (!GROUP_FIELDS.has(key))
+            throw new Error(`unknown todo field "${key}"; valid fields: create, update, delete`);
     }
-}
-/** Derive the operation model for one call from the before/after states. */
-export function buildTodoChange(params, before, after) {
-    switch (params.action) {
-        // Derived from the validated before/after states rather than params.items,
-        // which is external input and could read differently on a second access.
-        case "create":
-            return { kind: "create", ids: after.items.slice(before.items.length).map((item) => item.id) };
-        case "update": {
-            const id = params.id;
-            if (!isPositiveSafeInteger(id))
-                throw new Error("id required for update");
-            const demotedId = before.items.find((item) => item.id !== id && item.status === "in_progress" && findItem(after, item.id)?.status === "pending")?.id;
-            return {
-                kind: "update",
-                id,
-                from: findItem(before, id)?.status ?? "pending",
-                to: findItem(after, id)?.status ?? "pending",
-                ...(demotedId !== undefined ? { demotedId } : {}),
+    // Everything above the apply phase is validation: any throw leaves the
+    // caller's state untouched.
+    const createEntries = readCreateEntries(params.create);
+    const updateEntries = readUpdateEntries(params.update);
+    const deleteIds = readDeleteIds(params.delete);
+    // Conflicts: one edit per task per call, and a task cannot be both edited
+    // and removed in the same call.
+    const updatedIds = new Set();
+    for (const entry of updateEntries) {
+        if (updatedIds.has(entry.id))
+            throw new Error(`#${entry.id} appears more than once in update`);
+        updatedIds.add(entry.id);
+    }
+    const deleteSet = new Set(deleteIds);
+    for (const entry of updateEntries) {
+        if (deleteSet.has(entry.id))
+            throw new Error(`#${entry.id} cannot be in both update and delete`);
+    }
+    // Exactly one activation per call: more than one is a real contradiction,
+    // since a single task can be in_progress at any time.
+    const activations = [];
+    createEntries.forEach((entry, index) => {
+        if (entry.status === "in_progress")
+            activations.push(`create[${index}]`);
+    });
+    for (const entry of updateEntries) {
+        if (entry.status === "in_progress")
+            activations.push(`#${entry.id}`);
+    }
+    if (activations.length > 1) {
+        throw new Error(`at most one task may be set in_progress per call; got ${activations.join(" and ")}`);
+    }
+    const byId = new Map(before.items.map((item) => [item.id, item]));
+    for (const entry of updateEntries) {
+        if (!byId.has(entry.id))
+            throw new Error(`#${entry.id} not found; ${currentIdsLabel(before)}`);
+    }
+    if (createEntries.length > 0) {
+        if (!Number.isSafeInteger(before.nextId) || before.nextId < 1)
+            throw new Error("next id is invalid");
+        if (before.nextId > Number.MAX_SAFE_INTEGER - createEntries.length)
+            throw new Error("next id is exhausted");
+    }
+    // --- Apply: delete -------------------------------------------------------
+    const deleted = [];
+    const absent = [];
+    for (const id of dedupeIds(deleteIds)) {
+        const item = byId.get(id);
+        if (item)
+            deleted.push({ id: item.id, subject: item.subject });
+        else
+            absent.push(id);
+    }
+    let items = before.items.filter((item) => !deleteSet.has(item.id));
+    // --- Apply: update -------------------------------------------------------
+    const updated = [];
+    if (updateEntries.length > 0) {
+        const entriesById = new Map(updateEntries.map((entry) => [entry.id, entry]));
+        items = items.map((item) => {
+            const entry = entriesById.get(item.id);
+            if (!entry)
+                return item;
+            const next = {
+                id: item.id,
+                subject: entry.subject ?? item.subject,
+                description: entry.description ?? item.description,
+                status: entry.status ?? item.status,
+            };
+            updated.push({ id: item.id, from: item.status, to: next.status });
+            return next;
+        });
+    }
+    // --- Apply: create -------------------------------------------------------
+    const created = [];
+    if (createEntries.length > 0) {
+        const newItems = createEntries.map((entry, index) => {
+            const item = {
+                id: before.nextId + index,
+                subject: entry.subject,
+                description: entry.description,
+                status: entry.status ?? "pending",
             };
+            return item;
+        });
+        for (const item of newItems)
+            created.push(item.id);
+        items = [...items, ...newItems];
+    }
+    // --- Single in_progress: the one task this call activates demotes the rest.
+    let demotedId;
+    let activatedId;
+    for (const entry of updateEntries) {
+        if (entry.status === "in_progress")
+            activatedId = entry.id;
+    }
+    if (activatedId === undefined) {
+        createEntries.forEach((entry, index) => {
+            if (entry.status === "in_progress")
+                activatedId = before.nextId + index;
+        });
+    }
+    if (activatedId !== undefined) {
+        const demoted = items.find((item) => item.id !== activatedId && item.status === "in_progress");
+        if (demoted) {
+            demotedId = demoted.id;
+            items = items.map((item) => (item.id === demoted.id ? { ...item, status: "pending" } : item));
         }
-        case "list":
-            return { kind: "list" };
-        case "delete": {
-            const ids = Array.isArray(params.ids) ? dedupeIds(params.ids) : [];
-            const removed = ids
-                .map((id) => findItem(before, id))
-                .filter((item) => item !== undefined)
-                .map((item) => ({ id: item.id, subject: item.subject }));
-            return { kind: "delete", removed };
+    }
+    // --- Capacity: completed tasks are reclaimed oldest-first before a call
+    // may fail for space; only a list with more than the cap in open tasks is
+    // rejected.
+    const evicted = [];
+    if (items.length > TODO_MAX_ITEMS) {
+        let overflow = items.length - TODO_MAX_ITEMS;
+        const evictIds = new Set();
+        const completedOldestFirst = items
+            .filter((item) => item.status === "completed")
+            .sort((first, second) => first.id - second.id);
+        for (const item of completedOldestFirst) {
+            if (overflow <= 0)
+                break;
+            evictIds.add(item.id);
+            evicted.push({ id: item.id, subject: item.subject });
+            overflow--;
         }
+        if (overflow > 0)
+            throw new Error(`at most ${TODO_MAX_ITEMS} open tasks; complete or delete some first`);
+        items = items.filter((item) => !evictIds.has(item.id));
     }
+    const change = { created, updated, deleted, absent, evicted };
+    if (demotedId !== undefined)
+        change.demotedId = demotedId;
+    return { state: { items, nextId: before.nextId + created.length }, change };
 }
 export function buildTodoDetails(change, state) {
     return { schemaVersion: TODO_DETAILS_SCHEMA_VERSION, change, state: cloneTodoState(state) };
@@ -237,19 +321,18 @@ export function createTodoStore(initial) {
             state = requireValidState(next);
         },
         execute(params) {
-            const before = state;
-            const after = applyTodoAction(before, params);
-            const details = buildTodoDetails(buildTodoChange(params, before, after), after);
-            state = after;
+            const patch = applyTodoPatch(state, params);
+            const details = buildTodoDetails(patch.change, patch.state);
+            state = patch.state;
             return details;
         },
     };
 }
 /**
- * Validate an external v2 snapshot; returns undefined when malformed.
+ * Validate an external v3 snapshot; returns undefined when malformed.
  *
  * Snapshot text must already be in normalizeText() form, which makes that
- * function's output part of the v2 persistence contract: relaxing or changing
+ * function's output part of the v3 persistence contract: relaxing or changing
  * it would silently invalidate every historical snapshot, falling back to an
  * earlier one or to the empty state with no diagnostic. Change normalizeText
  * only together with TODO_DETAILS_SCHEMA_VERSION.
@@ -296,9 +379,10 @@ function normalizeSnapshotState(value) {
     return { items, nextId: value.nextId };
 }
 /**
- * Replay the newest valid v2 todo snapshot from a branch, scanning tail to
+ * Replay the newest valid v3 todo snapshot from a branch, scanning tail to
  * head so a malformed latest snapshot falls back to an earlier valid one.
- * v1 details are ignored, and the `change` field is not validated.
+ * Older schema versions (v1/v2) are ignored: restoring a session written
+ * before v3 starts from an empty list.
  */
 export function replayTodosFromBranch(ctx) {
     const branch = Array.from(ctx.sessionManager.getBranch());
@@ -321,7 +405,7 @@ export function replayTodosFromBranch(ctx) {
                 return state;
         }
         catch {
-            // Keep scanning for an earlier valid v2 snapshot.
+            // Keep scanning for an earlier valid v3 snapshot.
         }
     }
     return cloneTodoState(EMPTY_TODO_STATE);