@astrosheep/keiyaku 2.9.5 → 2.9.7

package/build/core/projection/tell/store.js

@@ -1,7 +1,6 @@
 import { ProjectionStateError, randomHex8 } from "../../atomic-publish.js";
-import { withRead, withWrite } from "./database.js";
-import { assertTellIdRandomHex, originalFromRow, parseFence, requireExecutionId, submittedFromRow, } from "./model.js";
-const PENDING_TELL_LIMIT = 10_000;
+import { withRead, withReadSnapshot, withWrite } from "./database.js";
+import { assertTellIdRandomHex, originalFromRow, PENDING_PROJECTION_TELL_STATES, parseFence, requireExecutionId, submittedFromRow, } from "./model.js";
 function selectTell(database, tellId) {
     return database.prepare(`
     SELECT
@@ -26,6 +25,77 @@ export function listTellIds(projectionDirectory, state) {
       ORDER BY tell_id
     `).all(state).map((row) => row.tell_id));
 }
+/** List continuation fence metadata without loading operator tell bodies. */
+export function listTellMetadataFromDatabase(database, states) {
+    const placeholders = states.map(() => "?").join(", ");
+    return database.prepare(`
+    SELECT tell_id, state, execution_id, effort
+    FROM projection_tells
+    WHERE state IN (${placeholders})
+    ORDER BY tell_id
+  `).all(...states).map((row) => ({
+        tellId: row.tell_id,
+        state: row.state,
+        ...(row.execution_id ? { executionId: row.execution_id } : {}),
+        ...(row.effort ? { effort: row.effort } : {}),
+    }));
+}
+/** List continuation fence metadata without loading operator tell bodies. */
+export function listTellMetadata(projectionDirectory, states) {
+    return withRead(projectionDirectory, (database) => listTellMetadataFromDatabase(database, states));
+}
+export function readPendingTellWindowFromDatabase(database, limit) {
+    if (!Number.isSafeInteger(limit) || limit < 0) {
+        throw new ProjectionStateError("pending tell window limit must be a non-negative safe integer");
+    }
+    const pendingPlaceholders = PENDING_PROJECTION_TELL_STATES.map(() => "?").join(", ");
+    const total = database.prepare(`
+    SELECT COUNT(*) AS count
+    FROM projection_tells
+    WHERE state IN (${pendingPlaceholders})
+  `).get(...PENDING_PROJECTION_TELL_STATES);
+    const rows = database.prepare(`
+    SELECT tell_id, text, created_at, state
+    FROM projection_tells
+    WHERE state IN (${pendingPlaceholders})
+    ORDER BY tell_id
+    LIMIT ?
+  `).all(...PENDING_PROJECTION_TELL_STATES, limit);
+    return {
+        totals: { undelivered: Number(total.count) },
+        window: rows.map((row) => ({ tellId: row.tell_id, text: row.text, createdAt: row.created_at, state: row.state })),
+    };
+}
+export function readPendingTellWindow(projectionDirectory, limit) {
+    return withReadSnapshot(projectionDirectory, (database) => readPendingTellWindowFromDatabase(database, limit));
+}
+/** Whether a failed successor fence still retains delivered mail for replay. */
+export function hasRetainedDeliveredTellFromDatabase(database, retainedFence) {
+    if (retainedFence.length === 0)
+        return false;
+    const statement = database.prepare(`
+    SELECT 1
+    FROM projection_tells
+    WHERE tell_id = ? AND state = 'delivered'
+    LIMIT 1
+  `);
+    return retainedFence.some((tellId) => statement.get(tellId) !== undefined);
+}
+export function hasRetainedDeliveredTell(projectionDirectory, retainedFence) {
+    return withRead(projectionDirectory, (database) => hasRetainedDeliveredTellFromDatabase(database, retainedFence));
+}
+/** Whether interrupted replay has any delivered tell left to return to inbox. */
+export function hasDeliveredTellFromDatabase(database, executionId) {
+    return database.prepare(`
+    SELECT 1
+    FROM projection_tells
+    WHERE state = 'delivered' AND execution_id = ?
+    LIMIT 1
+  `).get(executionId) !== undefined;
+}
+export function hasDeliveredTell(projectionDirectory, executionId) {
+    return withRead(projectionDirectory, (database) => hasDeliveredTellFromDatabase(database, executionId));
+}
 export function readTellOriginal(projectionDirectory, state, tellId) {
     return withRead(projectionDirectory, (database) => {
         const row = selectTell(database, tellId);
@@ -49,14 +119,6 @@ export function writeInboxTell(projectionDirectory, text, nowMs, options) {
     }
     const tellId = `${nowMs}-${assertTellIdRandomHex((options?.randomHex ?? randomHex8)())}`;
     return withWrite(projectionDirectory, (database) => {
-        const pending = database.prepare(`
-      SELECT COUNT(*) AS count
-      FROM projection_tells
-      WHERE state IN ('inbox', 'inflight', 'submitted', 'delivered')
-    `).get();
-        if (Number(pending.count) >= PENDING_TELL_LIMIT) {
-            throw new ProjectionStateError(`projection has reached the ${PENDING_TELL_LIMIT} pending tell limit`);
-        }
         try {
             database.prepare(`
         INSERT INTO projection_tells (
@@ -123,6 +185,31 @@ export function claimFencedTells(projectionDirectory, fence, executionId) {
                 claimed.push(tellId);
                 continue;
             }
+            if (row.state === "submitted" || row.state === "delivered") {
+                const submitted = submittedFromRow(row);
+                if (submitted.executionId === owner) {
+                    throw new ProjectionStateError(`submitted tell belongs to current execution: ${tellId}`);
+                }
+                const replayedFrom = [
+                    ...(submitted.replayedFrom ?? []),
+                    { executionId: submitted.executionId, fence: submitted.fence },
+                ];
+                const result = database.prepare(`
+          UPDATE projection_tells
+          SET
+            state = 'inflight',
+            execution_id = NULL,
+            fence_json = NULL,
+            replayed_from_json = ?,
+            delivered_at = NULL
+          WHERE tell_id = ? AND state = ?
+        `).run(JSON.stringify(replayedFrom), tellId, row.state);
+                if (Number(result.changes) !== 1) {
+                    throw new ProjectionStateError(`generation tell fence member changed while claiming: ${tellId}`);
+                }
+                claimed.push(tellId);
+                continue;
+            }
             if (row.state === "consumed" && row.execution_id === owner)
                 continue;
             throw new ProjectionStateError(`generation tell fence member is not claimable: ${tellId}`);
@@ -152,7 +239,7 @@ export function markTellSubmitted(projectionDirectory, tellId, fields) {
         state = 'submitted',
         execution_id = ?,
         fence_json = ?,
-        replayed_from_json = ?
+        replayed_from_json = COALESCE(?, replayed_from_json)
       WHERE tell_id = ? AND state = 'inflight'
     `).run(executionId, JSON.stringify(fence), replayedFrom.length > 0 ? JSON.stringify(replayedFrom) : null, tellId);
     });
@@ -190,12 +277,13 @@ export function readProjectionTellCounts(projectionDirectory) {
 }
 export function snapshotPendingTells(projectionDirectory) {
     return withRead(projectionDirectory, (database) => {
+        const pendingPlaceholders = PENDING_PROJECTION_TELL_STATES.map(() => "?").join(", ");
         const rows = database.prepare(`
       SELECT tell_id, effort
       FROM projection_tells
-      WHERE state IN ('inbox', 'inflight', 'submitted', 'delivered')
+      WHERE state IN (${pendingPlaceholders})
       ORDER BY tell_id
-    `).all();
+    `).all(...PENDING_PROJECTION_TELL_STATES);
         const effort = rows.reduce((selected, row) => row.effort ?? selected, undefined);
         return {
             tellIds: rows.map((row) => row.tell_id),
@@ -203,44 +291,3 @@ export function snapshotPendingTells(projectionDirectory) {
         };
     });
 }
-export function demoteSubmittedTellsForReplay(projectionDirectory, executionId) {
-    const currentExecutionId = requireExecutionId(executionId);
-    return withWrite(projectionDirectory, (database) => {
-        const rows = database.prepare(`
-      SELECT
-        tell_id,
-        text,
-        created_at,
-        effort,
-        state,
-        execution_id,
-        fence_json,
-        replayed_from_json,
-        delivered_at
-      FROM projection_tells
-      WHERE state IN ('submitted', 'delivered')
-      ORDER BY tell_id
-    `).all();
-        for (const row of rows) {
-            const submitted = submittedFromRow(row);
-            if (submitted.executionId === currentExecutionId) {
-                throw new ProjectionStateError(`submitted tell belongs to current execution: ${row.tell_id}`);
-            }
-            const replayedFrom = [
-                ...(submitted.replayedFrom ?? []),
-                { executionId: submitted.executionId, fence: submitted.fence },
-            ];
-            database.prepare(`
-        UPDATE projection_tells
-        SET
-          state = 'inflight',
-          execution_id = NULL,
-          fence_json = NULL,
-          replayed_from_json = ?,
-          delivered_at = NULL
-        WHERE tell_id = ? AND state IN ('submitted', 'delivered')
-      `).run(JSON.stringify(replayedFrom), row.tell_id);
-        }
-        return rows.map((row) => row.tell_id);
-    });
-}

package/build/core/registry.js

@@ -1,7 +1,7 @@
 import { FlowError } from "../flow-error.js";
 import { createGit, wrapGitError } from "../git/core.js";
 import { readLedger } from "./ledger.js";
-import { appendRefLogWithRetry } from "./ref-log.js";
+import { appendRefLogWithRetry, readRefLog } from "./ref-log.js";
 import { patternsOverlap, scopePathEvidence } from "./scope.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 export const REGISTRY_REF = "refs/keiyaku/registry";
@@ -39,11 +39,9 @@ async function activeRegistrations(cwd, entries) {
     }
     return active;
 }
-export async function registerScope(cwd, input) {
-    let overlaps = [];
-    let trackedPaths;
+async function trackedRepositoryPaths(cwd) {
     try {
-        trackedPaths = (await createGit(cwd).raw(["ls-files", "-z"]))
+        return (await createGit(cwd).raw(["ls-files", "-z"]))
             .split("\0")
             .filter(Boolean)
             .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
@@ -51,76 +49,91 @@ export async function registerScope(cwd, input) {
     catch (error) {
         throw wrapGitError("ls-files -z", error, cwd);
     }
-    const result = await appendRefLogWithRetry(cwd, REGISTRY_REF, registrySubject, parseRegistryEntry, async (entries) => {
-        const nextOverlaps = [];
-        const active = await activeRegistrations(cwd, entries);
-        if (input.exclusive && active.length > 0) {
-            const blocking = active.find((existing) => existing.contract !== input.contractId) ?? active[0];
-            throw new FlowError("ACTIVE_KEIYAKU_EXISTS", `exclusive bind rejected: active contract ${blocking.contract} already exists`);
+}
+async function scopeRegistrationAdmission(cwd, input, entries, trackedPaths) {
+    const nextOverlaps = [];
+    const active = await activeRegistrations(cwd, entries);
+    if (input.exclusive && active.length > 0) {
+        const blocking = active.find((existing) => existing.contract !== input.contractId) ?? active[0];
+        throw new FlowError("ACTIVE_KEIYAKU_EXISTS", `exclusive bind rejected: active contract ${blocking.contract} already exists`);
+    }
+    for (const existing of active) {
+        if (existing.contract === input.contractId)
+            continue;
+        if (existing.tree === input.tree) {
+            throw new FlowError("ACTIVE_KEIYAKU_EXISTS", [
+                `tree is already occupied by active contract ${existing.contract}`,
+                `Run \`keiyaku forfeit @${existing.contract}\` to free this tree.`,
+            ].join(" "));
         }
-        for (const existing of active) {
-            if (existing.contract === input.contractId)
+        const [nextEvidence, existingEvidence] = await Promise.all([
+            scopePathEvidence(cwd, input.scope, trackedPaths),
+            scopePathEvidence(cwd, existing.scope, trackedPaths),
+        ]);
+        const existingByPath = new Map(existingEvidence.map((evidence) => [evidence.path, evidence]));
+        const concreteByPatterns = new Map();
+        for (const next of nextEvidence) {
+            const prior = existingByPath.get(next.path);
+            if (!next.matched || !prior?.matched || !next.decisivePattern || !prior.decisivePattern)
                 continue;
-            if (existing.tree === input.tree) {
-                throw new FlowError("ACTIVE_KEIYAKU_EXISTS", [
-                    `tree is already occupied by active contract ${existing.contract}`,
-                    `Run \`keiyaku forfeit @${existing.contract}\` to free this tree.`,
-                ].join(" "));
-            }
-            const [nextEvidence, existingEvidence] = await Promise.all([
-                scopePathEvidence(cwd, input.scope, trackedPaths),
-                scopePathEvidence(cwd, existing.scope, trackedPaths),
-            ]);
-            const existingByPath = new Map(existingEvidence.map((evidence) => [evidence.path, evidence]));
-            const concreteByPatterns = new Map();
-            for (const next of nextEvidence) {
-                const prior = existingByPath.get(next.path);
-                if (!next.matched || !prior?.matched || !next.decisivePattern || !prior.decisivePattern)
-                    continue;
-                const key = `${next.decisivePattern.index}:${prior.decisivePattern.index}`;
-                const group = concreteByPatterns.get(key) ?? {
-                    next: next.decisivePattern.pattern,
-                    existing: prior.decisivePattern.pattern,
-                    paths: [],
-                };
-                group.paths.push(next.path);
-                concreteByPatterns.set(key, group);
-            }
-            for (const concrete of concreteByPatterns.values()) {
-                const preview = concrete.paths.slice(0, SCOPE_OVERLAP_PATH_PREVIEW_LIMIT);
-                nextOverlaps.push({
-                    contracts: [input.contractId, existing.contract],
-                    patterns: [concrete.next, concrete.existing],
-                    kind: "concrete",
-                    paths: {
-                        preview,
-                        count: concrete.paths.length,
-                        truncated: preview.length < concrete.paths.length,
-                    },
-                });
-            }
-            for (const nextPattern of input.scope) {
-                for (const existingPattern of existing.scope) {
-                    if (patternsOverlap(nextPattern, existingPattern)) {
-                        const [nextPatternEvidence, existingPatternEvidence] = await Promise.all([
-                            scopePathEvidence(cwd, [nextPattern], trackedPaths),
-                            scopePathEvidence(cwd, [existingPattern], trackedPaths),
-                        ]);
-                        const existingPatternByPath = new Map(existingPatternEvidence.map((evidence) => [evidence.path, evidence]));
-                        const hasCurrentWitness = nextPatternEvidence.some((evidence) => (evidence.matched && existingPatternByPath.get(evidence.path)?.matched));
-                        if (!hasCurrentWitness) {
-                            nextOverlaps.push({
-                                contracts: [input.contractId, existing.contract],
-                                patterns: [nextPattern, existingPattern],
-                                kind: "potential",
-                                paths: { preview: [], count: 0, truncated: false },
-                            });
-                        }
+            const key = `${next.decisivePattern.index}:${prior.decisivePattern.index}`;
+            const group = concreteByPatterns.get(key) ?? {
+                next: next.decisivePattern.pattern,
+                existing: prior.decisivePattern.pattern,
+                paths: [],
+            };
+            group.paths.push(next.path);
+            concreteByPatterns.set(key, group);
+        }
+        for (const concrete of concreteByPatterns.values()) {
+            const preview = concrete.paths.slice(0, SCOPE_OVERLAP_PATH_PREVIEW_LIMIT);
+            nextOverlaps.push({
+                contracts: [input.contractId, existing.contract],
+                patterns: [concrete.next, concrete.existing],
+                kind: "concrete",
+                paths: {
+                    preview,
+                    count: concrete.paths.length,
+                    truncated: preview.length < concrete.paths.length,
+                },
+            });
+        }
+        for (const nextPattern of input.scope) {
+            for (const existingPattern of existing.scope) {
+                if (patternsOverlap(nextPattern, existingPattern)) {
+                    const [nextPatternEvidence, existingPatternEvidence] = await Promise.all([
+                        scopePathEvidence(cwd, [nextPattern], trackedPaths),
+                        scopePathEvidence(cwd, [existingPattern], trackedPaths),
+                    ]);
+                    const existingPatternByPath = new Map(existingPatternEvidence.map((evidence) => [evidence.path, evidence]));
+                    const hasCurrentWitness = nextPatternEvidence.some((evidence) => (evidence.matched && existingPatternByPath.get(evidence.path)?.matched));
+                    if (!hasCurrentWitness) {
+                        nextOverlaps.push({
+                            contracts: [input.contractId, existing.contract],
+                            patterns: [nextPattern, existingPattern],
+                            kind: "potential",
+                            paths: { preview: [], count: 0, truncated: false },
+                        });
                     }
                 }
             }
         }
-        overlaps = nextOverlaps;
+    }
+    return nextOverlaps;
+}
+/** Read-only bind admission: validate exclusivity and classify scope overlap. */
+export async function previewScopeRegistration(cwd, input) {
+    const [entries, trackedPaths] = await Promise.all([
+        readRefLog(cwd, REGISTRY_REF, parseRegistryEntry),
+        trackedRepositoryPaths(cwd),
+    ]);
+    return await scopeRegistrationAdmission(cwd, input, entries, trackedPaths);
+}
+export async function registerScope(cwd, input) {
+    let overlaps = [];
+    const trackedPaths = await trackedRepositoryPaths(cwd);
+    const result = await appendRefLogWithRetry(cwd, REGISTRY_REF, registrySubject, parseRegistryEntry, async (entries) => {
+        overlaps = await scopeRegistrationAdmission(cwd, input, entries, trackedPaths);
         return {
             v: 1,
             kind: "register",

package/build/core/scope.js

@@ -38,17 +38,17 @@ export function isBlankScopePatternLine(line) {
 }
 /** Parse Keiyaku's source-line Scope opener, not a normalized Markdown node. */
 export function parseScopeFenceOpening(line) {
-    const match = line.match(/^(`{3,})$/);
-    return match ? { length: match[1].length } : null;
+    const match = line.match(/^(`{3,}|~{3,})$/);
+    return match ? { delimiter: match[1][0], length: match[1].length } : null;
 }
-/** Keiyaku closer: column-zero backticks, at least opener length, then whitespace. */
+/** Keiyaku closer: matching column-zero delimiter, at least opener length, then whitespace. */
 export function isScopeFenceClosing(line, fence) {
-    const match = line.match(/^(`+)[ \t]*$/);
-    return Boolean(match && match[1].length >= fence.length);
+    const match = line.match(/^(`+|~+)[ \t]*$/);
+    return Boolean(match && match[1][0] === fence.delimiter && match[1].length >= fence.length);
 }
 function fencedScopeError(heading, detail) {
     return new FlowError("INVALID_KEIYAKU_DRAFT", `${heading} must contain exactly one fenced gitignore-subset block; ${detail}. ` +
-        `Paste-ready canonical example:\n\n${heading}\n\`\`\`\nfoo\nbar\n\`\`\``);
+        `Paste-ready canonical example:\n\n${heading}\n~~~\nfoo\nbar\n~~~`);
 }
 /** Validate and normalize the one fenced block that constitutes a Scope body. */
 export function validateScopeFragmentLines(lines, options) {
@@ -152,14 +152,14 @@ export function markdownSourceSections(markdown) {
         return { ...heading, end: next?.start ?? markdown.length };
     });
 }
-/** Render canonical Scope bytes with a fence that content cannot close. */
+/** Render canonical Scope bytes with a tilde fence that content cannot close. */
 export function renderScopeFragment(patterns) {
     let longestRun = 0;
     for (const pattern of patterns) {
-        for (const run of pattern.match(/`+/g) ?? [])
+        for (const run of pattern.match(/~+/g) ?? [])
             longestRun = Math.max(longestRun, run.length);
     }
-    const fence = "`".repeat(Math.max(3, longestRun + 1));
+    const fence = "~".repeat(Math.max(3, longestRun + 1));
     return `${fence}\n${patterns.join("\n")}\n${fence}`;
 }
 /**

package/build/core/task/index.js

@@ -3,10 +3,10 @@
  * Only symbols required by current external consumers are re-exported.
  * Package-internal modules must import each other directly, not through this file.
  */
-export { reconcileTaskForfeit, settleTaskBoardForBind, settleTaskBoardForLanding, } from "./task-contract.js";
+export { previewTaskBoardForBind, reconcileTaskForfeit, settleTaskBoardForBind, settleTaskBoardForLanding, } from "./task-contract.js";
 export { resolveTaskCreator } from "./task-git-actor.js";
 export { openTaskCommandRepository, readTaskDoctor, taskCommandContractId, } from "./task-git-runtime.js";
-export { openTaskStore } from "./task-git-store.js";
+export { openTaskStore, readTaskHistory } from "./task-git-store.js";
 export { taskRepositoryFromStore } from "./task-store-repository.js";
 export { isTaskId } from "./validation.js";
 export { buildTaskTree, createTask, doneTask, dropTask, parseTaskDocument, readTaskBoard, resolveTaskReadId, serializeTaskDocument, startTask, stopTask, updateTask, deriveTaskDisplay, selectTaskList, taskUpdatedAt, advancedTaskUpdatedAt, } from "./task.js";

package/build/core/task/query.js

@@ -2,10 +2,16 @@ import { FlowError } from "../../flow-error.js";
 import { isCommissionId } from "../ids.js";
 import { taskUpdatedAt } from "./model.js";
 import { isTaskId } from "./validation.js";
-const FILTER_FIELDS = new Set([
-    "state", "priority", "parent", "needs", "blocks", "contract", "created", "updated",
-]);
+export const TASK_FILTER_FIELDS = [
+    "title", "state", "priority", "parent", "needs", "blocks", "contract", "created", "updated",
+];
+export const TASK_FILTER_OPERATORS = ["=", "!=", "~", "<", "<=", ">", ">="];
+export const TASK_FILTER_GRAMMAR = "FIELD OP VALUE[,VALUE...] [| FIELD OP VALUE[,VALUE...]]...";
+export const TASK_FILTER_COMPLETION = "FIELD OP VALUE[,VALUE...]|FIELD OP VALUE[,VALUE...]";
+const FILTER_FIELDS = new Set(TASK_FILTER_FIELDS);
 const ORDERED_FIELDS = new Set(["priority", "created", "updated"]);
+const TITLE_OPERATORS = new Set(["=", "!=", "~"]);
+const ORDERED_OPERATORS = new Set(["=", "!=", "<", "<=", ">", ">="]);
 const DISPLAY_VALUES = new Set(["ready", "blocked", "in_progress", "done", "dropped", "bound"]);
 const SORT_KEYS = new Set(["priority", "modified", "created"]);
 const RELATIVE_TIME = /^now-([1-9][0-9]*)([smhdw])$/;
@@ -21,57 +27,87 @@ export function deriveTaskDisplay(task) {
         return "in_progress";
     return task.blocked ? "blocked" : "ready";
 }
-function invalidFilter(detail) {
-    throw new FlowError("INVALID_TARGET", `invalid task filter: ${detail}`);
+function invalidFilter(detail, recoveredTerms = []) {
+    throw new FlowError("INVALID_TARGET", `invalid task filter: ${detail}`, {
+        facts: {
+            kind: "invalid_task_filter",
+            detail,
+            grammar: TASK_FILTER_GRAMMAR,
+            fields: [...TASK_FILTER_FIELDS],
+            operators: [...TASK_FILTER_OPERATORS],
+            recoveredTerms: recoveredTerms.map((term) => ({
+                field: term.field,
+                operator: term.operator,
+                values: [...term.values],
+            })),
+        },
+    });
 }
-export function parseTaskFilter(expression) {
-    const match = /^([a-z][a-z0-9_-]*)(!=|<=|>=|=|<|>)(.*)$/.exec(expression);
+function parseTaskFilterTerm(term, expression, recoveredTerms) {
+    const match = /^([a-z][a-z0-9_-]*)(!=|<=|>=|~|=|<|>)(.*)$/.exec(term);
     if (!match)
-        invalidFilter(`'${expression}' must use FIELD OP VALUE`);
+        invalidFilter(`'${expression}' must use ${TASK_FILTER_GRAMMAR}`, recoveredTerms);
     const field = match[1];
     const operator = match[2];
     if (!FILTER_FIELDS.has(field))
-        invalidFilter(`unknown field '${field}'`);
-    if (!ORDERED_FIELDS.has(field) && operator !== "=" && operator !== "!=") {
-        invalidFilter(`field '${field}' does not support operator '${operator}'`);
+        invalidFilter(`unknown field '${field}'`, recoveredTerms);
+    if (field === "title" && !TITLE_OPERATORS.has(operator)) {
+        invalidFilter(`field '${field}' does not support operator '${operator}'`, recoveredTerms);
+    }
+    if (field !== "title" && (ORDERED_FIELDS.has(field)
+        ? !ORDERED_OPERATORS.has(operator)
+        : operator !== "=" && operator !== "!=")) {
+        invalidFilter(`field '${field}' does not support operator '${operator}'`, recoveredTerms);
     }
     const values = match[3].split(",");
     if (values.some((value) => value.length === 0))
-        invalidFilter(`field '${field}' has an empty value`);
-    validateFilterValues(field, values);
+        invalidFilter(`field '${field}' has an empty value`, recoveredTerms);
+    validateFilterValues(field, values, recoveredTerms);
     return { field, operator, values };
 }
-function parseTimestamp(value, nowMs) {
+export function parseTaskFilter(expression) {
+    const terms = expression.split("|");
+    const parsed = [];
+    for (const term of terms) {
+        if (term.length === 0)
+            invalidFilter(`'${expression}' must use ${TASK_FILTER_GRAMMAR}`, parsed);
+        parsed.push(parseTaskFilterTerm(term, expression, parsed));
+    }
+    return parsed;
+}
+function parseTimestamp(value, nowMs, recoveredTerms = []) {
     const relative = RELATIVE_TIME.exec(value);
     if (relative) {
         const amount = Number(relative[1]);
         const offset = amount * UNIT_MS[relative[2]];
         if (!Number.isSafeInteger(offset))
-            invalidFilter(`timestamp '${value}' is outside the supported range`);
+            invalidFilter(`timestamp '${value}' is outside the supported range`, recoveredTerms);
         return nowMs - offset;
     }
     const timestamp = Date.parse(value);
     if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== value) {
-        invalidFilter(`timestamp '${value}' must be canonical ISO-8601 or now-<duration>`);
+        invalidFilter(`timestamp '${value}' must be canonical ISO-8601 or now-<duration>`, recoveredTerms);
     }
     return timestamp;
 }
-function validateFilterValues(field, values) {
+function validateFilterValues(field, values, recoveredTerms) {
+    if (field === "title")
+        return;
     if (field === "state") {
         for (const value of values)
             if (!DISPLAY_VALUES.has(value))
-                invalidFilter(`unknown state '${value}'`);
+                invalidFilter(`unknown state '${value}'`, recoveredTerms);
         return;
     }
     if (field === "priority") {
         for (const value of values)
             if (!/^[0-3]$/.test(value))
-                invalidFilter(`priority '${value}' must be 0 through 3`);
+                invalidFilter(`priority '${value}' must be 0 through 3`, recoveredTerms);
         return;
     }
     if (field === "created" || field === "updated") {
         for (const value of values)
-            parseTimestamp(value, 0);
+            parseTimestamp(value, 0, recoveredTerms);
         return;
     }
     if (field === "parent" || field === "needs" || field === "blocks") {
@@ -79,14 +115,14 @@ function validateFilterValues(field, values) {
             if (field === "parent" && value === "none")
                 continue;
             if (!isTaskId(value))
-                invalidFilter(`value '${value}' must be a canonical full task id`);
+                invalidFilter(`value '${value}' must be a canonical full task id`, recoveredTerms);
         }
         return;
     }
     if (field === "contract") {
         for (const value of values) {
             if (value !== "none" && !isCommissionId(value))
-                invalidFilter(`value '${value}' must be a full commission id or none`);
+                invalidFilter(`value '${value}' must be a full commission id or none`, recoveredTerms);
         }
     }
 }
@@ -114,10 +150,16 @@ function compareValue(left, right, operator) {
         case "<=": return left <= right;
         case ">": return left > right;
         case ">=": return left >= right;
+        case "~": return false;
     }
 }
 function matchesFilter(task, filter, nowMs) {
     return filter.values.some((raw) => {
+        if (filter.field === "title") {
+            if (filter.operator === "~")
+                return task.title.toLowerCase().includes(raw.toLowerCase());
+            return compareValue(task.title, raw, filter.operator);
+        }
         if (filter.field === "state")
             return compareValue(deriveTaskDisplay(task), raw, filter.operator);
         if (filter.field === "priority")
@@ -167,6 +209,6 @@ export function selectTaskList(tasks, options = {}) {
     const nowMs = options.nowMs ?? Date.now();
     return tasks
         .filter((task) => selected(task, options.selection ?? "default"))
-        .filter((task) => filters.every((filter) => matchesFilter(task, filter, nowMs)))
+        .filter((task) => filters.every((filter) => filter.some((term) => matchesFilter(task, term, nowMs))))
         .sort(sort === undefined ? defaultCompare : (left, right) => explicitCompare(sort, left, right));
 }

package/build/core/task/task-contract.js

@@ -7,6 +7,24 @@ import { buildTaskSourceBoard } from "./source-board.js";
 import { composeLandingTree, containsCommit, createLandingCommit, createTaskBoardCommit, findAcceptedLandingCommit, publishTaskMutationCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, reconcileTaskPathsetIndex, refHead, taskContractAtCommit, taskSettlementOwnershipAtCommit, taskSourcesAtCommit, taskWritesFromSources, trackedTaskPaths, updateBranch, updateTargetRef, } from "./settlement-git.js";
 import { contractPointerDocument, doneTaskReplacements, reopenedTaskDocument, requireHealthySettlementBoard, requireSettledTask, selectReadyTasksForBind, tasksForContract, } from "./settlement-policy.js";
 import { stableRepoRoot } from "../worktree-path.js";
+/**
+ * Read the same healthy task board and run the same ready-task selector as bind
+ * under the task admission lock, without replacing sources or publishing.
+ */
+export async function previewTaskBoardForBind(input) {
+    await requireGitRepository(input.cwd, "task bind");
+    return await withLockHeldTaskBoard(input.cwd, async (transaction) => {
+        if (transaction.location.mode !== "git") {
+            if (transaction.location.capability === "unavailable") {
+                assertGitObservation({ capability: "unavailable" }, "task bind");
+            }
+            throw new FlowError("NOT_GIT_REPO", "task bind requires Git task storage");
+        }
+        const repository = taskRepositoryFromLockedBoard(transaction);
+        const board = requireHealthySettlementBoard(await repository.read());
+        return { tasks: input.taskIds === undefined ? [] : selectReadyTasksForBind(board, input.taskIds) };
+    });
+}
 function sourcePath(root, source) {
     return source.path.slice(root.length + 1).split("\\").join("/");
 }