@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/relationship-lock.js

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+const locks = new Map();
+export async function withRelationshipLock(itemIds, operation) {
+    const releases = [];
+    const acquired = [...new Set(itemIds)].sort();
+    for (const itemId of acquired) {
+        const previous = locks.get(itemId) ?? Promise.resolve();
+        let release = () => undefined;
+        const current = new Promise((resolve) => {
+            release = () => resolve();
+        });
+        locks.set(itemId, current);
+        await previous;
+        releases.push(() => {
+            release();
+            if (locks.get(itemId) === current) {
+                locks.delete(itemId);
+            }
+        });
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        for (const release of releases.reverse())
+            release();
+    }
+}
+//# sourceMappingURL=relationship-lock.js.map

package/dist/core/relationship-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-lock.js","sourceRoot":"","sources":["../../src/core/relationship-lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;AAE/C,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAA0B,EAC1B,SAA2B;IAE3B,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAE9C,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACxD,IAAI,OAAO,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YAC5C,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3B,MAAM,QAAQ,CAAC;QACf,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE;YACjB,OAAO,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC;gBAClC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE;YAAE,OAAO,EAAE,CAAC;IACtD,CAAC;AACH,CAAC"}

package/dist/core/relationship-map.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Canonical relationship orientation map.
+ * Keeps bidirectional persistence and traversal semantics aligned.
+ */
+import type { RelationType } from '../schemas/index.js';
+export declare const INVERSE_RELATIONS: Readonly<Record<RelationType, RelationType>>;
+//# sourceMappingURL=relationship-map.d.ts.map

package/dist/core/relationship-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-map.d.ts","sourceRoot":"","sources":["../../src/core/relationship-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CAgB1E,CAAC"}

package/dist/core/relationship-map.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Canonical relationship orientation map.
+ * Keeps bidirectional persistence and traversal semantics aligned.
+ */
+export const INVERSE_RELATIONS = {
+    implements: 'implemented-by',
+    'implemented-by': 'implements',
+    'tested-by': 'tests',
+    tests: 'tested-by',
+    blocks: 'blocked-by',
+    'blocked-by': 'blocks',
+    'depends-on': 'required-by',
+    'required-by': 'depends-on',
+    'relates-to': 'relates-to',
+    supersedes: 'superseded-by',
+    'superseded-by': 'supersedes',
+    'canonical-for': 'derived-from',
+    'derived-from': 'canonical-for',
+    'documented-by': 'documents',
+    documents: 'documented-by',
+};
+//# sourceMappingURL=relationship-map.js.map

package/dist/core/relationship-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-map.js","sourceRoot":"","sources":["../../src/core/relationship-map.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,CAAC,MAAM,iBAAiB,GAAiD;IAC7E,UAAU,EAAE,gBAAgB;IAC5B,gBAAgB,EAAE,YAAY;IAC9B,WAAW,EAAE,OAAO;IACpB,KAAK,EAAE,WAAW;IAClB,MAAM,EAAE,YAAY;IACpB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,aAAa;IAC3B,aAAa,EAAE,YAAY;IAC3B,YAAY,EAAE,YAAY;IAC1B,UAAU,EAAE,eAAe;IAC3B,eAAe,EAAE,YAAY;IAC7B,eAAe,EAAE,cAAc;IAC/B,cAAc,EAAE,eAAe;IAC/B,eAAe,EAAE,WAAW;IAC5B,SAAS,EAAE,eAAe;CAC3B,CAAC"}

