@jungjaehoon/mama-os 0.53.0 → 0.57.0

package/dist/api/work-actions.js

@@ -0,0 +1,987 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTaskListView = void 0;
+exports.workListTitleTextScore = workListTitleTextScore;
+exports.readOpenWorkCandidates = readOpenWorkCandidates;
+exports.runWorkListView = runWorkListView;
+exports.workListActionRegistrations = workListActionRegistrations;
+exports.assertReplayEventDatetime = assertReplayEventDatetime;
+exports.minimalWorkActionRegistrations = minimalWorkActionRegistrations;
+const node_crypto_1 = require("node:crypto");
+const timezone_js_1 = require("../runtime/timezone.js");
+const catalog_1 = require("@jungjaehoon/mama-core/api/catalog");
+const knowledge_1 = require("@jungjaehoon/mama-core/knowledge");
+const WORK_LIST_DEFAULT_LIMIT = 25;
+const WORK_LIST_MAX_LIMIT = 50;
+const WORK_LIST_MAX_DETAIL_IDS = 4;
+const WORK_LIST_DEFAULT_TEXT_LIMIT = 1_000;
+const WORK_LIST_MAX_TEXT_LIMIT = 2_000;
+const WORK_LIST_STATUSES = [
+    'pending',
+    'in_progress',
+    'review',
+    'blocked',
+    'done',
+    'cancelled',
+];
+const WORK_LIST_PRIORITIES = ['high', 'normal', 'low'];
+function workListObject(value) {
+    if (value === undefined)
+        return {};
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('work.list input must be an object');
+    }
+    return value;
+}
+function workListString(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`work.list ${field} must be a string`);
+    return value;
+}
+function workListStatuses(value) {
+    if (value === undefined)
+        return undefined;
+    const values = Array.isArray(value) ? value : [value];
+    if (values.length === 0) {
+        throw new Error('work.list status must contain at least one status');
+    }
+    const statuses = values.map((candidate) => {
+        if (typeof candidate !== 'string') {
+            throw new Error('work.list status must be a string or an array of strings');
+        }
+        if (!WORK_LIST_STATUSES.includes(candidate)) {
+            throw new Error(`work.list status must be one of ${WORK_LIST_STATUSES.join('|')}`);
+        }
+        return candidate;
+    });
+    return [...new Set(statuses)];
+}
+function workListInteger(value, field, fallback, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new Error(`work.list ${field} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function workListNonNegativeInteger(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error(`work.list ${field} must be a non-negative integer`);
+    }
+    return value;
+}
+function workListAsOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('work.list asOf must be a non-negative epoch-millisecond integer');
+    }
+    return value;
+}
+function workListFilter(input) {
+    const status = workListStatuses(input.status);
+    return {
+        ...(status === undefined ? {} : { status }),
+        ...(input.stage === undefined ? {} : { stage: workListString(input.stage, 'stage') }),
+        ...(input.project === undefined ? {} : { project: workListString(input.project, 'project') }),
+        ...(input.text === undefined ? {} : { text: workListString(input.text, 'text') }),
+        ...(input.asOf === undefined ? {} : { asOf: workListAsOf(input.asOf) }),
+        ...(input.changedSince === undefined ? {} : { changedSince: workListAsOf(input.changedSince) }),
+    };
+}
+function workListValueObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function workListText(value) {
+    return typeof value === 'string' ? value : null;
+}
+function workListNormalizedText(value) {
+    return value.normalize('NFKC').toLowerCase();
+}
+function workListTokens(value) {
+    const normalized = workListNormalizedText(value)
+        .replace(/([\p{L}])([\p{N}])/gu, '$1 $2')
+        .replace(/([\p{N}])([\p{L}])/gu, '$1 $2');
+    return normalized.split(/[^\p{L}\p{N}]+/gu).filter((token) => token.length > 0);
+}
+function workListSearchFields(item) {
+    const values = workListValueObject(item.values);
+    return {
+        title: workListText(values.title) ?? '',
+        description: workListText(values.description) ?? '',
+    };
+}
+function workListLexicalScore(query, fields) {
+    const queryTokens = [...new Set(workListTokens(query))];
+    if (queryTokens.length === 0) {
+        throw new Error('work.list text must contain searchable text');
+    }
+    const fieldText = `${fields.title}\n${fields.description}`;
+    const fieldTokens = new Set(workListTokens(fieldText));
+    const overlap = queryTokens.filter((token) => fieldTokens.has(token)).length / queryTokens.length;
+    const compactQuery = workListNormalizedText(query).replace(/[^\p{L}\p{N}]+/gu, '');
+    const exactSubstringBonus = compactQuery.length > 0 &&
+        [fields.title, fields.description].some((field) => workListNormalizedText(field)
+            .replace(/[^\p{L}\p{N}]+/gu, '')
+            .includes(compactQuery))
+        ? 0.2
+        : 0;
+    return Math.min(1, overlap * 0.8 + exactSubstringBonus);
+}
+/**
+ * The title-only form of the same lexical rank used by work.list text search. A delta whose text
+ * has no searchable tokens (only attachments or symbols) overlaps no title.
+ */
+function workListTitleTextScore(query, title) {
+    if (workListTokens(query).length === 0)
+        return 0;
+    return workListLexicalScore(query, { title, description: '' });
+}
+function workListStatus(item) {
+    const value = workListValueObject(item.values).status;
+    if (typeof value === 'string' && WORK_LIST_STATUSES.includes(value)) {
+        return value;
+    }
+    if (value !== undefined && value !== null) {
+        throw new Error(`work.list encountered a status outside the contract: ${JSON.stringify(value)}`);
+    }
+    return item.withdrawn ? 'cancelled' : 'pending';
+}
+function workListPriority(item) {
+    const value = workListText(workListValueObject(item.values).priority);
+    return value !== null &&
+        WORK_LIST_PRIORITIES.includes(value)
+        ? value
+        : 'normal';
+}
+function workListEventTime(value) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0)
+        return value;
+    if (typeof value === 'string' && Number.isFinite(Date.parse(value)))
+        return Date.parse(value);
+    return null;
+}
+function workListIso(value) {
+    const ms = workListEventTime(value);
+    return ms === null ? null : new Date(ms).toISOString();
+}
+function workListDueState(item, now, timeZone) {
+    const status = workListStatus(item);
+    if (status === 'done' || status === 'cancelled')
+        return 'closed';
+    const values = workListValueObject(item.values);
+    const exact = workListEventTime(values.dueAt ?? values.due_at);
+    if (exact !== null)
+        return exact > now ? 'exact_upcoming' : 'exact_overdue';
+    const deadline = workListText(values.deadline ?? values.due_date);
+    if (deadline === null || !/^\d{4}-\d{2}-\d{2}$/.test(deadline))
+        return 'unscheduled';
+    const deadlineMs = (0, timezone_js_1.epochAtLocalDateTime)(`${deadline}T00:00:00`, timeZone);
+    if (!Number.isFinite(deadlineMs))
+        return 'unscheduled';
+    const today = (0, timezone_js_1.localDateKey)(now, timeZone);
+    if (deadline > today)
+        return 'date_upcoming';
+    if (deadline === today)
+        return 'date_due';
+    return 'date_overdue';
+}
+function workListCompact(item, now, score, timeZone) {
+    const values = workListValueObject(item.values);
+    const status = workListStatus(item);
+    const assignee = workListText(values.assignee ?? values.assigneeText ?? values.assignee_text);
+    const deadline = workListText(values.deadline ?? values.due_date);
+    const sourceChannel = workListText(values.sourceChannel ?? values.source_channel);
+    const sourceEventId = workListText(values.sourceEventId ?? values.source_event_id);
+    const latestEvent = workListText(values.latestEvent ?? values.latest_event);
+    const compact = {
+        id: item.rowId,
+        commitmentId: item.commitmentId,
+        revision: item.revision,
+        title: workListText(values.title),
+        status,
+        stage: workListText(values.stage),
+        project: workListText(values.project),
+        temporal_state: workListDueState(item, now, timeZone),
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+    };
+    const priority = workListPriority(item);
+    if (priority !== 'normal')
+        compact.priority = priority;
+    const optional = [
+        ['assignee', assignee],
+        ['deadline', deadline],
+        ['due_at', workListIso(values.dueAt ?? values.due_at)],
+        [
+            'deadline_offset_minutes',
+            typeof values.deadlineOffsetMinutes === 'number'
+                ? values.deadlineOffsetMinutes
+                : typeof values.deadline_offset_minutes === 'number'
+                    ? values.deadline_offset_minutes
+                    : null,
+        ],
+        ['sourceChannel', sourceChannel],
+        ['sourceEventId', sourceEventId],
+        ['completion_criteria', workListText(values.completionCriteria ?? values.completion_criteria)],
+        ['resolution_kind', workListText(values.resolutionKind ?? values.resolution_kind)],
+        ['latest_event', latestEvent?.replace(/\s+/g, ' ').trim() ?? null],
+        ['lastEventTime', values.lastEventTime ?? values.last_event_time],
+    ];
+    for (const [key, value] of optional) {
+        if (value !== null && value !== undefined)
+            compact[key] = value;
+    }
+    if (values.autoCreated === true || values.auto_created === true)
+        compact.auto_created = true;
+    if (values.confirmed === true)
+        compact.confirmed = true;
+    if (item.withdrawn)
+        compact.withdrawn = true;
+    if (score !== undefined)
+        compact.score = score;
+    return compact;
+}
+function workListMatches(item, filter) {
+    const values = workListValueObject(item.values);
+    if (filter.status !== undefined && !filter.status.includes(workListStatus(item)))
+        return false;
+    if (filter.stage !== undefined && workListText(values.stage) !== filter.stage)
+        return false;
+    if (filter.project !== undefined && workListText(values.project) !== filter.project)
+        return false;
+    if (filter.changedSince !== undefined && item.updatedAt < filter.changedSince)
+        return false;
+    return true;
+}
+/**
+ * Rank by the owner's words, not by substring: token overlap after NFKC and
+ * splitting on spaces, underscores, punctuation and letter/number boundaries,
+ * plus a bonus when the query is contained with separators removed. An item
+ * sharing no token is not a match. Embeddings were measured and dropped: on
+ * the live ledger e5 gave every title ~0.8 cosine (no separation, a
+ * transliterated Korean name ranked a different item first) and the first
+ * query embedded all items for 80 s.
+ */
+function workListRankedItems(items, filter) {
+    const filtered = items.filter((item) => workListMatches(item, filter));
+    if (filter.text === undefined)
+        return filtered.map((item) => ({ item }));
+    const query = filter.text;
+    return filtered
+        .map((item) => ({ item, score: workListLexicalScore(query, workListSearchFields(item)) }))
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => right.score - left.score || right.item.updatedAt - left.item.updatedAt);
+}
+function workListFingerprint(filter) {
+    return (0, node_crypto_1.createHash)('sha256')
+        .update(JSON.stringify([
+        filter.status === undefined ? null : [...filter.status].sort(),
+        filter.stage ?? null,
+        filter.project ?? null,
+        filter.text ?? null,
+        filter.asOf ?? null,
+        filter.changedSince ?? null,
+    ]))
+        .digest('base64url')
+        .slice(0, 22);
+}
+function workListReadVersion(items) {
+    const state = items.map((item) => ({
+        commitmentId: item.commitmentId,
+        rowId: item.rowId,
+        revision: item.revision,
+        latestJudgmentRef: item.latestJudgmentRef,
+        values: item.values,
+        withdrawn: item.withdrawn,
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+    }));
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(state)).digest('base64url');
+}
+function workListReadSnapshot(ctx, filter) {
+    const items = [];
+    const incompleteReasons = [];
+    let cursor;
+    for (;;) {
+        const query = {
+            history: 'current',
+            limit: 100,
+            ...(filter.asOf === undefined ? {} : { asOf: filter.asOf }),
+            ...(cursor === undefined ? {} : { cursor }),
+        };
+        const page = ctx.knowledge.readWork(query, ctx.access);
+        items.push(...page.items);
+        incompleteReasons.push(...page.coverage.reasons.filter((reason) => reason !== 'more commitments follow this page'));
+        if (incompleteReasons.length > 0) {
+            throw new Error(`work.list read is incomplete: ${incompleteReasons.join('; ')}`);
+        }
+        if (page.nextCursor === null) {
+            break;
+        }
+        cursor = page.nextCursor;
+    }
+    const observedAt = ctx.now?.() ?? Date.now();
+    if (!Number.isSafeInteger(observedAt) || observedAt < 0) {
+        throw new Error('work.list observed time must be a non-negative epoch-millisecond integer');
+    }
+    return { items: Object.freeze(items), readVersion: workListReadVersion(items), observedAt };
+}
+function readOpenWorkCandidates(ctx) {
+    const snapshot = workListReadSnapshot(ctx, {});
+    return snapshot.items.flatMap((item) => {
+        if (['done', 'cancelled'].includes(workListStatus(item)))
+            return [];
+        const values = workListValueObject(item.values);
+        const title = workListText(values.title);
+        if (!title)
+            return [];
+        return [
+            {
+                commitmentId: item.commitmentId,
+                title,
+                stage: workListText(values.stage) ?? 'Unstaged',
+                assignee: workListText(values.assignee ?? values.assigneeText ?? values.assignee_text) ?? '',
+                sourceChannel: workListText(values.sourceChannel ?? values.source_channel ?? values.channel) ?? '',
+                updatedAt: typeof item.updatedAt === 'number' ? item.updatedAt : Date.parse(item.updatedAt),
+            },
+        ];
+    });
+}
+function encodeWorkListCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64url');
+}
+/** The filter a cursor carries; malformed cursors are rejected by decodeWorkListCursor. */
+function workListCursorQuery(value) {
+    if (typeof value !== 'string' || value === '' || value.length > 4_096)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const query = parsed?.query;
+    return query !== null && typeof query === 'object' && !Array.isArray(query)
+        ? workListFilter(query)
+        : undefined;
+}
+function decodeWorkListCursor(value, filter) {
+    if (value === '') {
+        throw new Error('work.list cursor is empty; omit cursor to start from the first page');
+    }
+    if (typeof value !== 'string' || value.length > 4_096) {
+        throw new Error('work.list cursor is malformed; restart the items read from the first page');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new Error('work.list cursor is malformed; restart the items read from the first page');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('work.list cursor is malformed; restart the items read from the first page');
+    }
+    const candidate = parsed;
+    if (candidate.v !== 1 ||
+        typeof candidate.filter !== 'string' ||
+        typeof candidate.readVersion !== 'string' ||
+        !Number.isSafeInteger(candidate.offset) ||
+        candidate.offset < 0) {
+        throw new Error('work.list cursor is malformed; restart the items read from the first page');
+    }
+    if (candidate.filter !== workListFingerprint(filter)) {
+        throw new Error('work.list cursor belongs to a different query; restart the items read from the first page');
+    }
+    return candidate;
+}
+function workListTextWindow(value, offset, limit) {
+    const points = Array.from(value);
+    const start = Math.min(offset, points.length);
+    const slice = points.slice(start, start + limit);
+    const end = start + slice.length;
+    const nextOffset = end < points.length ? end : null;
+    return {
+        value: slice.join(''),
+        offset,
+        limit,
+        total: points.length,
+        nextOffset,
+        complete: nextOffset === null,
+    };
+}
+function workListDetailIds(value) {
+    if (!Array.isArray(value) || value.length < 1 || value.length > WORK_LIST_MAX_DETAIL_IDS) {
+        throw new Error(`work.list detail ids must contain 1 to ${WORK_LIST_MAX_DETAIL_IDS} ids`);
+    }
+    const ids = value.map((id) => {
+        if ((typeof id !== 'string' && typeof id !== 'number') ||
+            (typeof id === 'string' && id.trim() === '') ||
+            (typeof id === 'number' && (!Number.isSafeInteger(id) || id < 1))) {
+            throw new Error('work.list detail ids must be nonblank commitment ids or positive row ids');
+        }
+        return id;
+    });
+    if (new Set(ids).size !== ids.length)
+        throw new Error('work.list detail ids must be distinct');
+    return ids;
+}
+function workListDetailRecord(item, textOffset, textLimit, now, timeZone) {
+    if (item.history === undefined)
+        throw new Error('work.list detail did not return revision history');
+    const values = workListValueObject(item.values);
+    const detailedValues = { ...values };
+    for (const field of ['title', 'description', 'latestEvent']) {
+        const value = values[field];
+        if (typeof value === 'string')
+            detailedValues[field] = workListTextWindow(value, textOffset, textLimit);
+    }
+    const compact = workListCompact(item, now, undefined, timeZone);
+    return {
+        ...compact,
+        title: typeof values.title === 'string'
+            ? workListTextWindow(values.title, textOffset, textLimit)
+            : null,
+        description: typeof values.description === 'string'
+            ? workListTextWindow(values.description, textOffset, textLimit)
+            : null,
+        latestEvent: typeof values.latestEvent === 'string'
+            ? workListTextWindow(values.latestEvent, textOffset, textLimit)
+            : null,
+        values: detailedValues,
+        basis: item.basis,
+        history: item.history,
+        latestJudgmentRef: item.latestJudgmentRef,
+    };
+}
+function workListDetail(input, ctx) {
+    const ids = workListDetailIds(input.ids);
+    const textOffset = workListNonNegativeInteger(input.text_offset, 'text_offset', 0);
+    const textLimit = workListInteger(input.text_limit, 'text_limit', WORK_LIST_DEFAULT_TEXT_LIMIT, 1, WORK_LIST_MAX_TEXT_LIMIT);
+    const asOf = workListAsOf(input.asOf);
+    const now = ctx.now?.() ?? Date.now();
+    const tasks = [];
+    const missingIds = [];
+    for (const id of ids) {
+        const query = {
+            history: 'all',
+            ...(asOf === undefined ? {} : { asOf }),
+            ...(typeof id === 'number' ? { rowId: id } : { commitmentId: id }),
+        };
+        const page = ctx.knowledge.readWork(query, ctx.access);
+        const item = page.items[0];
+        if (item === undefined) {
+            missingIds.push(id);
+            continue;
+        }
+        tasks.push(workListDetailRecord(item, textOffset, textLimit, now, ctx.timeZone));
+    }
+    return {
+        success: true,
+        view: 'detail',
+        tasks,
+        missingIds,
+        observedAt: new Date(now).toISOString(),
+    };
+}
+function workListOverview(snapshot, rankedItems, now, timeZone) {
+    const items = rankedItems.map(({ item }) => item);
+    const status = Object.fromEntries(WORK_LIST_STATUSES.map((name) => [name, 0]));
+    const priority = Object.fromEntries(WORK_LIST_PRIORITIES.map((name) => [name, 0]));
+    const channels = new Map();
+    const assignees = new Map();
+    const due = { missing: 0, overdue: 0, upcoming: 0, closed: 0 };
+    for (const item of items) {
+        const values = workListValueObject(item.values);
+        const itemStatus = workListStatus(item);
+        status[itemStatus] += 1;
+        const itemPriority = workListPriority(item);
+        priority[itemPriority] = (priority[itemPriority] ?? 0) + 1;
+        const channel = workListText(values.sourceChannel ?? values.source_channel);
+        channels.set(channel, (channels.get(channel) ?? 0) + 1);
+        const assignee = workListText(values.assignee ?? values.assigneeText ?? values.assignee_text);
+        assignees.set(assignee, (assignees.get(assignee) ?? 0) + 1);
+        const temporal = workListDueState(item, now, timeZone);
+        if (temporal === 'closed')
+            due.closed += 1;
+        else if (temporal === 'unscheduled')
+            due.missing += 1;
+        else if (temporal.endsWith('overdue'))
+            due.overdue += 1;
+        else
+            due.upcoming += 1;
+    }
+    const sortedFacet = (values) => [...values.entries()]
+        .sort((left, right) => String(left[0] ?? '').localeCompare(String(right[0] ?? '')))
+        .map(([value, count]) => ({
+        [values === channels ? 'channel' : 'assignee']: value,
+        count,
+    }));
+    const channelRows = sortedFacet(channels).map((row) => ({
+        channel: row.channel,
+        count: row.count,
+    }));
+    const assigneeRows = sortedFacet(assignees).map((row) => ({
+        assignee: row.assignee,
+        count: row.count,
+    }));
+    return {
+        success: true,
+        view: 'overview',
+        total: items.length,
+        observedAt: new Date(snapshot.observedAt).toISOString(),
+        readVersion: snapshot.readVersion,
+        status,
+        priority,
+        channels: channelRows,
+        assignees: assigneeRows,
+        due,
+    };
+}
+async function runWorkListView(rawInput, ctx) {
+    const input = workListObject(rawInput);
+    const view = input.view === undefined ? 'items' : input.view;
+    if (view !== 'overview' && view !== 'items' && view !== 'detail' && view !== 'pipeline') {
+        throw new Error('work.list view must be one of overview|items|detail|pipeline');
+    }
+    if (input.ids !== undefined && view !== 'detail') {
+        throw new Error('work.list ids are only valid with view=detail');
+    }
+    if (view === 'detail')
+        return workListDetail(input, ctx);
+    const requested = workListFilter(input);
+    const filter = input.cursor !== undefined && Object.keys(requested).length === 0
+        ? (workListCursorQuery(input.cursor) ?? requested)
+        : requested;
+    const snapshot = workListReadSnapshot(ctx, filter);
+    const now = ctx.now?.() ?? snapshot.observedAt;
+    if (input.readVersion !== undefined && input.readVersion !== snapshot.readVersion) {
+        throw new Error('work.list readVersion changed; restart the items read from the first page');
+    }
+    if (view === 'pipeline') {
+        const open = snapshot.items.filter((item) => !['done', 'cancelled'].includes(workListStatus(item)));
+        const groups = new Map();
+        const fields = [
+            'commitmentId',
+            'title',
+            'status',
+            'assignee',
+            'deadline',
+            'latest_change',
+            'latest_event',
+        ];
+        for (const item of open) {
+            const values = workListValueObject(item.values);
+            const stage = workListText(values.stage) ?? 'Unstaged';
+            const group = groups.get(stage) ?? [];
+            const latestEvent = workListText(values.latestEvent ?? values.latest_event);
+            group.push([
+                item.commitmentId,
+                workListText(values.title),
+                workListStatus(item),
+                workListText(values.assignee ?? values.assigneeText ?? values.assignee_text),
+                workListText(values.deadline ?? values.due_date),
+                Math.trunc(typeof item.updatedAt === 'number'
+                    ? item.updatedAt / 1_000
+                    : Date.parse(item.updatedAt) / 1_000),
+                latestEvent?.replace(/\s+/g, ' ').trim() ?? null,
+            ]);
+            groups.set(stage, group);
+        }
+        return {
+            success: true,
+            view: 'pipeline',
+            fields,
+            stages: [...groups.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([stage, rows]) => ({ stage, count: rows.length, rows })),
+            total: open.length,
+            observedAt: new Date(snapshot.observedAt).toISOString(),
+        };
+    }
+    if (view === 'overview') {
+        const rankedItems = workListRankedItems(snapshot.items, filter);
+        return workListOverview(snapshot, rankedItems, now, ctx.timeZone);
+    }
+    const limit = workListInteger(input.limit, 'limit', WORK_LIST_DEFAULT_LIMIT, 1, WORK_LIST_MAX_LIMIT);
+    const decoded = input.cursor === undefined ? null : decodeWorkListCursor(input.cursor, filter);
+    if (decoded !== null && decoded.readVersion !== snapshot.readVersion) {
+        throw new Error('work.list board changed since this cursor was issued; restart the items read from the first page');
+    }
+    const rankedItems = workListRankedItems(snapshot.items, filter);
+    const offset = decoded?.offset ?? 0;
+    const page = rankedItems.slice(offset, offset + limit);
+    const nextOffset = offset + page.length < rankedItems.length ? offset + page.length : null;
+    return {
+        success: true,
+        view: 'items',
+        tasks: page.map(({ item, score }) => workListCompact(item, now, score, ctx.timeZone)),
+        total: rankedItems.length,
+        returned: page.length,
+        nextCursor: nextOffset === null
+            ? null
+            : encodeWorkListCursor({
+                v: 1,
+                filter: workListFingerprint(filter),
+                query: filter,
+                readVersion: snapshot.readVersion,
+                offset: nextOffset,
+            }),
+        observedAt: new Date(snapshot.observedAt).toISOString(),
+        readVersion: snapshot.readVersion,
+    };
+}
+/** Archive callers used this name; keep the carried view contract name at the action boundary. */
+exports.runTaskListView = runWorkListView;
+function workListActionRegistrations(ports) {
+    return [
+        {
+            contract: {
+                name: 'work.list',
+                summary: 'Read owner work progressively: overview counts, a compact open-work pipeline grouped by stage. Each pipeline row is an array using the top-level fields order (commitmentId, title, status, assignee, deadline, latest_change in epoch seconds, latest_event). Pipeline returns the whole open ledger and ignores limit; bounded items pages are capped at 50. Use detail for evidence and revision history.',
+                inputSchema: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        view: { type: 'string', enum: ['overview', 'items', 'detail', 'pipeline'] },
+                        ids: {
+                            type: 'array',
+                            minItems: 1,
+                            maxItems: WORK_LIST_MAX_DETAIL_IDS,
+                            items: {
+                                oneOf: [
+                                    { type: 'string', minLength: 1 },
+                                    { type: 'integer', minimum: 1 },
+                                ],
+                            },
+                        },
+                        limit: { type: 'integer', minimum: 1, maximum: WORK_LIST_MAX_LIMIT },
+                        cursor: { type: 'string', minLength: 0 },
+                        readVersion: {
+                            type: 'string',
+                            minLength: 1,
+                            description: 'Optional echoed read version; must match the current read.',
+                        },
+                        status: {
+                            oneOf: [
+                                { type: 'string', enum: WORK_LIST_STATUSES },
+                                { type: 'array', minItems: 1, items: { type: 'string', enum: WORK_LIST_STATUSES } },
+                            ],
+                        },
+                        stage: { type: 'string' },
+                        project: { type: 'string' },
+                        text: { type: 'string' },
+                        asOf: { type: 'integer', minimum: 0 },
+                        changedSince: {
+                            type: 'integer',
+                            minimum: 0,
+                            description: 'Only items written at or after this epoch-ms time, e.g. the start of your turn.',
+                        },
+                        text_offset: { type: 'integer', minimum: 0 },
+                        text_limit: { type: 'integer', minimum: 1, maximum: WORK_LIST_MAX_TEXT_LIMIT },
+                        history: { type: 'string', enum: ['current', 'all'] },
+                    },
+                },
+                examples: [
+                    { title: 'Work overview', input: { view: 'overview' } },
+                    { title: 'Open work pipeline', input: { view: 'pipeline' } },
+                    { title: 'First work page', input: { view: 'items', limit: WORK_LIST_DEFAULT_LIMIT } },
+                    { title: 'Work detail', input: { view: 'detail', ids: ['commitment-reference'] } },
+                ],
+            },
+            exec: (input, context) => runWorkListView(input, {
+                knowledge: ports.knowledge,
+                access: context.access,
+                timeZone: ports.timeZone.get(),
+            }),
+        },
+    ];
+}
+const nullableText = {
+    description: 'Optional text value; null clears the field, e.g. "reviewed" or null.',
+    oneOf: [{ type: 'string' }, { type: 'null' }],
+};
+const workFileSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        locator: { type: 'string', minLength: 1, description: 'Relevant file locator.' },
+        version: { type: 'string', minLength: 1, description: 'Relevant file version.' },
+        hash: { type: 'string', minLength: 1, description: 'Relevant file content hash.' },
+    },
+    required: ['locator', 'version', 'hash'],
+};
+const workRoleSchema = {
+    type: 'object',
+    additionalProperties: true,
+    properties: {
+        personRef: { type: 'string', minLength: 1, description: 'Person reference for the role.' },
+        role: { type: 'string', minLength: 1, description: 'Role judged from evidence.' },
+        evidenceRefs: {
+            type: 'array',
+            description: 'Stable observationRef handles supporting the role.',
+            items: { type: 'string', minLength: 1 },
+        },
+        confirmed: {
+            type: 'boolean',
+            description: 'True when evidence confirms the role; false is the explicit unconfirmed status.',
+        },
+    },
+};
+const workPatchSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        title: { ...nullableText, description: 'Work title, e.g. "Prepare release" or null.' },
+        description: {
+            ...nullableText,
+            description: 'Work description, e.g. "Collect review" or null.',
+        },
+        status: {
+            description: 'Work status: pending, in_progress, review, blocked, done or cancelled; or null. The owner stage stays in stage.',
+            oneOf: [
+                {
+                    type: 'string',
+                    enum: ['pending', 'in_progress', 'review', 'blocked', 'done', 'cancelled'],
+                },
+                { type: 'null' },
+            ],
+        },
+        priority: { ...nullableText, description: 'Work priority, e.g. "high" or null.' },
+        dueAt: { ...nullableText, description: 'Due-time text, e.g. "2026-09-30" or null.' },
+        deadline: { ...nullableText, description: 'Deadline text, e.g. "Friday" or null.' },
+        deadlineOffsetMinutes: {
+            description: 'Deadline offset from the stated event, e.g. 60 or null.',
+            oneOf: [{ type: 'integer', minimum: -840, maximum: 840 }, { type: 'null' }],
+        },
+        stage: { ...nullableText, description: 'Current work stage, or null to clear it.' },
+        project: {
+            ...nullableText,
+            description: 'project associated with the work, or null to clear it.',
+        },
+        lastEventTime: {
+            ...nullableText,
+            description: 'Timezone-qualified ISO timestamp for the source event time, not replay time, or null.',
+        },
+        files: {
+            description: 'Relevant file locator/version/hash entries preserved with the work, or null.',
+            oneOf: [{ type: 'array', items: workFileSchema }, { type: 'null' }],
+        },
+        completionCriteria: {
+            type: 'string',
+            pattern: '\\S',
+            description: 'Evidence-based completion rule, e.g. "Owner approves".',
+        },
+        assignee: { ...nullableText, description: 'Assigned person text, e.g. "person_123" or null.' },
+        assigneeText: {
+            ...nullableText,
+            description: 'Unresolved assignee text, e.g. "reviewer" or null.',
+        },
+        latestEvent: {
+            ...nullableText,
+            description: 'Latest work event text, e.g. "review requested" or null.',
+        },
+        confirmed: {
+            description: 'Whether the patch is confirmed, e.g. true or null.',
+            oneOf: [{ type: 'boolean' }, { type: 'null' }],
+        },
+        roles: {
+            description: 'Evidence-backed role entries with personRef, role, evidenceRefs and confirmed; use false for an explicit unconfirmed status, or null.',
+            oneOf: [{ type: 'array', items: workRoleSchema }, { type: 'null' }],
+        },
+        data: {
+            description: 'Product-specific structured fields, e.g. {"stage":"review"} or null.',
+            oneOf: [{ type: 'object' }, { type: 'null' }],
+        },
+    },
+};
+const commandFields = {
+    topic: { type: 'string', minLength: 1, description: 'Work topic key, e.g. "release".' },
+    summary: {
+        type: 'string',
+        minLength: 1,
+        description: 'What changed and why, e.g. "Review is requested".',
+    },
+    reasoning: {
+        type: 'string',
+        minLength: 1,
+        description: 'Decision reasoning, e.g. "The source confirms the handoff".',
+    },
+    scopes: {
+        type: 'array',
+        description: 'Work visibility scopes, e.g. [{"kind":"project","id":"project_123"}].',
+        items: catalog_1.scopeRefSchema,
+    },
+    sourceRefs: {
+        type: 'array',
+        description: 'Stable observationRef citation handles, e.g. ["obs_123"].',
+        items: { type: 'string', minLength: 1 },
+    },
+    links: {
+        type: 'array',
+        description: 'Graph links from this revision: derived_from an observation it rests on; supersedes, amends or refines an earlier record it replaces or corrects; contradicts one it reverses; builds_on or synthesizes records it extends or combines; blocks or next_action_for another work item. E.g. [{"relation":"derived_from","target":{"kind":"observation","id":"obs_123"}}].',
+        items: catalog_1.recordLinkSchema,
+    },
+    eventDatetime: {
+        description: 'Source event time as epoch milliseconds, not replay time, or null, e.g. 1760000000000.',
+        oneOf: [{ type: 'number' }, { type: 'null' }],
+    },
+    recordedAt: {
+        type: 'number',
+        description: 'Record time as epoch milliseconds, e.g. 1760000000000.',
+    },
+    event: { type: 'object', description: 'Structured event details, e.g. {"kind":"review"}.' },
+};
+const createSchema = {
+    type: 'object',
+    required: ['topic', 'summary', 'set'],
+    additionalProperties: false,
+    properties: {
+        ...commandFields,
+        set: {
+            ...workPatchSchema,
+            description: 'Fields to set on the new work item, e.g. {"title":"Prepare release"}.',
+        },
+    },
+};
+const reviseSchema = {
+    type: 'object',
+    required: ['commitmentId', 'topic', 'summary'],
+    additionalProperties: false,
+    properties: {
+        ...commandFields,
+        commitmentId: {
+            type: 'string',
+            minLength: 1,
+            description: 'stable commitmentId citation handle to revise, e.g. "commitment_123".',
+        },
+        expectedRevision: {
+            type: 'integer',
+            minimum: 0,
+            description: 'Optional revision read before editing; when omitted, the latest owner revision is appended.',
+        },
+        set: {
+            ...workPatchSchema,
+            description: 'Fields to update on the existing work item, e.g. {"assignee":null}.',
+        },
+        clear: {
+            type: 'array',
+            description: 'Patch fields to clear, e.g. ["assignee"].',
+            items: { type: 'string' },
+        },
+    },
+};
+function operationId(context, action) {
+    if (typeof context.operationId !== 'string' || context.operationId.trim() === '') {
+        throw new knowledge_1.JudgmentError('INVALID_COMMAND', `${action} requires operationId`);
+    }
+    return context.operationId;
+}
+function assertSourceRefsExist(body, ports) {
+    if (!Array.isArray(body.sourceRefs))
+        return;
+    for (const ref of body.sourceRefs) {
+        if (typeof ref === 'string' && !ports.observationExists(ref)) {
+            // Echo only the caller's own input, as the core reference refusal does.
+            throw new knowledge_1.JudgmentError('REFERENCE_NOT_FOUND', `sourceRefs names an unavailable observation: ${ref}`);
+        }
+    }
+}
+function commandFieldsFrom(body) {
+    const { commitmentId: _commitmentId, expectedRevision: _expectedRevision, ...fields } = body;
+    return fields;
+}
+function assertReplayEventDatetime(body, context, action) {
+    const ceiling = context.session?.replaySourceEndMs;
+    if (ceiling === undefined)
+        return;
+    if (!Number.isSafeInteger(ceiling) || ceiling < 0) {
+        throw new knowledge_1.JudgmentError('REPLAY_SOURCE_CEILING_INVALID', 'Replay source ceiling must be a nonnegative epoch millisecond integer');
+    }
+    const eventDatetime = body.eventDatetime;
+    if (typeof eventDatetime !== 'number' ||
+        !Number.isSafeInteger(eventDatetime) ||
+        eventDatetime <= 0) {
+        throw new knowledge_1.JudgmentError('REPLAY_EVENT_TIME_REQUIRED', `${action} requires eventDatetime during replay`);
+    }
+    if (eventDatetime > ceiling) {
+        throw new knowledge_1.JudgmentError('REPLAY_EVENT_TIME_AFTER_CEILING', `${action} eventDatetime is later than the active replay source ceiling`);
+    }
+}
+function minimalWorkActionRegistrations(ports) {
+    return [
+        {
+            contract: {
+                name: 'work.create',
+                recallableWrite: true,
+                summary: 'Create one owner-work commitment. Product fields such as assignee and roles remain part of the revision patch; links with relation derived_from cite the observations the work rests on.',
+                inputSchema: createSchema,
+                examples: [
+                    {
+                        title: 'Create owner work',
+                        input: {
+                            topic: 'work topic',
+                            summary: 'what the work means',
+                            set: { title: 'work title', assignee: 'assignee', roles: [] },
+                        },
+                    },
+                ],
+            },
+            exec: (input, context) => {
+                const body = input;
+                assertReplayEventDatetime(body, context, 'work.create');
+                assertSourceRefsExist(body, ports);
+                return ports.knowledge.createWork({
+                    ...body,
+                    ...commandFieldsFrom(body),
+                    commandId: operationId(context, 'work.create'),
+                    modelRunId: context.session?.modelRunId,
+                }, context.access);
+            },
+        },
+        {
+            contract: {
+                name: 'work.revise',
+                recallableWrite: true,
+                summary: 'Append a revision to owner work. expectedRevision is optional for the single owner writer; when supplied it rejects a stale write. The required summary states what changed and why. Links with relation derived_from cite the observations the revision rests on.',
+                inputSchema: reviseSchema,
+                examples: [
+                    {
+                        title: 'Revise assignee and roles',
+                        input: {
+                            commitmentId: 'commitment-reference',
+                            expectedRevision: 1,
+                            topic: 'work topic',
+                            summary: 'what changed and why',
+                            set: { assignee: null, roles: [] },
+                        },
+                    },
+                ],
+            },
+            exec: (input, context) => {
+                const body = input;
+                assertReplayEventDatetime(body, context, 'work.revise');
+                assertSourceRefsExist(body, ports);
+                const commitmentId = body.commitmentId;
+                return ports.knowledge.reviseWork({
+                    ...commandFieldsFrom(body),
+                    commitmentId,
+                    ...(body.expectedRevision === undefined
+                        ? {}
+                        : { expectedRevision: body.expectedRevision }),
+                    commandId: operationId(context, 'work.revise'),
+                    modelRunId: context.session?.modelRunId,
+                }, context.access);
+            },
+        },
+    ];
+}
+//# sourceMappingURL=work-actions.js.map