@interf/compiler 0.9.5 → 0.13.0

package/dist/packages/compiler/state-view.js

@@ -1,12 +1,10 @@
-import { basename, relative } from "node:path";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { discoverSourceFiles } from "./discovery.js";
+import { basename } from "node:path";
 import { readInterfConfig, resolveSourceFolderPath } from "../project-model/interf-detect.js";
-import { loadCompiledViewSpec, saveCompiledViewSpec, } from "./state-io.js";
-import { rawSnapshotPath } from "./state-paths.js";
-import { compiledRuntimeRoot, methodPackagePathForCompiled } from "./compiled-paths.js";
+import { loadCompiledSourceSnapshot, loadCompiledViewSpec, saveCompiledViewSpec, } from "./state-io.js";
+import { methodPackagePathForCompiled } from "./compiled-paths.js";
 import { readCompiledSchemaFile } from "./compiled-schema.js";
 import { getActiveCompiledMethod, resolveRequiredCompiledMethodFromConfig } from "../method-package/method-definitions.js";
+import { writeCompiledSourceFiles, writeCompiledSourceSnapshot, } from "./source-files.js";
 export function ensureCompiledViewSpec(dirPath) {
     const existing = loadCompiledViewSpec(dirPath);
     const now = new Date().toISOString();
@@ -22,29 +20,21 @@ export function ensureCompiledViewSpec(dirPath) {
     saveCompiledViewSpec(dirPath, defaults);
     return defaults;
 }
-export function ensureCompiledRawSnapshot(dirPath) {
-    const now = new Date().toISOString();
+export function ensureCompiledSourceFiles(dirPath) {
     const config = readInterfConfig(dirPath);
-    const compiledName = config?.name ?? basename(dirPath);
-    const sourcePath = resolveSourceFolderPath(dirPath, config);
-    const discovery = discoverSourceFiles(sourcePath, dirPath);
-    const sampleFiles = [...discovery.sourceFiles]
-        .sort((a, b) => a.length - b.length || a.localeCompare(b))
-        .slice(0, 10);
-    const sourceRoot = relative(dirPath, sourcePath) || ".";
-    const artifact = {
-        kind: "compiled-raw-snapshot",
-        version: 1,
-        generated_at: now,
-        target_name: compiledName,
-        source_root: sourceRoot,
-        raw_root: sourceRoot,
-        source_total: discovery.totalCount,
-        sample_files: sampleFiles,
-    };
-    mkdirSync(compiledRuntimeRoot(dirPath), { recursive: true });
-    writeFileSync(rawSnapshotPath(dirPath), JSON.stringify(artifact, null, 2) + "\n");
-    return artifact;
+    return writeCompiledSourceFiles(dirPath, resolveSourceFolderPath(dirPath, config));
+}
+export function ensureCompiledSourceSnapshot(dirPath, sourceFiles) {
+    const existing = loadCompiledSourceSnapshot(dirPath);
+    if (existing)
+        return existing;
+    const config = readInterfConfig(dirPath);
+    const resolvedSourceFiles = sourceFiles ?? writeCompiledSourceFiles(dirPath, resolveSourceFolderPath(dirPath, config));
+    return writeCompiledSourceSnapshot({
+        compiledPath: dirPath,
+        sourceFiles: resolvedSourceFiles,
+        runId: null,
+    });
 }
 export function normalizeCompiledViewSpec(existing, defaults) {
     const resolvedDefaults = defaults ?? existing;

package/dist/packages/compiler/state.d.ts

@@ -1,7 +1,7 @@
-export type { RuntimeStatus, CompiledStage, CompiledState, CompiledHealth, ViewSection, ViewCard, CompiledViewSpec, CompiledRawSnapshot, } from "./lib/schema.js";
-export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
-export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export type { RuntimeStatus, CompiledStage, CompiledState, CompiledHealth, ViewSection, ViewCard, CompiledViewSpec, SourceFiles, SourceSnapshot, StageInputs, } from "./lib/schema.js";
+export { statePath, healthPath, viewSpecPath, sourceFilesPath, sourceSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledSourceFiles, loadCompiledSourceSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
 export { refreshCompiledArtifacts, } from "./state-artifacts.js";
 export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
-export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+export { ensureCompiledViewSpec, ensureCompiledSourceFiles, ensureCompiledSourceSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
 export declare function initializeCompiledRuntimeState(dirPath: string): void;

package/dist/packages/compiler/state.js

@@ -1,8 +1,8 @@
-export { statePath, healthPath, viewSpecPath, rawSnapshotPath, } from "./state-paths.js";
-export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledRawSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
+export { statePath, healthPath, viewSpecPath, sourceFilesPath, sourceSnapshotPath, } from "./state-paths.js";
+export { loadState, saveState, loadCompiledHealth, saveCompiledHealth, loadCompiledViewSpec, loadCompiledSourceFiles, loadCompiledSourceSnapshot, saveCompiledViewSpec, initCompiledState, } from "./state-io.js";
 export { refreshCompiledArtifacts, } from "./state-artifacts.js";
 export { computeCompiledHealth, resolveCompiledStatus, resolveCompiledStage, } from "./state-health.js";
-export { ensureCompiledViewSpec, ensureCompiledRawSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
+export { ensureCompiledViewSpec, ensureCompiledSourceFiles, ensureCompiledSourceSnapshot, normalizeCompiledViewSpec, } from "./state-view.js";
 import { saveEmptyCompiledInventory, initCompiledState, saveState } from "./state-io.js";
 import { refreshCompiledArtifacts } from "./state-artifacts.js";
 export function initializeCompiledRuntimeState(dirPath) {

package/dist/packages/contracts/index.d.ts

@@ -1,2 +1,2 @@
 export * as schema from "./lib/schema.js";
-export type { MethodId, PreparationName, ReadinessCheck, ReadinessGate, ReadinessState, ReadinessStatus, ReadinessTargetResult, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, TestCaseExpect, TestTargetType, } from "./lib/schema.js";
+export type { MethodId, PreparationName, ReadinessCheck, ReadinessGate, ReadinessState, ReadinessStatus, ReadinessTargetResult, RuntimeContractType, RuntimeExecutorInfo, RuntimeStage, RuntimeTargetType, Source, SourceFile, SourceFiles, SourceKind, SourceSnapshot, StageInput, StageInputs, TestCaseExpect, TestTargetType, } from "./lib/schema.js";

package/dist/packages/contracts/lib/preparation-paths.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Source of truth for every Interf path on disk.
+ *
+ * Two roots, one helper per named location. Code never string-concatenates
+ * path segments to product locations; it calls the helper here.
+ *
+ * Branded string types catch "passed a Source Folder where I expected a
+ * Preparation Data Dir" at the type-checker level instead of at runtime.
+ *
+ * Two roots:
+ * - **Interf Home** (`~/.interf/`): per-user, cross-preparation state. Holds
+ *   the user-level Method library and the central service registry.
+ * - **Preparation Data Dir**: a directory that IS a preparation's state
+ *   root. Holds `interf.json`, `methods/`, the portable context output, and
+ *   the service-internal `.service/` scratch dir. The user's Source Folders
+ *   are passed as `--source <path>` — they are inputs, not part of the
+ *   preparation data dir.
+ *
+ * No nested `interf/` namespace. The data dir IS the state root, full stop.
+ */
+/** Absolute path to `~/.interf/` (overridable via `INTERF_USER_HOME`). */
+export type InterfHomeRoot = string & {
+    readonly __brand: "InterfHomeRoot";
+};
+/** Absolute path to a directory that IS a preparation's state root. */
+export type PreparationDataDir = string & {
+    readonly __brand: "PreparationDataDir";
+};
+/** Absolute path to a Source Folder — the user's input. Read-only by default. */
+export type SourceFolderPath = string & {
+    readonly __brand: "SourceFolderPath";
+};
+/** Absolute path to a portable-context output directory. */
+export type PortableContextPath = string & {
+    readonly __brand: "PortableContextPath";
+};
+/** Preparation config filename. Kept as `interf.json` for back-compat with existing fixtures. */
+export declare const PREPARATION_CONFIG_FILENAME = "interf.json";
+/** The portable-context state directory name (lives at `<portable-context>/.interf/`). */
+export declare const PORTABLE_CONTEXT_STATE_DIR = ".interf";
+/** Method packages directory name (preparation drafts and user library). */
+export declare const METHODS_DIR = "methods";
+/** Service-internal directory inside a preparation data dir. */
+export declare const SERVICE_DIR = ".service";
+/** Service registry filename inside Interf Home. */
+export declare const SERVICE_REGISTRY_FILENAME = "services.json";
+/** Service jobs subdir. */
+export declare const SERVICE_JOBS_DIR = "jobs";
+/** Service action-proposals subdir. */
+export declare const SERVICE_ACTION_PROPOSALS_DIR = "action-proposals";
+/** Service action-plans subdir. */
+export declare const SERVICE_ACTION_PLANS_DIR = "action-plans";
+/** Tests directory inside a preparation data dir. */
+export declare const PREPARATION_TESTS_DIR = "tests";
+/** Tests-spec subdir. */
+export declare const PREPARATION_TESTS_SPECS_DIR = "specs";
+/** Per-portable-context tests directory. */
+export declare const PORTABLE_CONTEXT_TESTS_DIR = "tests";
+/** Per-portable-context runtime directory. */
+export declare const PORTABLE_CONTEXT_RUNTIME_DIR = "runtime";
+/** Per-portable-context method package directory. */
+export declare const PORTABLE_CONTEXT_METHOD_DIR = "method";
+/** Environment variable that overrides Interf Home for tests. */
+export declare const INTERF_USER_HOME_ENV = "INTERF_USER_HOME";
+export declare function asPreparationDataDir(path: string): PreparationDataDir;
+/** `~/.interf/` (or `INTERF_USER_HOME` override). */
+export declare function interfHomeRoot(): InterfHomeRoot;
+/** `~/.interf/methods/` — user-level Method library root. */
+export declare function userMethodsRoot(): string;
+/** `~/.interf/methods/<id>/` — a specific user-library Method package. */
+export declare function userMethodPackagePath(methodId: string): string;
+/** `~/.interf/services.json` — central service registry. */
+export declare function serviceRegistryPath(): string;
+/** `~/.interf/<basename>/` — per-source-folder default preparation data dir. */
+export declare function defaultPreparationDataDirForSourceBasename(basename: string): PreparationDataDir;
+/** `<prep-data>/interf.json` — preparation config source of truth. */
+export declare function preparationConfigPath(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/methods/` — preparation-draft Method packages root. */
+export declare function preparationMethodsRoot(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/methods/<id>/` — a preparation-draft Method package. */
+export declare function preparationMethodPackagePath(prepDataDir: PreparationDataDir, methodId: string): string;
+/** `<prep-data>/<preparation-name>/` — a preparation's portable context root. */
+export declare function preparationPortableContextPath(prepDataDir: PreparationDataDir, preparationName: string): PortableContextPath;
+/** `<prep-data>/.service/` — service-owned scratch dir for jobs and proposals. */
+export declare function preparationServiceRoot(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/.service/jobs/`. */
+export declare function preparationServiceJobsRoot(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/.service/action-proposals/`. */
+export declare function preparationServiceActionProposalsRoot(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/.service/action-plans/`. */
+export declare function preparationServiceActionPlansRoot(prepDataDir: PreparationDataDir): string;
+/** `<prep-data>/tests/specs/` — saved readiness check specs. */
+export declare function preparationTestsSpecsRoot(prepDataDir: PreparationDataDir): string;
+/** `<portable-context>/.interf/`. */
+export declare function portableContextStateRoot(portableContext: PortableContextPath): string;
+/** `<portable-context>/.interf/interf.json` — runtime contract. */
+export declare function portableContextConfigPath(portableContext: PortableContextPath): string;
+/** `<portable-context>/.interf/method/` — active Method package inside portable context. */
+export declare function portableContextMethodPath(portableContext: PortableContextPath): string;
+/** `<portable-context>/.interf/runtime/`. */
+export declare function portableContextRuntimeRoot(portableContext: PortableContextPath): string;
+/** `<portable-context>/.interf/tests/`. */
+export declare function portableContextTestsRoot(portableContext: PortableContextPath): string;
+/** Test target labels: source-files (raw input) vs compiled (portable context). */
+export type PreparationTestTargetLabel = "source-files" | "compiled";
+/** `<prep-data>/<prep>/.interf/tests/`. */
+export declare function preparationTestsRoot(prepDataDir: PreparationDataDir, preparationName: string): string;
+/** `<prep-data>/<prep>/.interf/tests/<target>/runs/`. */
+export declare function preparationTestRunsRoot(prepDataDir: PreparationDataDir, preparationName: string, target: PreparationTestTargetLabel): string;
+/** `<prep-data>/<prep>/.interf/tests/latest.json`. */
+export declare function preparationLatestReadinessRunPath(prepDataDir: PreparationDataDir, preparationName: string): string;
+/** `<prep-data>/<prep>/.interf/tests/latest.md`. */
+export declare function preparationLatestReadinessSummaryPath(prepDataDir: PreparationDataDir, preparationName: string): string;
+/** Normalize a free-form string into a stable, kebab-cased id (≤80 chars). */
+export declare function normalizePreparationTestRunId(input: string): string;
+/** `<prep-data>/<prep>/.interf/tests/<target>/runs/<timestamp>-<run-id>[-<suffix>].json`. */
+export declare function preparationTestRunPath(prepDataDir: PreparationDataDir, preparationName: string, target: PreparationTestTargetLabel, generatedAt: string, runId: string, runSuffix?: string | null): string;

package/dist/packages/contracts/lib/preparation-paths.js

@@ -0,0 +1,177 @@
+/**
+ * Source of truth for every Interf path on disk.
+ *
+ * Two roots, one helper per named location. Code never string-concatenates
+ * path segments to product locations; it calls the helper here.
+ *
+ * Branded string types catch "passed a Source Folder where I expected a
+ * Preparation Data Dir" at the type-checker level instead of at runtime.
+ *
+ * Two roots:
+ * - **Interf Home** (`~/.interf/`): per-user, cross-preparation state. Holds
+ *   the user-level Method library and the central service registry.
+ * - **Preparation Data Dir**: a directory that IS a preparation's state
+ *   root. Holds `interf.json`, `methods/`, the portable context output, and
+ *   the service-internal `.service/` scratch dir. The user's Source Folders
+ *   are passed as `--source <path>` — they are inputs, not part of the
+ *   preparation data dir.
+ *
+ * No nested `interf/` namespace. The data dir IS the state root, full stop.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ───────────────────────────────────────────────────────────────────────────
+// Constants — every named segment lives here, nowhere else
+// ───────────────────────────────────────────────────────────────────────────
+/** Preparation config filename. Kept as `interf.json` for back-compat with existing fixtures. */
+export const PREPARATION_CONFIG_FILENAME = "interf.json";
+/** The portable-context state directory name (lives at `<portable-context>/.interf/`). */
+export const PORTABLE_CONTEXT_STATE_DIR = ".interf";
+/** Method packages directory name (preparation drafts and user library). */
+export const METHODS_DIR = "methods";
+/** Service-internal directory inside a preparation data dir. */
+export const SERVICE_DIR = ".service";
+/** Service registry filename inside Interf Home. */
+export const SERVICE_REGISTRY_FILENAME = "services.json";
+/** Service jobs subdir. */
+export const SERVICE_JOBS_DIR = "jobs";
+/** Service action-proposals subdir. */
+export const SERVICE_ACTION_PROPOSALS_DIR = "action-proposals";
+/** Service action-plans subdir. */
+export const SERVICE_ACTION_PLANS_DIR = "action-plans";
+/** Tests directory inside a preparation data dir. */
+export const PREPARATION_TESTS_DIR = "tests";
+/** Tests-spec subdir. */
+export const PREPARATION_TESTS_SPECS_DIR = "specs";
+/** Per-portable-context tests directory. */
+export const PORTABLE_CONTEXT_TESTS_DIR = "tests";
+/** Per-portable-context runtime directory. */
+export const PORTABLE_CONTEXT_RUNTIME_DIR = "runtime";
+/** Per-portable-context method package directory. */
+export const PORTABLE_CONTEXT_METHOD_DIR = "method";
+/** Environment variable that overrides Interf Home for tests. */
+export const INTERF_USER_HOME_ENV = "INTERF_USER_HOME";
+// ───────────────────────────────────────────────────────────────────────────
+// Brand constructors — convert untyped strings at boundaries
+// ───────────────────────────────────────────────────────────────────────────
+export function asPreparationDataDir(path) {
+    return path;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Interf Home (~/.interf/) paths
+// ───────────────────────────────────────────────────────────────────────────
+/** `~/.interf/` (or `INTERF_USER_HOME` override). */
+export function interfHomeRoot() {
+    const override = process.env[INTERF_USER_HOME_ENV]?.trim();
+    if (override && override.length > 0)
+        return override;
+    return join(homedir(), ".interf");
+}
+/** `~/.interf/methods/` — user-level Method library root. */
+export function userMethodsRoot() {
+    return join(interfHomeRoot(), METHODS_DIR);
+}
+/** `~/.interf/methods/<id>/` — a specific user-library Method package. */
+export function userMethodPackagePath(methodId) {
+    return join(userMethodsRoot(), methodId);
+}
+/** `~/.interf/services.json` — central service registry. */
+export function serviceRegistryPath() {
+    return join(interfHomeRoot(), SERVICE_REGISTRY_FILENAME);
+}
+/** `~/.interf/<basename>/` — per-source-folder default preparation data dir. */
+export function defaultPreparationDataDirForSourceBasename(basename) {
+    return asPreparationDataDir(join(interfHomeRoot(), basename || "source-folder"));
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Preparation Data Dir paths (the data dir IS the state root)
+// ───────────────────────────────────────────────────────────────────────────
+/** `<prep-data>/interf.json` — preparation config source of truth. */
+export function preparationConfigPath(prepDataDir) {
+    return join(prepDataDir, PREPARATION_CONFIG_FILENAME);
+}
+/** `<prep-data>/methods/` — preparation-draft Method packages root. */
+export function preparationMethodsRoot(prepDataDir) {
+    return join(prepDataDir, METHODS_DIR);
+}
+/** `<prep-data>/methods/<id>/` — a preparation-draft Method package. */
+export function preparationMethodPackagePath(prepDataDir, methodId) {
+    return join(preparationMethodsRoot(prepDataDir), methodId);
+}
+/** `<prep-data>/<preparation-name>/` — a preparation's portable context root. */
+export function preparationPortableContextPath(prepDataDir, preparationName) {
+    return join(prepDataDir, preparationName);
+}
+/** `<prep-data>/.service/` — service-owned scratch dir for jobs and proposals. */
+export function preparationServiceRoot(prepDataDir) {
+    return join(prepDataDir, SERVICE_DIR);
+}
+/** `<prep-data>/.service/jobs/`. */
+export function preparationServiceJobsRoot(prepDataDir) {
+    return join(preparationServiceRoot(prepDataDir), SERVICE_JOBS_DIR);
+}
+/** `<prep-data>/.service/action-proposals/`. */
+export function preparationServiceActionProposalsRoot(prepDataDir) {
+    return join(preparationServiceRoot(prepDataDir), SERVICE_ACTION_PROPOSALS_DIR);
+}
+/** `<prep-data>/.service/action-plans/`. */
+export function preparationServiceActionPlansRoot(prepDataDir) {
+    return join(preparationServiceRoot(prepDataDir), SERVICE_ACTION_PLANS_DIR);
+}
+/** `<prep-data>/tests/specs/` — saved readiness check specs. */
+export function preparationTestsSpecsRoot(prepDataDir) {
+    return join(prepDataDir, PREPARATION_TESTS_DIR, PREPARATION_TESTS_SPECS_DIR);
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Portable Context paths (one per Preparation, lives under prep data dir state)
+// ───────────────────────────────────────────────────────────────────────────
+/** `<portable-context>/.interf/`. */
+export function portableContextStateRoot(portableContext) {
+    return join(portableContext, PORTABLE_CONTEXT_STATE_DIR);
+}
+/** `<portable-context>/.interf/interf.json` — runtime contract. */
+export function portableContextConfigPath(portableContext) {
+    return join(portableContextStateRoot(portableContext), PREPARATION_CONFIG_FILENAME);
+}
+/** `<portable-context>/.interf/method/` — active Method package inside portable context. */
+export function portableContextMethodPath(portableContext) {
+    return join(portableContextStateRoot(portableContext), PORTABLE_CONTEXT_METHOD_DIR);
+}
+/** `<portable-context>/.interf/runtime/`. */
+export function portableContextRuntimeRoot(portableContext) {
+    return join(portableContextStateRoot(portableContext), PORTABLE_CONTEXT_RUNTIME_DIR);
+}
+/** `<portable-context>/.interf/tests/`. */
+export function portableContextTestsRoot(portableContext) {
+    return join(portableContextStateRoot(portableContext), PORTABLE_CONTEXT_TESTS_DIR);
+}
+/** `<prep-data>/<prep>/.interf/tests/`. */
+export function preparationTestsRoot(prepDataDir, preparationName) {
+    return portableContextTestsRoot(preparationPortableContextPath(prepDataDir, preparationName));
+}
+/** `<prep-data>/<prep>/.interf/tests/<target>/runs/`. */
+export function preparationTestRunsRoot(prepDataDir, preparationName, target) {
+    return join(preparationTestsRoot(prepDataDir, preparationName), target, "runs");
+}
+/** `<prep-data>/<prep>/.interf/tests/latest.json`. */
+export function preparationLatestReadinessRunPath(prepDataDir, preparationName) {
+    return join(preparationTestsRoot(prepDataDir, preparationName), "latest.json");
+}
+/** `<prep-data>/<prep>/.interf/tests/latest.md`. */
+export function preparationLatestReadinessSummaryPath(prepDataDir, preparationName) {
+    return join(preparationTestsRoot(prepDataDir, preparationName), "latest.md");
+}
+/** Normalize a free-form string into a stable, kebab-cased id (≤80 chars). */
+export function normalizePreparationTestRunId(input) {
+    return input
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+/** `<prep-data>/<prep>/.interf/tests/<target>/runs/<timestamp>-<run-id>[-<suffix>].json`. */
+export function preparationTestRunPath(prepDataDir, preparationName, target, generatedAt, runId, runSuffix) {
+    const suffix = runSuffix ? `-${normalizePreparationTestRunId(runSuffix)}` : "";
+    return join(preparationTestRunsRoot(prepDataDir, preparationName, target), `${generatedAt.replace(/[:.]/g, "-")}-${runId}${suffix}.json`);
+}

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

@@ -9,9 +9,82 @@ 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";
+}>;
+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,8 +99,8 @@ 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";
@@ -36,8 +109,8 @@ export declare const ReadinessGateSchema: z.ZodEnum<{
 }>;
 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";
@@ -93,8 +166,8 @@ 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";
@@ -142,8 +215,8 @@ 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";
@@ -195,6 +268,13 @@ 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,52 @@ 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"]);
+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([