@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/contracts/lib/schema.d.ts

@@ -9,9 +9,109 @@ export declare const RuntimeTargetTypeSchema: z.ZodEnum<{
     compiled: "compiled";
 }>;
 export declare const TestTargetTypeSchema: z.ZodEnum<{
+    "source-files": "source-files";
     compiled: "compiled";
-    raw: "raw";
 }>;
+export declare const SourceKindSchema: z.ZodEnum<{
+    "local-folder": "local-folder";
+}>;
+/**
+ * Canonical locator-kind enum. A locator identifies where a resource
+ * lives so the API and UI can route the right action without hard-coding
+ * deployment shape:
+ *
+ *   local-path  → the engine has filesystem access; UI opens via OS shell
+ *   remote-url  → a signed URL; UI opens in a browser tab
+ *   api-served  → relative API route; UI fetches via the engine and renders
+ *                 inline (text/markdown drawer, image preview, download)
+ *
+ * All three forms carry a string `value` whose meaning depends on `kind`.
+ */
+export declare const LocatorKindSchema: z.ZodEnum<{
+    "local-path": "local-path";
+    "remote-url": "remote-url";
+    "api-served": "api-served";
+}>;
+export declare const LocatorSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "local-path": "local-path";
+        "remote-url": "remote-url";
+        "api-served": "api-served";
+    }>;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type LocatorKind = z.infer<typeof LocatorKindSchema>;
+export type Locator = z.infer<typeof LocatorSchema>;
+export declare const SourceSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        "local-folder": "local-folder";
+    }>;
+    locator: z.ZodString;
+}, z.core.$strict>;
+export declare const SourceFileSchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    locator: z.ZodString;
+}, z.core.$strict>;
+export declare const SourceFilesSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-source-files">;
+    version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    source: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "local-folder": "local-folder";
+        }>;
+        locator: z.ZodString;
+    }, z.core.$strict>;
+    source_total: z.ZodNumber;
+    files: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        locator: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const SourceSnapshotSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-source-snapshot">;
+    version: z.ZodLiteral<1>;
+    snapshot_id: z.ZodString;
+    generated_at: z.ZodString;
+    run_id: z.ZodNullable<z.ZodString>;
+    source: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            "local-folder": "local-folder";
+        }>;
+        locator: z.ZodString;
+    }, z.core.$strict>;
+    source_total: z.ZodNumber;
+    files: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        locator: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const StageInputSchema: z.ZodObject<{
+    source_file_id: z.ZodString;
+    path: z.ZodString;
+    locator: z.ZodString;
+}, z.core.$strict>;
+export declare const StageInputsSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interf-stage-inputs">;
+    version: z.ZodLiteral<1>;
+    generated_at: z.ZodString;
+    run_id: z.ZodNullable<z.ZodString>;
+    method: z.ZodString;
+    stage: z.ZodString;
+    source_snapshot_id: z.ZodString;
+    input_total: z.ZodNumber;
+    inputs: z.ZodArray<z.ZodObject<{
+        source_file_id: z.ZodString;
+        path: z.ZodString;
+        locator: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const SourceCompiledMaxAttemptsSchema: z.ZodNumber;
 export declare const SourceCompiledMaxLoopsSchema: z.ZodNumber;
 export declare const ReadinessStatusSchema: z.ZodEnum<{
@@ -26,22 +126,18 @@ export declare const ReadinessStatusSchema: z.ZodEnum<{
     failed: "failed";
 }>;
 export declare const ReadinessGateSchema: z.ZodEnum<{
-    "preparation-config": "preparation-config";
     "portable-context": "portable-context";
+    "preparation-config": "preparation-config";
     "compile-run": "compile-run";
     "readiness-checks": "readiness-checks";
-    "source-baseline": "source-baseline";
-    "portable-context-check": "portable-context-check";
     "checks-current": "checks-current";
 }>;
 export declare const ReadinessCheckSchema: z.ZodObject<{
     gate: z.ZodEnum<{
-        "preparation-config": "preparation-config";
         "portable-context": "portable-context";
+        "preparation-config": "preparation-config";
         "compile-run": "compile-run";
         "readiness-checks": "readiness-checks";
-        "source-baseline": "source-baseline";
-        "portable-context-check": "portable-context-check";
         "checks-current": "checks-current";
     }>;
     ok: z.ZodBoolean;
@@ -93,12 +189,10 @@ export declare const ReadinessStateSchema: z.ZodObject<{
     latest_test_run_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     compile: z.ZodNullable<z.ZodObject<{
         gate: z.ZodEnum<{
-            "preparation-config": "preparation-config";
             "portable-context": "portable-context";
+            "preparation-config": "preparation-config";
             "compile-run": "compile-run";
             "readiness-checks": "readiness-checks";
-            "source-baseline": "source-baseline";
-            "portable-context-check": "portable-context-check";
             "checks-current": "checks-current";
         }>;
         ok: z.ZodBoolean;
@@ -142,12 +236,10 @@ export declare const ReadinessStateSchema: z.ZodObject<{
     }, z.core.$strict>;
     checks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         gate: z.ZodEnum<{
-            "preparation-config": "preparation-config";
             "portable-context": "portable-context";
+            "preparation-config": "preparation-config";
             "compile-run": "compile-run";
             "readiness-checks": "readiness-checks";
-            "source-baseline": "source-baseline";
-            "portable-context-check": "portable-context-check";
             "checks-current": "checks-current";
         }>;
         ok: z.ZodBoolean;
@@ -182,6 +274,25 @@ export declare const RuntimeExecutorInfoSchema: z.ZodObject<{
     profile: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     timeout_ms: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
 }, z.core.$strip>;
+/**
+ * Canonical list of stage acceptance-rule keys the engine understands.
+ *
+ * Method packages (`method.json`) declare per-stage `acceptance: {…}` blocks
+ * that use a flat shape with these keys as optional properties. The runtime
+ * walks the same key set when validating a stage outcome. The list is the
+ * single source of truth; method-authoring prompts and runtime exhaustiveness
+ * checks should both read from it instead of duplicating string literals.
+ */
+export declare const ACCEPTANCE_RULE_KEYS: readonly ["artifacts_exist", "stage_truthy", "stage_equals_counts", "stage_at_least", "stage_at_least_counts", "zone_counts_at_least", "zone_counts_at_least_counts", "markdown_frontmatter_valid_zones", "frontmatter_required_keys_in_zones", "markdown_abstract_valid_zones", "wikilinks_valid_in_zones", "artifacts_must_not_contain"];
+export type AcceptanceRuleKey = typeof ACCEPTANCE_RULE_KEYS[number];
+/**
+ * Standard Interf evidence frontmatter keys used by Methods that emit
+ * markdown summaries of source files. Method authors that adopt this
+ * frontmatter convention should use this constant in
+ * `frontmatter_required_keys_in_zones` rather than re-typing the list.
+ */
+export declare const STANDARD_EVIDENCE_FRONTMATTER_KEYS: readonly ["source", "source_kind", "evidence_tier", "truth_mode", "state"];
+export type StandardEvidenceFrontmatterKey = typeof STANDARD_EVIDENCE_FRONTMATTER_KEYS[number];
 export declare const TestCaseExpectSchema: z.ZodObject<{
     must_include: z.ZodOptional<z.ZodArray<z.ZodString>>;
     must_include_one_of: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
@@ -189,12 +300,75 @@ export declare const TestCaseExpectSchema: z.ZodObject<{
     min_words: z.ZodOptional<z.ZodNumber>;
     max_words: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/**
+ * The 5 canonical roles a Method stage can declare. Methods MAY declare
+ * custom role names; the engine treats any unknown role as `general`.
+ */
+export declare const CANONICAL_ROLES: readonly ["extractor", "summarizer", "structurer", "verifier", "general"];
+export type CanonicalRole = typeof CANONICAL_ROLES[number];
+/**
+ * Open-ended role identifier. Methods are free to invent new role names
+ * (e.g. `pdf-extractor`, `chart-builder`); the role-router maps unknown
+ * names to `general` at run time.
+ */
+export declare const RoleSchema: z.ZodString;
+/**
+ * One agent in the registry. `source` distinguishes built-in detected
+ * agents (Claude Code, Codex, Cursor) from user-registered custom CLIs
+ * persisted in `~/.interf/agents.json`. `available` is a runtime-only
+ * field — true if the command's first token resolves on PATH. It is
+ * populated when the merged registry is read and is NOT persisted.
+ */
+export declare const AgentRecordSchema: z.ZodObject<{
+    name: z.ZodString;
+    display_name: z.ZodString;
+    command: z.ZodString;
+    source: z.ZodEnum<{
+        builtin: "builtin";
+        user: "user";
+    }>;
+    available: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type AgentRecord = z.infer<typeof AgentRecordSchema>;
+/**
+ * Map from role name → agent name. Updated by the user via UI / CLI;
+ * persisted in `~/.interf/agents.json`. Roles missing from this map
+ * fall through to the active agent at run time.
+ */
+export declare const RoleMapSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type RoleMap = z.infer<typeof RoleMapSchema>;
+/**
+ * Wire shape of `~/.interf/agents.json`. Built-in agents are detected
+ * dynamically and merged in at read time, so this file persists only
+ * the user-registered subset and the role-map.
+ */
+export declare const AgentsRegistrySchema: z.ZodObject<{
+    agents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        display_name: z.ZodString;
+        command: z.ZodString;
+        source: z.ZodEnum<{
+            builtin: "builtin";
+            user: "user";
+        }>;
+        available: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    role_map: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type AgentsRegistry = z.infer<typeof AgentsRegistrySchema>;
 export type PreparationName = z.infer<typeof PreparationNameSchema>;
 export type MethodId = z.infer<typeof MethodIdSchema>;
 export type RuntimeStage = z.infer<typeof RuntimeStageSchema>;
 export type RuntimeContractType = z.infer<typeof RuntimeContractTypeSchema>;
 export type RuntimeTargetType = z.infer<typeof RuntimeTargetTypeSchema>;
 export type TestTargetType = z.infer<typeof TestTargetTypeSchema>;
+export type SourceKind = z.infer<typeof SourceKindSchema>;
+export type Source = z.infer<typeof SourceSchema>;
+export type SourceFile = z.infer<typeof SourceFileSchema>;
+export type SourceFiles = z.infer<typeof SourceFilesSchema>;
+export type SourceSnapshot = z.infer<typeof SourceSnapshotSchema>;
+export type StageInput = z.infer<typeof StageInputSchema>;
+export type StageInputs = z.infer<typeof StageInputsSchema>;
 export type ReadinessStatus = z.infer<typeof ReadinessStatusSchema>;
 export type ReadinessGate = z.infer<typeof ReadinessGateSchema>;
 export type ReadinessCheck = z.infer<typeof ReadinessCheckSchema>;

package/dist/packages/contracts/lib/schema.js

@@ -10,7 +10,69 @@ export const MethodIdSchema = z.string().regex(InterfIdPattern);
 export const RuntimeStageSchema = z.string().regex(InterfIdPattern);
 export const RuntimeContractTypeSchema = z.string().regex(InterfIdPattern);
 export const RuntimeTargetTypeSchema = z.enum(["compiled"]);
-export const TestTargetTypeSchema = z.enum(["compiled", "raw"]);
+export const TestTargetTypeSchema = z.enum(["compiled", "source-files"]);
+export const SourceKindSchema = z.enum(["local-folder"]);
+/**
+ * Canonical locator-kind enum. A locator identifies where a resource
+ * lives so the API and UI can route the right action without hard-coding
+ * deployment shape:
+ *
+ *   local-path  → the engine has filesystem access; UI opens via OS shell
+ *   remote-url  → a signed URL; UI opens in a browser tab
+ *   api-served  → relative API route; UI fetches via the engine and renders
+ *                 inline (text/markdown drawer, image preview, download)
+ *
+ * All three forms carry a string `value` whose meaning depends on `kind`.
+ */
+export const LocatorKindSchema = z.enum(["local-path", "remote-url", "api-served"]);
+export const LocatorSchema = z.object({
+    kind: LocatorKindSchema,
+    value: z.string().min(1),
+}).strict();
+export const SourceSchema = z.object({
+    id: z.string().regex(InterfIdPattern),
+    kind: SourceKindSchema,
+    locator: z.string().min(1),
+}).strict();
+export const SourceFileSchema = z.object({
+    id: z.string().min(1),
+    path: z.string().min(1),
+    locator: z.string().min(1),
+}).strict();
+export const SourceFilesSchema = z.object({
+    kind: z.literal("interf-source-files"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    source: SourceSchema,
+    source_total: z.number().int().min(0),
+    files: z.array(SourceFileSchema),
+}).strict();
+export const SourceSnapshotSchema = z.object({
+    kind: z.literal("interf-source-snapshot"),
+    version: z.literal(1),
+    snapshot_id: z.string().min(1),
+    generated_at: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    source: SourceSchema,
+    source_total: z.number().int().min(0),
+    files: z.array(SourceFileSchema),
+}).strict();
+export const StageInputSchema = z.object({
+    source_file_id: z.string().min(1),
+    path: z.string().min(1),
+    locator: z.string().min(1),
+}).strict();
+export const StageInputsSchema = z.object({
+    kind: z.literal("interf-stage-inputs"),
+    version: z.literal(1),
+    generated_at: z.string().min(1),
+    run_id: z.string().min(1).nullable(),
+    method: MethodIdSchema,
+    stage: RuntimeStageSchema,
+    source_snapshot_id: z.string().min(1),
+    input_total: z.number().int().min(0),
+    inputs: z.array(StageInputSchema),
+}).strict();
 export const SourceCompiledMaxAttemptsSchema = z.number().int().min(1).max(5);
 export const SourceCompiledMaxLoopsSchema = z.number().int().min(1).max(3);
 export const ReadinessStatusSchema = z.enum([
@@ -29,8 +91,6 @@ export const ReadinessGateSchema = z.enum([
     "portable-context",
     "compile-run",
     "readiness-checks",
-    "source-baseline",
-    "portable-context-check",
     "checks-current",
 ]);
 export const ReadinessCheckSchema = z.object({
@@ -81,6 +141,42 @@ export const RuntimeExecutorInfoSchema = z.object({
     profile: z.string().nullable().optional(),
     timeout_ms: z.number().nullable().optional(),
 });
+/**
+ * Canonical list of stage acceptance-rule keys the engine understands.
+ *
+ * Method packages (`method.json`) declare per-stage `acceptance: {…}` blocks
+ * that use a flat shape with these keys as optional properties. The runtime
+ * walks the same key set when validating a stage outcome. The list is the
+ * single source of truth; method-authoring prompts and runtime exhaustiveness
+ * checks should both read from it instead of duplicating string literals.
+ */
+export const ACCEPTANCE_RULE_KEYS = [
+    "artifacts_exist",
+    "stage_truthy",
+    "stage_equals_counts",
+    "stage_at_least",
+    "stage_at_least_counts",
+    "zone_counts_at_least",
+    "zone_counts_at_least_counts",
+    "markdown_frontmatter_valid_zones",
+    "frontmatter_required_keys_in_zones",
+    "markdown_abstract_valid_zones",
+    "wikilinks_valid_in_zones",
+    "artifacts_must_not_contain",
+];
+/**
+ * Standard Interf evidence frontmatter keys used by Methods that emit
+ * markdown summaries of source files. Method authors that adopt this
+ * frontmatter convention should use this constant in
+ * `frontmatter_required_keys_in_zones` rather than re-typing the list.
+ */
+export const STANDARD_EVIDENCE_FRONTMATTER_KEYS = [
+    "source",
+    "source_kind",
+    "evidence_tier",
+    "truth_mode",
+    "state",
+];
 export const TestCaseExpectSchema = z.object({
     must_include: z.array(z.string().min(1)).optional(),
     must_include_one_of: z.array(z.array(z.string().min(1)).min(1)).optional(),
@@ -98,3 +194,52 @@ export const TestCaseExpectSchema = z.object({
     value.max_words !== undefined, {
     message: "Test expectations must include at least one check",
 });
+// ───────────────────────────────────────────────────────────────────────────
+// 0.15 — connected agents + roles
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * The 5 canonical roles a Method stage can declare. Methods MAY declare
+ * custom role names; the engine treats any unknown role as `general`.
+ */
+export const CANONICAL_ROLES = [
+    "extractor",
+    "summarizer",
+    "structurer",
+    "verifier",
+    "general",
+];
+/**
+ * Open-ended role identifier. Methods are free to invent new role names
+ * (e.g. `pdf-extractor`, `chart-builder`); the role-router maps unknown
+ * names to `general` at run time.
+ */
+export const RoleSchema = z.string().min(1);
+/**
+ * One agent in the registry. `source` distinguishes built-in detected
+ * agents (Claude Code, Codex, Cursor) from user-registered custom CLIs
+ * persisted in `~/.interf/agents.json`. `available` is a runtime-only
+ * field — true if the command's first token resolves on PATH. It is
+ * populated when the merged registry is read and is NOT persisted.
+ */
+export const AgentRecordSchema = z.object({
+    name: z.string().min(1),
+    display_name: z.string().min(1),
+    command: z.string().min(1),
+    source: z.enum(["builtin", "user"]),
+    available: z.boolean().optional(),
+}).strict();
+/**
+ * Map from role name → agent name. Updated by the user via UI / CLI;
+ * persisted in `~/.interf/agents.json`. Roles missing from this map
+ * fall through to the active agent at run time.
+ */
+export const RoleMapSchema = z.record(RoleSchema, z.string().min(1));
+/**
+ * Wire shape of `~/.interf/agents.json`. Built-in agents are detected
+ * dynamically and merged in at read time, so this file persists only
+ * the user-registered subset and the role-map.
+ */
+export const AgentsRegistrySchema = z.object({
+    agents: z.array(AgentRecordSchema).default([]),
+    role_map: RoleMapSchema.default({}),
+}).strict();

package/dist/packages/contracts/utils/filesystem.d.ts

@@ -0,0 +1,9 @@
+export declare function countFilesRecursive(dirPath: string): number;
+export declare function listFilesRecursive(dirPath: string, predicate?: (filePath: string) => boolean): string[];
+/**
+ * Async variant of {@link listFilesRecursive}. Uses promise-based
+ * `readdir` + `realpath` so directory walks on large source folders do
+ * not block the event loop. Symlink cycles are skipped via a
+ * canonical-path visited set, matching the sync variant.
+ */
+export declare function listFilesRecursiveAsync(dirPath: string, predicate?: (filePath: string) => boolean): Promise<string[]>;

package/dist/packages/contracts/utils/filesystem.js

@@ -0,0 +1,142 @@
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { readdir, realpath } from "node:fs/promises";
+import { join } from "node:path";
+export function countFilesRecursive(dirPath) {
+    if (!existsSync(dirPath))
+        return 0;
+    let total = 0;
+    walkFilesRecursive(dirPath, () => {
+        total += 1;
+    });
+    return total;
+}
+export function listFilesRecursive(dirPath, predicate) {
+    const files = [];
+    if (!existsSync(dirPath))
+        return files;
+    walkFilesRecursive(dirPath, (filePath) => {
+        if (!predicate || predicate(filePath)) {
+            files.push(filePath);
+        }
+    });
+    return files;
+}
+/**
+ * Async variant of {@link listFilesRecursive}. Uses promise-based
+ * `readdir` + `realpath` so directory walks on large source folders do
+ * not block the event loop. Symlink cycles are skipped via a
+ * canonical-path visited set, matching the sync variant.
+ */
+export async function listFilesRecursiveAsync(dirPath, predicate) {
+    const files = [];
+    if (!existsSync(dirPath))
+        return files;
+    await walkFilesRecursiveAsync(dirPath, (filePath) => {
+        if (!predicate || predicate(filePath)) {
+            files.push(filePath);
+        }
+    });
+    return files;
+}
+function walkFilesRecursive(dirPath, onFile, visitedDirs = new Set()) {
+    if (!existsSync(dirPath))
+        return;
+    walkFilesRecursiveInternal(dirPath, onFile, visitedDirs);
+}
+function walkFilesRecursiveInternal(dirPath, onFile, visitedDirs) {
+    let resolvedDir;
+    try {
+        resolvedDir = realpathSync(dirPath);
+    }
+    catch {
+        return;
+    }
+    if (visitedDirs.has(resolvedDir))
+        return;
+    visitedDirs.add(resolvedDir);
+    // `withFileTypes` returns Dirent entries that already encode whether
+    // each name is a file/dir/symlink; using them avoids the per-entry
+    // statSync that previously dominated the walk on large source folders.
+    let entries;
+    try {
+        entries = readdirSync(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+        if (entry.isSymbolicLink()) {
+            // Symlinks need realpath to detect cycles; if the target reads as
+            // a directory we recurse, otherwise treat the link as a file.
+            try {
+                const target = realpathSync(fullPath);
+                if (visitedDirs.has(target))
+                    continue;
+                try {
+                    readdirSync(target);
+                    walkFilesRecursiveInternal(fullPath, onFile, visitedDirs);
+                }
+                catch {
+                    onFile(fullPath);
+                }
+            }
+            catch {
+                // Broken or inaccessible link.
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            walkFilesRecursiveInternal(fullPath, onFile, visitedDirs);
+        }
+        else if (entry.isFile()) {
+            onFile(fullPath);
+        }
+    }
+}
+async function walkFilesRecursiveAsync(dirPath, onFile, visitedDirs = new Set()) {
+    let resolvedDir;
+    try {
+        resolvedDir = await realpath(dirPath);
+    }
+    catch {
+        return;
+    }
+    if (visitedDirs.has(resolvedDir))
+        return;
+    visitedDirs.add(resolvedDir);
+    let entries;
+    try {
+        entries = await readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry.name);
+        if (entry.isSymbolicLink()) {
+            try {
+                const target = await realpath(fullPath);
+                if (visitedDirs.has(target))
+                    continue;
+                try {
+                    await readdir(target);
+                    await walkFilesRecursiveAsync(fullPath, onFile, visitedDirs);
+                }
+                catch {
+                    onFile(fullPath);
+                }
+            }
+            catch {
+                // Broken or inaccessible link.
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            await walkFilesRecursiveAsync(fullPath, onFile, visitedDirs);
+        }
+        else if (entry.isFile()) {
+            onFile(fullPath);
+        }
+    }
+}

package/dist/packages/{local-service → engine}/action-definitions.d.ts

@@ -42,25 +42,25 @@ export declare const INTERF_SERVICE_ACTIONS: {
         readonly id: "create-preparation";
         readonly serviceAction: "preparation-setup";
         readonly title: "Create Preparation";
-        readonly description: "Save a Source Folder and agent job as a Preparation.";
+        readonly description: "Save a Source Folder + Method binding so future runs can be invoked by name.";
     };
-    readonly runPreparation: {
-        readonly id: "prepare-run";
+    readonly compileRun: {
+        readonly id: "compile-run";
         readonly serviceAction: "compile";
-        readonly title: "Run Preparation";
-        readonly description: "Build portable context for a saved Preparation.";
+        readonly title: "Compile Method";
+        readonly description: "Run the chosen Method against this Source Folder and write portable context.";
     };
     readonly selectMethod: {
         readonly id: "select-method";
         readonly serviceAction: "preparation-setup";
         readonly title: "Select Method";
-        readonly description: "Save the Method a Preparation should use for future prepare runs.";
+        readonly description: "Choose which Method this saved binding should use for future runs.";
     };
     readonly createMethod: {
         readonly id: "create-method";
         readonly serviceAction: "method-authoring";
-        readonly title: "Create Method";
-        readonly description: "Draft a reusable local Method for an agent-work pattern.";
+        readonly title: "Draft Method";
+        readonly description: "Draft a reusable local Method that captures a repeatable agent-work pattern.";
     };
     readonly methodChange: {
         readonly id: "method-change";
@@ -95,8 +95,8 @@ export declare const INTERF_SERVICE_ACTIONS: {
     readonly improvePreparation: {
         readonly id: "improve-preparation";
         readonly serviceAction: "method-improvement";
-        readonly title: "Improve Preparation";
-        readonly description: "Use readiness evidence to improve the Method for this Preparation.";
+        readonly title: "Improve Method";
+        readonly description: "Use readiness evidence to refine the Method this saved binding uses.";
     };
 };
 export type InterfServiceActionKey = keyof typeof INTERF_SERVICE_ACTIONS;
@@ -146,10 +146,10 @@ export type MethodActionChoice = {
 export type CreatePreparationActionContext = {
     existingNames: string[];
     methods: MethodActionChoice[];
-    sourcePath: string;
+    prepDataDir: string;
     suggestedName: string;
 };
-export type PrepareRunActionContext = {
+export type CompileRunActionContext = {
     about: string;
     methodId: string;
     name: string;
@@ -232,8 +232,8 @@ export declare function methodImprovementActionValues(options: {
     preparationName: string;
 }): MethodAuthoringActionValues;
 export declare function buildCreatePreparationActionDefinition(context: CreatePreparationActionContext): ActionInputDefinition;
-export declare function buildPrepareRunActionDefinition(context: PrepareRunActionContext): ActionInputDefinition;
-export declare function buildPrepareRunActionDraft(context: PrepareRunActionContext): ActionInputDraft;
+export declare function buildCompileRunActionDefinition(context: CompileRunActionContext): ActionInputDefinition;
+export declare function buildCompileRunActionDraft(context: CompileRunActionContext): ActionInputDraft;
 export declare function buildSelectMethodActionDefinition(context: SelectMethodActionContext): ActionInputDefinition;
 export declare function buildCreateMethodActionDefinition(context: CreateMethodActionContext): ActionInputDefinition;
 export declare function buildMethodChangeActionDefinition(context: MethodChangeActionContext): ActionInputDefinition;