package/dist/core/search.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Full-text search across item titles, descriptions, tags, and commits.
+ * STORY-041: one implementation for the CLI, the MCP server, and the extension.
+ */
+import type { ItemType } from '../schemas/index.js';
+/** Hits returned when the caller does not ask for a specific number. */
+export declare const SEARCH_DEFAULT_LIMIT = 20;
+export type SearchMatchType = 'id' | 'title' | 'description' | 'tag' | 'commit';
+export interface SearchHit {
+    id: string;
+    type: string;
+    status: string;
+    title: string;
+    match_type: SearchMatchType;
+    excerpt?: string;
+}
+export interface SearchItemsArgs {
+    query: string;
+    type?: ItemType;
+    /** Maximum hits to return; the total keeps counting past it. */
+    limit?: number;
+    /** true searches only items carrying a `process_definition`, false only the rest. */
+    has_definition?: boolean;
+}
+export interface SearchItemsResult {
+    query: string;
+    total: number;
+    returned: number;
+    results: SearchHit[];
+    /** Hit counts per category over every hit, so a search leads to the same leaf `list` shows. */
+    refine?: {
+        category: Record<string, number>;
+    };
+    truncated?: true;
+    more?: string;
+}
+/**
+ * Build the predicate for one query: `*` wildcards become a regex, several words must
+ * all occur (AND), and a single word is a case-insensitive substring match.
+ */
+export declare function buildSearchMatcher(rawQuery: string): (text: string) => boolean;
+/**
+ * Search items by query.
+ *
+ * Every candidate is scanned even once `limit` hits are collected, so the total is honest
+ * and the caller can judge whether to narrow the query. Hits carry only what is needed
+ * to decide what to open next; `getItem` serves the detail.
+ */
+export declare function searchItems(devstepsDir: string, args: SearchItemsArgs): Promise<SearchItemsResult>;
+//# sourceMappingURL=search.d.ts.map

package/dist/core/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/core/search.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAIpD,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAIvC,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,OAAO,GAAG,aAAa,GAAG,KAAK,GAAG,QAAQ,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,+FAA+F;IAC/F,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IAC9C,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAU9E;AAgBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAqE5B"}

package/dist/core/search.js

