@felan-ai/ext-tasks 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felan contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,12 @@
+@felan-ai/ext-tasks
+
+Its interaction design was informed by the MIT-licensed pi-todo-write package
+from https://github.com/mslavov/pi-extensions at source commit
+9571293d422db11de893fa80ed0fc3e39945c657. No source code was copied.
+
+The dependency and readiness model was informed by the open-source Beads task
+tracker. This package does not include Beads source code or invoke its CLI.
+
+This package uses TypeBox 1.1.38 from
+https://github.com/sinclairzx81/typebox, licensed under the MIT License.
+Copyright (c) 2017-2026 Haydn Paterson.

package/README.md

@@ -0,0 +1,48 @@
+# @felan-ai/ext-tasks
+
+Dependency-aware task tracking scoped to one Felan root session. The extension
+registers `TaskCreate`, `TaskUpdate`, `TaskList`, and `TaskGet`. Tasks have stable
+IDs, hard prerequisite edges, priorities, acceptance criteria, ownership,
+handoff notes, and terminal results.
+
+Task state lives under `<session-storage>/tasks/state.json`. The root session and
+all of its subagents use the same `AgentRuntime.storage('session')` namespace,
+so every worker sees the same graph without a task-specific subagent protocol.
+Mutations are serialized per storage root within a Felan host process, and
+`TaskUpdate` atomically claims a ready task for its calling session when setting
+`status: "in_progress"`. A cloud host that distributes one root session across
+multiple processes must provide equivalent root-scoped serialization.
+
+The task graph is execution state rather than an issue tracker. It has no
+project backlog, remote synchronization, comments, labels, estimates, or due
+dates. Work that must outlive the root session belongs in Beads, Jira, Linear,
+or another persistent tracking system.
+
+## Tools
+
+- `TaskCreate` creates a pending task and returns its stable ID.
+- `TaskUpdate` edits metadata and dependencies or changes lifecycle status.
+- `TaskList` returns the current, ready, active, blocked, pending, completed, or
+  full task view.
+- `TaskGet` returns one task with prerequisite and dependent details.
+
+Only completed prerequisites satisfy a dependency. Dependency cycles are
+rejected. Multiple sessions may own work concurrently, while each session may
+claim at most one task at a time. A session cannot change another session's
+active task unless it explicitly requests stale-claim recovery with `force`.
+
+Local TUI sessions expose `/tasks` and `Ctrl+Shift+T` for list, detail, and graph
+views. Headless and cloud sessions use the same tools and storage without
+registering TUI controls.
+
+## Development
+
+Source: `packages/ext-tasks` in <https://github.com/felan-ai/felan>.
+
+```sh
+corepack enable
+pnpm install --frozen-lockfile
+pnpm --filter @felan-ai/ext-tasks build
+pnpm --filter @felan-ai/ext-tasks type-check
+pnpm --filter @felan-ai/ext-tasks test
+```

package/dist/contracts.d.ts