@@ -0,0 +1,122 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Full-text search across item titles, descriptions, tags, and commits.
+ * STORY-041: one implementation for the CLI, the MCP server, and the extension.
+ */
+import { existsSync } from 'node:fs';
+import { readAllItems } from './item-store.js';
+import { matchesDefinitionFilter } from './list.js';
+/** Hits returned when the caller does not ask for a specific number. */
+export const SEARCH_DEFAULT_LIMIT = 20;
+/** Characters of surrounding description text carried per hit. */
+const EXCERPT_LENGTH = 160;
+/**
+ * Build the predicate for one query: `*` wildcards become a regex, several words must
+ * all occur (AND), and a single word is a case-insensitive substring match.
+ */
+export function buildSearchMatcher(rawQuery) {
+    const query = rawQuery.toLowerCase();
+    const regexPattern = query.includes('*') ? new RegExp(query.replace(/\*/g, '.*'), 'i') : null;
+    const tokens = query.split(/\s+/).filter((token) => token.length > 0);
+    return (text) => {
+        const lowerText = text.toLowerCase();
+        if (regexPattern)
+            return regexPattern.test(lowerText);
+        if (tokens.length > 1)
+            return tokens.every((token) => lowerText.includes(token));
+        return lowerText.includes(query);
+    };
+}
+/**
+ * Cut an excerpt around the first hit rather than from the top of the text —
+ * the opening lines of a description rarely contain the term that matched.
+ */
+function buildExcerpt(description, query) {
+    const at = description.toLowerCase().indexOf(query.toLowerCase());
+    const start = at < 0 ? 0 : Math.max(0, at - EXCERPT_LENGTH / 4);
+    const excerpt = description
+        .slice(start, start + EXCERPT_LENGTH)
+        .replace(/\s+/g, ' ')
+        .trim();
+    return start > 0 ? `…${excerpt}` : excerpt;
+}
+/**
+ * Search items by query.
+ *
+ * Every candidate is scanned even once `limit` hits are collected, so the total is honest
+ * and the caller can judge whether to narrow the query. Hits carry only what is needed
+ * to decide what to open next; `getItem` serves the detail.
+ */
+export async function searchItems(devstepsDir, args) {
+    if (!existsSync(devstepsDir)) {
+        throw new Error('Project not initialized. Run devsteps-init first.');
+    }
+    const matches = buildSearchMatcher(args.query);
+    // An exact item ID is a lookup, not a substring: `task` must not hit every TASK-nnn (BUG-178).
+    const exactId = args.query.trim().toUpperCase();
+    // A bare number names the items with that number: `1040` finds TASK-1040 (BUG-251).
+    const exactNumber = /^\d+$/.test(exactId) ? Number(exactId) : undefined;
+    const isNamed = (id) => id === exactId || Number(id.slice(id.lastIndexOf('-') + 1)) === exactNumber;
+    const limit = args.limit && args.limit > 0 ? args.limit : SEARCH_DEFAULT_LIMIT;
+    // One pass over the store: metadata and description come together (STORY-426).
+    const { items } = readAllItems(devstepsDir, args.type);
+    const results = [];
+    const byCategory = {};
+    let total = 0;
+    for (const { metadata, description } of items) {
+        if (!matchesDefinitionFilter(metadata, args.has_definition))
+            continue;
+        const matchType = isNamed(metadata.id)
+            ? 'id'
+            : matches(metadata.title)
+                ? 'title'
+                : matches(description)
+                    ? 'description'
+                    : metadata.tags.some((tag) => matches(tag))
+                        ? 'tag'
+                        : metadata.commits.some((hash) => matches(hash))
+                            ? 'commit'
+                            : null;
+        if (!matchType)
+            continue;
+        total += 1;
+        byCategory[metadata.category] = (byCategory[metadata.category] ?? 0) + 1;
+        if (results.length >= limit && matchType !== 'id')
+            continue;
+        const hit = {
+            id: metadata.id,
+            type: metadata.type,
+            status: metadata.status,
+            title: metadata.title,
+            match_type: matchType,
+            // Only when the description is what matched — for a title hit the
+            // excerpt would just repeat the title back.
+            ...(matchType === 'description' ? { excerpt: buildExcerpt(description, args.query) } : {}),
+        };
+        if (matchType !== 'id') {
+            results.push(hit);
+            continue;
+        }
+        // The item the caller named comes first, even past the limit.
+        results.unshift(hit);
+        if (results.length > limit)
+            results.pop();
+    }
+    const omitted = total - results.length;
+    return {
+        query: args.query,
+        total,
+        returned: results.length,
+        results,
+        ...(total > 0 ? { refine: { category: byCategory } } : {}),
+        ...(omitted > 0
+            ? {
+                truncated: true,
+                more: `${omitted} further hit(s) not shown — narrow the query, add type, or raise limit (current: ${limit}).`,
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/core/search.js.map

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

package/dist/core/task-workflow-loader.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TASK workflow definition loader
+ * Reads item-owned workflow declarations and validates identity, inputs, scope, and drift.
+ * The loader returns data for the neutral runtime; it does not execute workflow steps.
+ */
+import type { ProcessRun } from '../runtime/index.js';
+import type { LoadedWorkflowDefinition } from '../runtime/workflow-contract.js';
+import { TaskWorkflowDefinition } from '../schemas/task-workflow.js';
+import { type GetItemResult } from './get.js';
+export type TaskWorkflowLoadOptions = Readonly<{
+    expectedRevision?: string;
+    expectedDigest?: string;
+    actualWorkspaceFingerprint?: string;
+    expectedWorkspaceFingerprint?: string;
+    inputs?: Readonly<Record<string, unknown>>;
+    preconditions?: Readonly<Record<string, boolean>>;
+    scopePaths?: readonly string[];
+    activeRuns?: readonly ProcessRun[];
+}>;
+export type LoadedTaskWorkflow = Readonly<{
+    item: GetItemResult;
+    definition: TaskWorkflowDefinition;
+    definitionRevision: string;
+    definitionDigest: string;
+    workspaceFingerprint?: string;
+    resolvedInputs: Readonly<Record<string, unknown>>;
+}> & LoadedWorkflowDefinition;
+export declare class TaskWorkflowLoadError extends Error {
+    readonly code: 'NOT_TASK' | 'MISSING_DEFINITION' | 'INVALID_DEFINITION' | 'REVISION_DRIFT' | 'DIGEST_DRIFT' | 'WORKSPACE_DRIFT' | 'MISSING_INPUT' | 'UNKNOWN_INPUT' | 'INVALID_INPUT' | 'PRECONDITION_FAILED' | 'SCOPE_VIOLATION' | 'OPEN_RUN';
+    constructor(code: TaskWorkflowLoadError['code'], message: string);
+}
+export declare function loadTaskWorkflowDefinitionFromItem(item: GetItemResult, options?: TaskWorkflowLoadOptions): LoadedTaskWorkflow;
+export declare function loadTaskWorkflowDefinition(devstepsDir: string, itemId: string, options?: TaskWorkflowLoadOptions): Promise<LoadedTaskWorkflow>;
+//# sourceMappingURL=task-workflow-loader.d.ts.map

package/dist/core/task-workflow-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-workflow-loader.d.ts","sourceRoot":"","sources":["../../src/core/task-workflow-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAGhF,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,KAAK,aAAa,EAAW,MAAM,UAAU,CAAC;AAKvD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3C,aAAa,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,UAAU,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CACpC,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,sBAAsB,CAAC;IACnC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD,CAAC,GACA,wBAAwB,CAAC;AAE3B,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAChB,UAAU,GACV,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,GAChB,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,eAAe,GACf,eAAe,GACf,qBAAqB,GACrB,iBAAiB,GACjB,UAAU,CAAC;IAEf,YAAmB,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAItE;CACF;AAuHD,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAgEpB;AAED,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAG7B"}

package/dist/core/task-workflow-loader.js

@@ -0,0 +1,162 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TASK workflow definition loader
+ * Reads item-owned workflow declarations and validates identity, inputs, scope, and drift.
+ * The loader returns data for the neutral runtime; it does not execute workflow steps.
+ */
+import { createHash } from 'node:crypto';
+import { sameWorkspaceFingerprint } from '../runtime/workspace-fingerprint.js';
+import { TaskWorkflowDefinition } from '../schemas/task-workflow.js';
+import { getItem } from './get.js';
+export class TaskWorkflowLoadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TaskWorkflowLoadError';
+        this.code = code;
+    }
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, canonicalize(nested)]));
+}
+function digestDefinition(definition) {
+    const canonical = JSON.stringify(canonicalize(definition));
+    return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+function workflowMetadata(metadata) {
+    return metadata.metadata;
+}
+function rawWorkflowDefinition(metadata) {
+    // `process_definition` is the persisted item contract. Keep accepting the
+    // early nested spelling so existing workspaces remain readable.
+    return metadata.process_definition ?? workflowMetadata(metadata).workflow_definition;
+}
+function resolveRevision(metadata, definitionDigest) {
+    const revision = workflowMetadata(metadata).workflow_revision;
+    return typeof revision === 'string' && revision.length > 0 ? revision : definitionDigest;
+}
+function validateInputValue(type, value) {
+    switch (type) {
+        case 'string':
+        case 'path':
+        case 'secret-reference':
+            return typeof value === 'string' && value.length > 0;
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        default:
+            return false;
+    }
+}
+function resolveInputs(definition, supplied) {
+    // Resolve defaults here so execution receives one complete, validated input set.
+    const declared = new Set(definition.inputs.map((input) => input.name));
+    for (const name of Object.keys(supplied)) {
+        if (!declared.has(name)) {
+            throw new TaskWorkflowLoadError('UNKNOWN_INPUT', `Unknown workflow input: ${name}`);
+        }
+    }
+    const resolved = {};
+    for (const input of definition.inputs) {
+        const value = supplied[input.name] ?? input.default;
+        if (value === undefined && input.required) {
+            throw new TaskWorkflowLoadError('MISSING_INPUT', `Missing required workflow input: ${input.name}`);
+        }
+        if (value !== undefined && !validateInputValue(input.type, value)) {
+            throw new TaskWorkflowLoadError('INVALID_INPUT', `Invalid workflow input: ${input.name}`);
+        }
+        if (value !== undefined)
+            resolved[input.name] = value;
+    }
+    return resolved;
+}
+function validateScope(metadata, scopePaths) {
+    // Scope is checked against the item declaration before any runtime mutation is allowed.
+    const declared = metadata.affected_paths;
+    for (const path of scopePaths) {
+        const isDeclared = declared.some((candidate) => {
+            const normalizedCandidate = candidate.replace(/\*+$/, '').replace(/\/$/, '');
+            return path === normalizedCandidate || path.startsWith(`${normalizedCandidate}/`);
+        });
+        if (!isDeclared) {
+            throw new TaskWorkflowLoadError('SCOPE_VIOLATION', `Path is outside TASK scope: ${path}`);
+        }
+    }
+}
+function validatePreconditions(definition, results) {
+    for (const precondition of definition.preconditions) {
+        if (precondition.required && results[precondition.id] !== true) {
+            throw new TaskWorkflowLoadError('PRECONDITION_FAILED', `TASK precondition failed: ${precondition.id}`);
+        }
+    }
+}
+function validateOpenRuns(definition, activeRuns) {
+    const open = activeRuns.filter((run) => !run.terminal).map((run) => run.run_id);
+    if (!definition.allow_parallel_runs && open.length > 0) {
+        throw new TaskWorkflowLoadError('OPEN_RUN', `TASK definition does not allow parallel runs and run ${open.join(', ')} is still open; ` +
+            'finalize or resume it, or set allow_parallel_runs: true');
+    }
+}
+export function loadTaskWorkflowDefinitionFromItem(item, options = {}) {
+    // Keep TASK-specific discovery and drift checks out of the neutral runtime engine.
+    if (item.metadata.type !== 'task') {
+        throw new TaskWorkflowLoadError('NOT_TASK', `Item ${item.metadata.id} is not a TASK definition`);
+    }
+    const rawDefinition = rawWorkflowDefinition(item.metadata);
+    if (rawDefinition === undefined) {
+        throw new TaskWorkflowLoadError('MISSING_DEFINITION', `TASK ${item.metadata.id} has no workflow definition`);
+    }
+    const parsed = TaskWorkflowDefinition.safeParse(rawDefinition);
+    if (!parsed.success) {
+        throw new TaskWorkflowLoadError('INVALID_DEFINITION', parsed.error.message);
+    }
+    const definition = parsed.data;
+    const definitionDigest = digestDefinition(definition);
+    const definitionRevision = resolveRevision(item.metadata, definitionDigest);
+    const storedWorkspace = workflowMetadata(item.metadata).workspace_fingerprint;
+    const workspaceFingerprint = typeof storedWorkspace === 'string' ? storedWorkspace : undefined;
+    if (options.expectedRevision && options.expectedRevision !== definitionRevision) {
+        throw new TaskWorkflowLoadError('REVISION_DRIFT', 'TASK workflow revision has changed');
+    }
+    if (options.expectedDigest && options.expectedDigest !== definitionDigest) {
+        throw new TaskWorkflowLoadError('DIGEST_DRIFT', 'TASK workflow definition digest has changed');
+    }
+    // BUG-116: the item pin `metadata.workspace_fingerprint` is optional. Only an item that
+    // declares one constrains which workspace may run it; an undeclared pin matches every run.
+    for (const candidate of [
+        options.expectedWorkspaceFingerprint,
+        options.actualWorkspaceFingerprint,
+    ]) {
+        if (candidate &&
+            workspaceFingerprint &&
+            !sameWorkspaceFingerprint(candidate, workspaceFingerprint)) {
+            throw new TaskWorkflowLoadError('WORKSPACE_DRIFT', `TASK ${item.metadata.id} is pinned to workspace fingerprint "${workspaceFingerprint}" but "${candidate}" was supplied`);
+        }
+    }
+    if (options.scopePaths)
+        validateScope(item.metadata, options.scopePaths);
+    validatePreconditions(definition, options.preconditions ?? {});
+    validateOpenRuns(definition, options.activeRuns ?? []);
+    return {
+        item,
+        definition,
+        definitionRevision,
+        definitionDigest,
+        workspaceFingerprint,
+        resolvedInputs: resolveInputs(definition, options.inputs ?? {}),
+    };
+}
+export async function loadTaskWorkflowDefinition(devstepsDir, itemId, options = {}) {
+    const item = await getItem(devstepsDir, itemId);
+    return loadTaskWorkflowDefinitionFromItem(item, options);
+}
+//# sourceMappingURL=task-workflow-loader.js.map

package/dist/core/task-workflow-loader.js.map

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

package/dist/core/test-workflow-loader.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TEST workflow definition loader.
+ * Validates item-owned TEST declarations and returns direct Acceptance scope only.
+ */
+import type { LoadedWorkflowDefinition } from '../runtime/workflow-contract.js';
+import type { TestProfile } from '../schemas/index.js';
+import { TestWorkflowDefinition } from '../schemas/test-workflow.js';
+import { type GetItemResult } from './get.js';
+export type TestWorkflowLoadOptions = Readonly<{
+    expectedProfile?: TestProfile;
+    requiredDependencyIds?: readonly string[];
+    expectedRevision?: string;
+    expectedDigest?: string;
+}>;
+export type LoadedTestWorkflow = Readonly<{
+    item: GetItemResult;
+    definition: TestWorkflowDefinition;
+    directAcceptanceScope: readonly string[];
+    dependencyIds: readonly string[];
+    definitionRevision: string;
+    definitionDigest: string;
+}> & LoadedWorkflowDefinition;
+export declare class TestWorkflowLoadError extends Error {
+    readonly code: 'NOT_TEST' | 'MISSING_DEFINITION' | 'INVALID_DEFINITION' | 'MISSING_TEST_SCOPE' | 'DEPENDENCY_LINK_MISSING' | 'DERIVED_DOC_LINK_MISSING' | 'PROFILE_MISMATCH';
+    constructor(code: TestWorkflowLoadError['code'], message: string);
+}
+export declare function loadTestWorkflowDefinitionFromItem(item: GetItemResult, options?: TestWorkflowLoadOptions): LoadedTestWorkflow;
+export declare function loadTestWorkflowDefinition(devstepsDir: string, itemId: string, options?: TestWorkflowLoadOptions): Promise<LoadedTestWorkflow>;
+//# sourceMappingURL=test-workflow-loader.d.ts.map

package/dist/core/test-workflow-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-workflow-loader.d.ts","sourceRoot":"","sources":["../../src/core/test-workflow-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,KAAK,aAAa,EAAW,MAAM,UAAU,CAAC;AAIvD,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,eAAe,CAAC,EAAE,WAAW,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,sBAAsB,CAAC;IACnC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC,GACA,wBAAwB,CAAC;AAE3B,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAChB,UAAU,GACV,oBAAoB,GACpB,oBAAoB,GACpB,oBAAoB,GACpB,yBAAyB,GACzB,0BAA0B,GAC1B,kBAAkB,CAAC;IAEvB,YAAmB,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,EAItE;CACF;AA2BD,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAuFpB;AAED,wBAAsB,0BAA0B,CAC9C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,kBAAkB,CAAC,CAG7B"}

package/dist/core/test-workflow-loader.js

@@ -0,0 +1,98 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * TEST workflow definition loader.
+ * Validates item-owned TEST declarations and returns direct Acceptance scope only.
+ */
+import { createHash } from 'node:crypto';
+import { TestWorkflowDefinition } from '../schemas/test-workflow.js';
+import { getItem } from './get.js';
+export class TestWorkflowLoadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TestWorkflowLoadError';
+        this.code = code;
+    }
+}
+function workflowMetadata(metadata) {
+    return metadata.metadata;
+}
+function rawWorkflowDefinition(metadata) {
+    // `process_definition` is the persisted item contract. Keep accepting the
+    // early nested spelling so existing workspaces remain readable.
+    return metadata.process_definition ?? workflowMetadata(metadata).workflow_definition;
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, nested]) => [key, canonicalize(nested)]));
+}
+function definitionDigest(definition) {
+    const canonical = JSON.stringify(canonicalize(definition));
+    return `sha256:${createHash('sha256').update(canonical).digest('hex')}`;
+}
+export function loadTestWorkflowDefinitionFromItem(item, options = {}) {
+    if (item.metadata.type !== 'test') {
+        throw new TestWorkflowLoadError('NOT_TEST', `Item ${item.metadata.id} is not a TEST definition`);
+    }
+    if (item.metadata.linked_items.tests.length === 0) {
+        throw new TestWorkflowLoadError('MISSING_TEST_SCOPE', `TEST ${item.metadata.id} must declare direct tests relationships`);
+    }
+    const rawDefinition = rawWorkflowDefinition(item.metadata);
+    if (rawDefinition === undefined) {
+        throw new TestWorkflowLoadError('MISSING_DEFINITION', `TEST ${item.metadata.id} has no workflow definition`);
+    }
+    const parsed = TestWorkflowDefinition.safeParse(rawDefinition);
+    if (!parsed.success) {
+        throw new TestWorkflowLoadError('INVALID_DEFINITION', `Invalid TEST workflow definition: ${parsed.error.message}`);
+    }
+    const definition = parsed.data;
+    const metadata = workflowMetadata(item.metadata);
+    const revision = metadata.workflow_revision;
+    const currentDefinitionDigest = definitionDigest(definition);
+    const definitionRevision = typeof revision === 'string' && revision.length > 0 ? revision : currentDefinitionDigest;
+    if (options.expectedRevision && options.expectedRevision !== definitionRevision) {
+        throw new TestWorkflowLoadError('INVALID_DEFINITION', 'TEST workflow revision has changed');
+    }
+    if (options.expectedDigest && options.expectedDigest !== currentDefinitionDigest) {
+        throw new TestWorkflowLoadError('INVALID_DEFINITION', 'TEST workflow definition digest has changed');
+    }
+    if (options.expectedProfile && definition.profile !== options.expectedProfile) {
+        throw new TestWorkflowLoadError('PROFILE_MISMATCH', 'TEST workflow profile has changed');
+    }
+    const linkedDependencies = new Set(item.metadata.linked_items['depends-on']);
+    for (const dependencyId of definition.dependencies) {
+        if (!linkedDependencies.has(dependencyId)) {
+            throw new TestWorkflowLoadError('DEPENDENCY_LINK_MISSING', `TEST dependency is not linked: ${dependencyId}`);
+        }
+    }
+    for (const dependencyId of options.requiredDependencyIds ?? []) {
+        if (!linkedDependencies.has(dependencyId)) {
+            throw new TestWorkflowLoadError('DEPENDENCY_LINK_MISSING', `Required TEST dependency is not linked: ${dependencyId}`);
+        }
+    }
+    if (definition.derived_doc &&
+        !item.metadata.linked_items.documents.includes(definition.derived_doc) &&
+        !item.metadata.linked_items['documented-by'].includes(definition.derived_doc)) {
+        throw new TestWorkflowLoadError('DERIVED_DOC_LINK_MISSING', `Derived DOC is not linked: ${definition.derived_doc}`);
+    }
+    return {
+        item,
+        definition,
+        directAcceptanceScope: [...item.metadata.linked_items.tests],
+        dependencyIds: [...definition.dependencies],
+        definitionRevision,
+        definitionDigest: currentDefinitionDigest,
+    };
+}
+export async function loadTestWorkflowDefinition(devstepsDir, itemId, options = {}) {
+    const item = await getItem(devstepsDir, itemId);
+    return loadTestWorkflowDefinitionFromItem(item, options);
+}
+//# sourceMappingURL=test-workflow-loader.js.map