@@ -0,0 +1,62 @@
+export declare const TASK_STATUS_VALUES: readonly ["pending", "in_progress", "blocked", "completed", "cancelled"];
+export declare const TASK_VIEW_VALUES: readonly ["current", "ready", "active", "blocked", "pending", "completed", "all"];
+export type TaskStatus = typeof TASK_STATUS_VALUES[number];
+export type TaskView = typeof TASK_VIEW_VALUES[number];
+export type TaskAvailability = 'ready' | 'waiting' | 'in_progress' | 'blocked' | 'completed' | 'cancelled';
+export interface Task {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly acceptanceCriteria?: string;
+    readonly priority: number;
+    readonly status: TaskStatus;
+    readonly blockedBy: readonly string[];
+    readonly ownerSessionId?: string;
+    readonly claimedAt?: string;
+    readonly notes?: string;
+    readonly result?: string;
+    readonly blockedReason?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly completedAt?: string;
+}
+export interface TaskState {
+    readonly schemaVersion: 1;
+    readonly revision: number;
+    readonly tasks: readonly Task[];
+}
+export interface CreateTaskInput {
+    readonly title: string;
+    readonly description?: string;
+    readonly acceptanceCriteria?: string;
+    readonly priority?: number;
+    readonly blockedBy?: readonly string[];
+}
+export interface UpdateTaskInput {
+    readonly taskId: string;
+    readonly force?: boolean;
+    readonly title?: string;
+    readonly description?: string;
+    readonly acceptanceCriteria?: string;
+    readonly priority?: number;
+    readonly status?: TaskStatus;
+    readonly addBlockedBy?: readonly string[];
+    readonly removeBlockedBy?: readonly string[];
+    readonly notes?: string;
+    readonly result?: string;
+    readonly blockedReason?: string;
+}
+export interface TaskMutationResult {
+    readonly state: TaskState;
+    readonly task: Task;
+}
+export interface TaskCounts {
+    readonly total: number;
+    readonly ready: number;
+    readonly active: number;
+    readonly blocked: number;
+    readonly pending: number;
+    readonly completed: number;
+    readonly cancelled: number;
+}
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

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

package/dist/contracts.js

@@ -0,0 +1,17 @@
+export const TASK_STATUS_VALUES = [
+    'pending',
+    'in_progress',
+    'blocked',
+    'completed',
+    'cancelled',
+];
+export const TASK_VIEW_VALUES = [
+    'current',
+    'ready',
+    'active',
+    'blocked',
+    'pending',
+    'completed',
+    'all',
+];
+//# sourceMappingURL=contracts.js.map

package/dist/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,SAAS;IACT,aAAa;IACb,SAAS;IACT,WAAW;IACX,WAAW;CACH,CAAC;AAEX,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,OAAO;IACP,QAAQ;IACR,SAAS;IACT,SAAS;IACT,WAAW;IACX,KAAK;CACG,CAAC"}

package/dist/graph.d.ts

@@ -0,0 +1,21 @@
+import type { CreateTaskInput, Task, TaskAvailability, TaskCounts, TaskMutationResult, TaskState, TaskView, UpdateTaskInput } from './contracts.js';
+export declare const MAX_TASKS = 200;
+export declare const MAX_DEPENDENCIES = 32;
+export declare const TASK_ID_PATTERN: RegExp;
+export declare class TaskGraphError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function emptyTaskState(): TaskState;
+export declare function cloneTaskState(state: TaskState): TaskState;
+export declare function createTask(state: TaskState, input: CreateTaskInput, id: string, now: string): TaskMutationResult;
+export declare function updateTask(state: TaskState, input: UpdateTaskInput, actorSessionId: string, now: string): TaskMutationResult;
+export declare function getTask(state: TaskState, id: string): Task;
+export declare function taskDependents(state: TaskState, id: string): Task[];
+export declare function taskAvailability(task: Task, state: TaskState): TaskAvailability;
+export declare function incompleteBlockers(task: Task, state: TaskState): Task[];
+export declare function listTasks(state: TaskState, view: TaskView): Task[];
+export declare function taskCounts(state: TaskState): TaskCounts;
+export declare function hasOpenTasks(state: TaskState): boolean;
+export declare function parseTaskState(value: unknown): TaskState;
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,IAAI,EACJ,gBAAgB,EAChB,UAAU,EACV,kBAAkB,EAClB,SAAS,EAET,QAAQ,EACR,eAAe,EAChB,MAAM,gBAAgB,CAAC;AAGxB,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,gBAAgB,KAAK,CAAC;AACnC,eAAO,MAAM,eAAe,QAAqB,CAAC;AAIlD,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,cAAc,IAAI,SAAS,CAE1C;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAM1D;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,eAAe,EACtB,EAAE,EAAE,MAAM,EACV,GAAG,EAAE,MAAM,GACV,kBAAkB,CA2BpB;AAED,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,eAAe,EACtB,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,GACV,kBAAkB,CAmFpB;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAI1D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,EAAE,CAInE;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,gBAAgB,CAM/E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,EAAE,CAKvE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,EAAE,CAKlE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU,CAoBvD;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAEtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAmBxD"}