package/dist/core/test-workflow-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-workflow-loader.js","sourceRoot":"","sources":["../../src/core/test-workflow-loader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAsB,OAAO,EAAE,MAAM,UAAU,CAAC;AAqBvD,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9B,IAAI,CAOG;IAEvB,YAAmB,IAAmC,EAAE,OAAe;QACrE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,SAAS,gBAAgB,CAAC,QAAsB;IAC9C,OAAO,QAAQ,CAAC,QAA4B,CAAC;AAC/C,CAAC;AAED,SAAS,qBAAqB,CAAC,QAAsB;IACnD,0EAA0E;IAC1E,gEAAgE;IAChE,OAAO,QAAQ,CAAC,kBAAkB,IAAI,gBAAgB,CAAC,QAAQ,CAAC,CAAC,mBAAmB,CAAC;AACvF,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SAClB,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;SACpD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CACvD,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,UAAkC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;IAC3D,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,kCAAkC,CAChD,IAAmB,EACnB,OAAO,GAA4B,EAAE;IAErC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAClC,MAAM,IAAI,qBAAqB,CAC7B,UAAU,EACV,QAAQ,IAAI,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CACpD,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,qBAAqB,CAC7B,oBAAoB,EACpB,QAAQ,IAAI,CAAC,QAAQ,CAAC,EAAE,0CAA0C,CACnE,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3D,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,qBAAqB,CAC7B,oBAAoB,EACpB,QAAQ,IAAI,CAAC,QAAQ,CAAC,EAAE,6BAA6B,CACtD,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAC/D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,qBAAqB,CAC7B,oBAAoB,EACpB,qCAAqC,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CAC5D,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC;IAC/B,MAAM,QAAQ,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,QAAQ,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IAC5C,MAAM,uBAAuB,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC7D,MAAM,kBAAkB,GACtB,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAC3F,IAAI,OAAO,CAAC,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,KAAK,kBAAkB,EAAE,CAAC;QAChF,MAAM,IAAI,qBAAqB,CAAC,oBAAoB,EAAE,oCAAoC,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,OAAO,CAAC,cAAc,IAAI,OAAO,CAAC,cAAc,KAAK,uBAAuB,EAAE,CAAC;QACjF,MAAM,IAAI,qBAAqB,CAC7B,oBAAoB,EACpB,6CAA6C,CAC9C,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,eAAe,IAAI,UAAU,CAAC,OAAO,KAAK,OAAO,CAAC,eAAe,EAAE,CAAC;QAC9E,MAAM,IAAI,qBAAqB,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7E,KAAK,MAAM,YAAY,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;QACnD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,qBAAqB,CAC7B,yBAAyB,EACzB,kCAAkC,YAAY,EAAE,CACjD,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,MAAM,YAAY,IAAI,OAAO,CAAC,qBAAqB,IAAI,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC1C,MAAM,IAAI,qBAAqB,CAC7B,yBAAyB,EACzB,2CAA2C,YAAY,EAAE,CAC1D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IACE,UAAU,CAAC,WAAW;QACtB,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC;QACtE,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,EAC7E,CAAC;QACD,MAAM,IAAI,qBAAqB,CAC7B,0BAA0B,EAC1B,8BAA8B,UAAU,CAAC,WAAW,EAAE,CACvD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI;QACJ,UAAU;QACV,qBAAqB,EAAE,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC;QAC5D,aAAa,EAAE,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC;QAC3C,kBAAkB;QAClB,gBAAgB,EAAE,uBAAuB;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,WAAmB,EACnB,MAAc,EACd,OAAO,GAA4B,EAAE;IAErC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAChD,OAAO,kCAAkC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC"}