package/dist/graph.js

@@ -0,0 +1,447 @@
+import { TASK_STATUS_VALUES } from './contracts.js';
+export const MAX_TASKS = 200;
+export const MAX_DEPENDENCIES = 32;
+export const TASK_ID_PATTERN = /^T-[A-Z0-9]{6}$/u;
+const TASK_STATUSES = new Set(TASK_STATUS_VALUES);
+export class TaskGraphError extends Error {
+    code;
+    constructor(code, message) {
+        super(`Task error: ${code} — ${message}`);
+        this.code = code;
+        this.name = 'TaskGraphError';
+    }
+}
+export function emptyTaskState() {
+    return { schemaVersion: 1, revision: 0, tasks: [] };
+}
+export function cloneTaskState(state) {
+    return {
+        schemaVersion: 1,
+        revision: state.revision,
+        tasks: state.tasks.map((task) => ({ ...task, blockedBy: [...task.blockedBy] })),
+    };
+}
+export function createTask(state, input, id, now) {
+    if (state.tasks.length >= MAX_TASKS) {
+        throw new TaskGraphError('task_limit', `A session task graph may contain at most ${MAX_TASKS} tasks`);
+    }
+    if (!TASK_ID_PATTERN.test(id))
+        throw new TaskGraphError('invalid_id', `Invalid task id: ${id}`);
+    if (state.tasks.some((task) => task.id === id))
+        throw new TaskGraphError('duplicate_id', `Task already exists: ${id}`);
+    const blockedBy = uniqueIds(input.blockedBy ?? []);
+    const task = {
+        id,
+        title: requiredText(input.title, 'title'),
+        priority: priorityValue(input.priority ?? 2),
+        status: 'pending',
+        blockedBy,
+        createdAt: now,
+        updatedAt: now,
+        ...(input.description === undefined ? {} : { description: requiredText(input.description, 'description') }),
+        ...(input.acceptanceCriteria === undefined
+            ? {}
+            : { acceptanceCriteria: requiredText(input.acceptanceCriteria, 'acceptance criteria') }),
+    };
+    const tasks = [...state.tasks, task];
+    assertGraphValid(tasks);
+    return {
+        state: { schemaVersion: 1, revision: state.revision + 1, tasks },
+        task,
+    };
+}
+export function updateTask(state, input, actorSessionId, now) {
+    const index = state.tasks.findIndex((task) => task.id === input.taskId);
+    if (index < 0)
+        throw new TaskGraphError('not_found', `Task not found: ${input.taskId}`);
+    const actor = requiredText(actorSessionId, 'session id');
+    const original = state.tasks[index];
+    let task = { ...original, blockedBy: [...original.blockedBy] };
+    if (original.status === 'in_progress'
+        && original.ownerSessionId !== actor
+        && input.force !== true) {
+        throw new TaskGraphError('not_owner', `${original.id} is claimed by ${original.ownerSessionId}`);
+    }
+    if (original.status === 'completed' && input.status !== undefined && input.status !== 'completed') {
+        const protectedDependents = state.tasks.filter((entry) => (entry.blockedBy.includes(original.id)
+            && (entry.status === 'in_progress' || entry.status === 'completed')));
+        if (protectedDependents.length > 0) {
+            throw new TaskGraphError('dependent_started', `Reopen dependent tasks before reopening ${original.id}: ${protectedDependents.map((entry) => entry.id).join(', ')}`);
+        }
+    }
+    if (input.title !== undefined)
+        task = { ...task, title: requiredText(input.title, 'title') };
+    if (input.description !== undefined) {
+        task = { ...task, description: requiredText(input.description, 'description') };
+    }
+    if (input.acceptanceCriteria !== undefined) {
+        task = {
+            ...task,
+            acceptanceCriteria: requiredText(input.acceptanceCriteria, 'acceptance criteria'),
+        };
+    }
+    if (input.priority !== undefined)
+        task = { ...task, priority: priorityValue(input.priority) };
+    if (input.notes !== undefined)
+        task = { ...task, notes: requiredText(input.notes, 'notes') };
+    const dependencyChange = input.addBlockedBy !== undefined || input.removeBlockedBy !== undefined;
+    if (dependencyChange && isTerminal(original.status) && input.status !== 'pending') {
+        throw new TaskGraphError('terminal_task', 'Reopen a completed or cancelled task before changing its dependencies');
+    }
+    const additions = uniqueIds(input.addBlockedBy ?? []);
+    const removals = uniqueIds(input.removeBlockedBy ?? []);
+    const overlap = additions.find((id) => removals.includes(id));
+    if (overlap)
+        throw new TaskGraphError('dependency_conflict', `${overlap} cannot be added and removed together`);
+    const blockedBy = task.blockedBy.filter((id) => !removals.includes(id));
+    for (const id of additions) {
+        if (!blockedBy.includes(id))
+            blockedBy.push(id);
+    }
+    task = { ...task, blockedBy };
+    if (input.result !== undefined && input.status !== 'completed' && original.status !== 'completed') {
+        throw new TaskGraphError('invalid_result', 'A result can only be written while completing a task');
+    }
+    if (input.blockedReason !== undefined && input.status !== 'blocked' && original.status !== 'blocked') {
+        throw new TaskGraphError('invalid_blocker', 'A blocked reason requires blocked status');
+    }
+    if (input.status !== undefined) {
+        task = transitionTask(state, task, input, actor, now);
+    }
+    else {
+        if (input.result !== undefined)
+            task = { ...task, result: requiredText(input.result, 'result') };
+        if (input.blockedReason !== undefined) {
+            task = { ...task, blockedReason: requiredText(input.blockedReason, 'blocked reason') };
+        }
+    }
+    const candidateTasks = state.tasks.map((entry, entryIndex) => entryIndex === index ? task : entry);
+    assertGraphValid(candidateTasks);
+    if (task.status === 'in_progress' || task.status === 'completed')
+        assertDependenciesCompleted(task, candidateTasks);
+    const unchanged = JSON.stringify({ ...task, updatedAt: original.updatedAt }) === JSON.stringify(original);
+    if (unchanged)
+        throw new TaskGraphError('no_changes', `No changes were supplied for ${task.id}`);
+    task = { ...task, updatedAt: now };
+    const tasks = state.tasks.map((entry, entryIndex) => entryIndex === index ? task : entry);
+    return {
+        state: { schemaVersion: 1, revision: state.revision + 1, tasks },
+        task,
+    };
+}
+export function getTask(state, id) {
+    const task = state.tasks.find((entry) => entry.id === id);
+    if (!task)
+        throw new TaskGraphError('not_found', `Task not found: ${id}`);
+    return { ...task, blockedBy: [...task.blockedBy] };
+}
+export function taskDependents(state, id) {
+    return state.tasks
+        .filter((task) => task.blockedBy.includes(id))
+        .map((task) => ({ ...task, blockedBy: [...task.blockedBy] }));
+}
+export function taskAvailability(task, state) {
+    if (task.status === 'in_progress')
+        return 'in_progress';
+    if (task.status === 'blocked')
+        return 'blocked';
+    if (task.status === 'completed')
+        return 'completed';
+    if (task.status === 'cancelled')
+        return 'cancelled';
+    return incompleteBlockers(task, state).length === 0 ? 'ready' : 'waiting';
+}
+export function incompleteBlockers(task, state) {
+    const tasks = new Map(state.tasks.map((entry) => [entry.id, entry]));
+    return task.blockedBy
+        .map((id) => tasks.get(id))
+        .filter((entry) => entry !== undefined && entry.status !== 'completed');
+}
+export function listTasks(state, view) {
+    return state.tasks
+        .filter((task) => matchesView(task, state, view))
+        .map((task) => ({ ...task, blockedBy: [...task.blockedBy] }))
+        .sort((left, right) => compareTasks(left, right, state));
+}
+export function taskCounts(state) {
+    const counts = {
+        total: state.tasks.length,
+        ready: 0,
+        active: 0,
+        blocked: 0,
+        pending: 0,
+        completed: 0,
+        cancelled: 0,
+    };
+    for (const task of state.tasks) {
+        const availability = taskAvailability(task, state);
+        if (availability === 'ready')
+            counts.ready += 1;
+        if (availability === 'in_progress')
+            counts.active += 1;
+        if (availability === 'blocked' || availability === 'waiting')
+            counts.blocked += 1;
+        if (task.status === 'pending')
+            counts.pending += 1;
+        if (task.status === 'completed')
+            counts.completed += 1;
+        if (task.status === 'cancelled')
+            counts.cancelled += 1;
+    }
+    return counts;
+}
+export function hasOpenTasks(state) {
+    return state.tasks.some((task) => !isTerminal(task.status));
+}
+export function parseTaskState(value) {
+    if (!isRecord(value) || value.schemaVersion !== 1 || !isNonNegativeInteger(value.revision)) {
+        throw new TaskGraphError('invalid_state', 'Stored task state has an unsupported schema or revision');
+    }
+    if (!Array.isArray(value.tasks) || value.tasks.length > MAX_TASKS) {
+        throw new TaskGraphError('invalid_state', 'Stored task state has an invalid task collection');
+    }
+    const state = {
+        schemaVersion: 1,
+        revision: value.revision,
+        tasks: value.tasks.map(parseTask),
+    };
+    assertGraphValid(state.tasks);
+    for (const task of state.tasks) {
+        if (task.status === 'in_progress' || task.status === 'completed') {
+            assertDependenciesCompleted(task, state.tasks);
+        }
+    }
+    return state;
+}
+function transitionTask(state, task, input, actor, now) {
+    const status = input.status;
+    if (status === 'in_progress') {
+        if (task.status !== 'pending' && task.status !== 'in_progress') {
+            throw new TaskGraphError('not_ready', `${task.id} must be pending before it can be claimed`);
+        }
+        const active = state.tasks.find((entry) => (entry.status === 'in_progress'
+            && entry.ownerSessionId === actor
+            && entry.id !== task.id));
+        if (active)
+            throw new TaskGraphError('actor_busy', `${actor} already owns ${active.id}`);
+        assertDependenciesCompleted(task, state.tasks);
+        const base = clearTerminalFields(clearBlockedFields(task));
+        return {
+            ...base,
+            status: 'in_progress',
+            ownerSessionId: actor,
+            claimedAt: task.ownerSessionId === actor && task.claimedAt ? task.claimedAt : now,
+        };
+    }
+    if (status === 'pending') {
+        return { ...clearOwnership(clearTerminalFields(clearBlockedFields(task))), status: 'pending' };
+    }
+    if (status === 'blocked') {
+        const reason = input.blockedReason ?? task.blockedReason;
+        if (!reason)
+            throw new TaskGraphError('blocked_reason_required', 'Blocked tasks require a blocked reason');
+        return {
+            ...clearOwnership(clearTerminalFields(task)),
+            status: 'blocked',
+            blockedReason: requiredText(reason, 'blocked reason'),
+        };
+    }
+    if (status === 'completed') {
+        if (task.status !== 'in_progress' && task.status !== 'completed') {
+            throw new TaskGraphError('claim_required', `${task.id} must be claimed before completion`);
+        }
+        const result = input.result ?? task.result;
+        if (!result)
+            throw new TaskGraphError('result_required', 'Completed tasks require a result');
+        assertDependenciesCompleted(task, state.tasks);
+        return {
+            ...clearOwnership(clearBlockedFields(task)),
+            status: 'completed',
+            result: requiredText(result, 'result'),
+            completedAt: task.completedAt ?? now,
+        };
+    }
+    return { ...clearOwnership(clearTerminalFields(clearBlockedFields(task))), status: 'cancelled' };
+}
+function clearOwnership(task) {
+    const { ownerSessionId: _owner, claimedAt: _claimed, ...rest } = task;
+    return rest;
+}
+function clearBlockedFields(task) {
+    const { blockedReason: _reason, ...rest } = task;
+    return rest;
+}
+function clearTerminalFields(task) {
+    const { result: _result, completedAt: _completed, ...rest } = task;
+    return rest;
+}
+function assertDependenciesCompleted(task, tasks) {
+    const byId = new Map(tasks.map((entry) => [entry.id, entry]));
+    const incomplete = task.blockedBy.filter((id) => byId.get(id)?.status !== 'completed');
+    if (incomplete.length > 0) {
+        throw new TaskGraphError('blocked', `${task.id} is waiting on ${incomplete.join(', ')}`);
+    }
+}
+function assertGraphValid(tasks) {
+    const byId = new Map();
+    for (const task of tasks) {
+        if (byId.has(task.id))
+            throw new TaskGraphError('invalid_state', `Duplicate task id: ${task.id}`);
+        byId.set(task.id, task);
+    }
+    for (const task of tasks) {
+        if (task.blockedBy.length > MAX_DEPENDENCIES) {
+            throw new TaskGraphError('dependency_limit', `${task.id} has more than ${MAX_DEPENDENCIES} prerequisites`);
+        }
+        for (const blocker of task.blockedBy) {
+            if (blocker === task.id)
+                throw new TaskGraphError('self_dependency', `${task.id} cannot block itself`);
+            if (!byId.has(blocker))
+                throw new TaskGraphError('unknown_dependency', `Task not found: ${blocker}`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const path = [];
+    const visit = (id) => {
+        if (visited.has(id))
+            return;
+        if (visiting.has(id)) {
+            const start = path.indexOf(id);
+            throw new TaskGraphError('dependency_cycle', [...path.slice(start), id].join(' -> '));
+        }
+        visiting.add(id);
+        path.push(id);
+        for (const blocker of byId.get(id).blockedBy)
+            visit(blocker);
+        path.pop();
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const task of tasks)
+        visit(task.id);
+}
+function matchesView(task, state, view) {
+    const availability = taskAvailability(task, state);
+    if (view === 'all')
+        return true;
+    if (view === 'current')
+        return !isTerminal(task.status);
+    if (view === 'ready')
+        return availability === 'ready';
+    if (view === 'active')
+        return task.status === 'in_progress';
+    if (view === 'blocked')
+        return availability === 'blocked' || availability === 'waiting';
+    if (view === 'pending')
+        return task.status === 'pending';
+    return task.status === 'completed';
+}
+function compareTasks(left, right, state) {
+    const rank = (task) => {
+        const availability = taskAvailability(task, state);
+        return availability === 'in_progress' ? 0
+            : availability === 'ready' ? 1
+                : availability === 'blocked' || availability === 'waiting' ? 2
+                    : availability === 'completed' ? 3
+                        : 4;
+    };
+    return rank(left) - rank(right)
+        || left.priority - right.priority
+        || left.createdAt.localeCompare(right.createdAt)
+        || left.id.localeCompare(right.id);
+}
+function parseTask(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || !TASK_ID_PATTERN.test(value.id)) {
+        throw new TaskGraphError('invalid_state', 'Stored task has an invalid id');
+    }
+    if (typeof value.title !== 'string' || !TASK_STATUSES.has(String(value.status))) {
+        throw new TaskGraphError('invalid_state', `Stored task ${value.id} has invalid required fields`);
+    }
+    if (!Array.isArray(value.blockedBy) || !value.blockedBy.every((id) => typeof id === 'string')) {
+        throw new TaskGraphError('invalid_state', `Stored task ${value.id} has invalid dependencies`);
+    }
+    const task = {
+        id: value.id,
+        title: requiredText(value.title, 'title'),
+        priority: priorityValue(value.priority),
+        status: value.status,
+        blockedBy: uniqueIds(value.blockedBy),
+        createdAt: storedText(value.createdAt, value.id, 'createdAt'),
+        updatedAt: storedText(value.updatedAt, value.id, 'updatedAt'),
+        ...optionalStoredText(value, 'description'),
+        ...optionalStoredText(value, 'acceptanceCriteria'),
+        ...optionalStoredText(value, 'ownerSessionId'),
+        ...optionalStoredText(value, 'claimedAt'),
+        ...optionalStoredText(value, 'notes'),
+        ...optionalStoredText(value, 'result'),
+        ...optionalStoredText(value, 'blockedReason'),
+        ...optionalStoredText(value, 'completedAt'),
+    };
+    if (task.status === 'in_progress' && (!task.ownerSessionId || !task.claimedAt)) {
+        throw new TaskGraphError('invalid_state', `Stored active task ${task.id} has no owner`);
+    }
+    if (task.status !== 'in_progress' && (task.ownerSessionId || task.claimedAt)) {
+        throw new TaskGraphError('invalid_state', `Stored inactive task ${task.id} has active ownership`);
+    }
+    if (task.status === 'blocked' && !task.blockedReason) {
+        throw new TaskGraphError('invalid_state', `Stored blocked task ${task.id} has no reason`);
+    }
+    if (task.status !== 'blocked' && task.blockedReason) {
+        throw new TaskGraphError('invalid_state', `Stored task ${task.id} has a stale blocked reason`);
+    }
+    if (task.status === 'completed' && (!task.result || !task.completedAt)) {
+        throw new TaskGraphError('invalid_state', `Stored completed task ${task.id} has no result`);
+    }
+    if (task.status !== 'completed' && (task.result || task.completedAt)) {
+        throw new TaskGraphError('invalid_state', `Stored task ${task.id} has stale completion data`);
+    }
+    return task;
+}
+function optionalStoredText(value, key) {
+    const entry = value[key];
+    if (entry === undefined)
+        return {};
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+        throw new TaskGraphError('invalid_state', `Stored task has invalid ${String(key)}`);
+    }
+    return { [key]: entry };
+}
+function storedText(value, id, field) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new TaskGraphError('invalid_state', `Stored task ${id} has invalid ${field}`);
+    }
+    return value;
+}
+function requiredText(value, field) {
+    const text = value.trim();
+    if (!text)
+        throw new TaskGraphError('invalid_request', `${field} cannot be empty`);
+    return text;
+}
+function priorityValue(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 4) {
+        throw new TaskGraphError('invalid_priority', 'Priority must be an integer from 0 to 4');
+    }
+    return value;
+}
+function uniqueIds(ids) {
+    const unique = [...new Set(ids.map((id) => id.trim()))];
+    if (unique.some((id) => !TASK_ID_PATTERN.test(id))) {
+        throw new TaskGraphError('invalid_id', 'Dependency IDs must use the task ID returned by TaskCreate');
+    }
+    if (unique.length > MAX_DEPENDENCIES) {
+        throw new TaskGraphError('dependency_limit', `A task may have at most ${MAX_DEPENDENCIES} prerequisites`);
+    }
+    return unique;
+}
+function isTerminal(status) {
+    return status === 'completed' || status === 'cancelled';
+}
+function isNonNegativeInteger(value) {
+    return Number.isInteger(value) && value >= 0;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=graph.js.map