@glubean/scanner 0.2.2 → 0.2.4

package/dist/contract-extraction.d.ts

@@ -23,6 +23,18 @@ export type CaseSeverity = "critical" | "warning" | "info";
 export type CaseRequires = "headless" | "browser" | "out-of-band";
 /** Case default run policy. */
 export type CaseDefaultRun = "always" | "opt-in";
+/** Projectable description of opaque verify() semantics. */
+export type VerifyRule = string | {
+    id?: string;
+    description: string;
+    severity?: CaseSeverity;
+    extensions?: Record<string, unknown>;
+};
+/** Runnability gates mirrored from the SDK's CaseRunnability. */
+export interface NormalizedRunnability {
+    requireAttachment?: boolean;
+    requireSession?: boolean;
+}
 /** A named example entry for OpenAPI docs. */
 export interface NormalizedExample {
     value: unknown;
@@ -56,6 +68,35 @@ export interface NormalizedCaseMeta {
     schemas?: unknown;
     /** Adapter-defined free-form meta (opaque). */
     meta?: unknown;
+    /**
+     * World-state precondition — attachment-model §0.9. Adapter threads
+     * through from `BaseCaseSpec.given`. Not a contract semantic input,
+     * but projected because it changes what `expect` means.
+     */
+    given?: string;
+    /** True when executable semantics also live in an adapter verify() callback. */
+    hasVerify?: boolean;
+    /** Projectable companion rules for opaque verify() callbacks. */
+    verifyRules?: VerifyRule[];
+    /**
+     * Runnability metadata — attachment-model §7.2. `requireAttachment`
+     * blocks raw execution (case MUST run via a bootstrap overlay). Lives
+     * as a first-class field, not in `extensions`, per proposal.
+     */
+    runnability?: NormalizedRunnability;
+    /**
+     * True iff the case declared `needs`. Authoritative trigger for
+     * `rawBypass` in the attachment inventory. Decoupled from `needsSchema`:
+     * a case can have needs whose schema isn't projectable.
+     */
+    hasNeeds?: boolean;
+    /**
+     * v10 attachment-model — JSON-safe `needs` schema. May be undefined
+     * even when `hasNeeds` is true (e.g. opaque custom validator). Use
+     * `hasNeeds` for inventory/rawBypass decisions; this field is a
+     * decoration for consumers that want the schema shape when available.
+     */
+    needsSchema?: unknown;
 }
 /**
  * Protocol-agnostic contract metadata. Mirrors `ExtractedContractProjection`.
@@ -123,15 +164,98 @@ export interface NormalizedFlowMeta {
     setupDynamic?: true;
     steps: NormalizedFlowStep[];
 }
-/** Result of extracting contracts/flows from one or more files. */
+/**
+ * Default execution mode for a contract case — runs the case directly with
+ * an explicit input (or void when no needs declared). Lives in
+ * `attachments[]` until a bootstrap overlay replaces it.
+ */
+export interface NormalizedRawAttachment {
+    kind: "raw";
+    /** Contract case test id (`${contractId}.${caseKey}`). */
+    testId: string;
+    contractId: string;
+    caseKey: string;
+    /** Export name of the contract this case belongs to. */
+    exportName: string;
+    /** Runnability gates declared by the case. */
+    runnability?: NormalizedRunnability;
+}
+/**
+ * Bootstrap overlay attachment — `contract.bootstrap(ref, spec)` registers
+ * a setup-and-cleanup that wraps the case. Replaces the raw entry for the
+ * target testId. Body of `run`/`spec` is opaque per attachment-model §4.2.
+ *
+ * `paramsSchema` is undefined in v0 — structured-form param schema
+ * extraction needs the bootstrap registry, deferred to Spike 3.
+ *
+ * `rawBypass` exposes the explicit-input execution path (§5.1) so the
+ * inventory is the single authoritative source for both modes per testId.
+ */
+export interface NormalizedBootstrapOverlayAttachment {
+    kind: "bootstrap-overlay";
+    testId: string;
+    /** The overlay's own export name (NOT the contract's). */
+    exportName: string;
+    targetRef: {
+        contractId: string;
+        caseKey: string;
+    };
+    bootstrap: {
+        /** v0: undefined; populated when structured-form `params` schema lands. */
+        paramsSchema?: unknown;
+    };
+    /** Present iff the target case has `needs` (explicit-input bypass available). */
+    rawBypass?: {
+        available: true;
+        /** JSON-safe form of the case's `needs` schema (may be undefined when SDK can't convert). */
+        needsSchema: unknown;
+    };
+}
+/**
+ * Flow attachment — orchestrates a sequence of contract calls under a
+ * single test id. Distinct from raw / overlay (no underlying case).
+ */
+export interface NormalizedFlowAttachment {
+    kind: "flow";
+    /** Flow test id (`flowId`). */
+    testId: string;
+    exportName: string;
+    flow: NormalizedFlowMeta;
+}
+/** Discriminated attachment entry. One per testId in the inventory. */
+export type NormalizedAttachmentMeta = NormalizedRawAttachment | NormalizedBootstrapOverlayAttachment | NormalizedFlowAttachment;
+/** Result of extracting contracts/attachments from one or more files. */
 export interface ExtractionResult {
     contracts: NormalizedContractMeta[];
-    flows?: NormalizedFlowMeta[];
+    /**
+     * Attachment inventory per attachment-model §7.3. Always present
+     * (may be empty). Replaces the previous `flows?: NormalizedFlowMeta[]`
+     * top-level field — flows now appear here as `kind: "flow"` entries.
+     */
+    attachments: NormalizedAttachmentMeta[];
     errors: Array<{
         file: string;
         error: string;
     }>;
 }
+/**
+ * Check if a value looks like a BootstrapAttachment (v10 attachment model).
+ *
+ * BootstrapAttachment is the runtime marker returned by `contract.bootstrap()`.
+ * Carries `__glubean_type: "bootstrap-attachment"` and `testId`
+ * (= `${contractId}.${caseKey}`). Scanner identifies attachments via this
+ * marker without importing @glubean/sdk types.
+ *
+ * v0 attachment projection only surfaces metadata (kind, testId,
+ * contractId, caseKey). Bootstrap params schema (structured-form `params`)
+ * is not yet exposed on the export object — extracting it requires reading
+ * the bootstrap registry, deferred to Spike 3 when the runner input
+ * channel ships.
+ */
+export declare function isBootstrapAttachment(val: unknown): val is {
+    __glubean_type: "bootstrap-attachment";
+    testId: string;
+};
 /**
  * Check if a value looks like a ProtocolContract.
  * ProtocolContract extends Array<Test> and has `_projection` with protocol + target.
@@ -204,14 +328,87 @@ export declare function protocolContractToNormalized(value: {
     _extracted: any;
 }, exportName: string): NormalizedContractMeta;
 /**
- * Extract contracts + flows from a single file by dynamic import.
+ * Bootstrap overlay marker collected during file walk — pre-synthesis raw
+ * material. Not yet a final attachment entry; `synthesizeAttachments`
+ * decides whether to keep it (replaces a raw entry) or report duplicate.
+ */
+export interface BootstrapOverlayMarker {
+    exportName: string;
+    testId: string;
+    contractId: string;
+    caseKey: string;
+}
+/**
+ * Convert a BootstrapAttachment runtime export to a marker. Splits
+ * `testId` into contractId + caseKey at the LAST dot (contractId can have
+ * dots, e.g. `v2.orders.create.success`). Returns null for malformed shapes
+ * (no dot, leading dot, trailing dot) — caller skips them.
+ */
+export declare function bootstrapAttachmentToNormalized(attachment: {
+    testId: string;
+}, exportName: string): BootstrapOverlayMarker | null;
+/**
+ * Synthesize the §7.3 attachment inventory from raw materials.
+ *
+ * Algorithm (per attachment-model §7.3):
+ *  1. Seed: each contract case → `kind: "raw"` entry (testId = `${id}.${key}`).
+ *  2. Apply overlays: each marker → REPLACE the raw entry with the same
+ *     testId by a `kind: "bootstrap-overlay"` entry. Carry `rawBypass`
+ *     when the target case has `needsSchema` (explicit-input bypass
+ *     available per §5.1).
+ *  3. Duplicate detection: two markers with the same testId → push a
+ *     load-time error. Keep the first; subsequent overlays ignored.
+ *  4. Append flows as `kind: "flow"` entries.
+ *
+ * Overlays whose testId doesn't match any contract case stand alone —
+ * we still emit them as `bootstrap-overlay` (no `rawBypass`, no targetRef
+ * verification). This keeps cross-file overlay registration discoverable
+ * even when the contract module hasn't been scanned yet.
+ */
+export declare function synthesizeAttachments(contracts: NormalizedContractMeta[], flows: NormalizedFlowMeta[], markers: BootstrapOverlayMarker[]): {
+    attachments: NormalizedAttachmentMeta[];
+    errors: ExtractionResult["errors"];
+};
+/**
+ * Extract contracts + attachments from a single file by dynamic import.
  * One file's import failure does not block others.
+ *
+ * Per-file synthesis: only this file's contracts/flows/markers are seen.
+ * Cross-file overlay replacement (overlay in fileA targets case in fileB)
+ * only resolves at project level via `extractContractsFromProject`.
  */
 export declare function extractContractFromFile(filePath: string): Promise<ExtractionResult>;
 /**
- * Extract contracts + flows from all recognized files in a project.
+ * Extract contracts + attachments from all recognized files in a project.
+ *
+ * Project-level synthesis: collects raw materials (contracts, flows,
+ * overlay markers) across all `.contract.` / `.flow.` / `.bootstrap.`
+ * files, then runs `synthesizeAttachments` once. This is what enables
+ * cross-file overlay replacement (overlay in `signup.bootstrap.ts`
+ * replacing the raw entry for a case in `signup.contract.ts`) and
+ * project-wide duplicate-overlay detection per §7.3.
  */
 export declare function extractContractsFromProject(dir: string): Promise<ExtractionResult>;
+/**
+ * Eagerly import every `*.bootstrap.{ts,js,mjs}` file under `dir` so
+ * `contract.bootstrap()` calls execute during module evaluation and
+ * register their overlays in the SDK's bootstrap registry.
+ *
+ * Idempotent: subsequent calls re-import the same module URLs; Node's
+ * ESM module cache short-circuits unless the file's mtime changed (the
+ * same cache-busting strategy `collectRawMaterials` uses).
+ *
+ * Errors: per-file failures are returned; the caller decides whether
+ * to abort or continue. We return errors instead of throwing because a
+ * single broken bootstrap file shouldn't kill an otherwise-working run.
+ */
+export declare function loadProjectOverlays(dir: string): Promise<{
+    loaded: string[];
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}>;
 /** @deprecated Removed in v0.2 — HTTP now goes through isProtocolContract. */
 export declare function isHttpContract(_val: unknown): never;
 //# sourceMappingURL=contract-extraction.d.ts.map

package/dist/contract-extraction.d.ts.map

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

package/dist/contract-extraction.js

@@ -21,6 +21,26 @@ import { readdirSync, statSync } from "node:fs";
 // =============================================================================
 // Duck typing
 // =============================================================================
+/**
+ * Check if a value looks like a BootstrapAttachment (v10 attachment model).
+ *
+ * BootstrapAttachment is the runtime marker returned by `contract.bootstrap()`.
+ * Carries `__glubean_type: "bootstrap-attachment"` and `testId`
+ * (= `${contractId}.${caseKey}`). Scanner identifies attachments via this
+ * marker without importing @glubean/sdk types.
+ *
+ * v0 attachment projection only surfaces metadata (kind, testId,
+ * contractId, caseKey). Bootstrap params schema (structured-form `params`)
+ * is not yet exposed on the export object — extracting it requires reading
+ * the bootstrap registry, deferred to Spike 3 when the runner input
+ * channel ships.
+ */
+export function isBootstrapAttachment(val) {
+    return (typeof val === "object" &&
+        val !== null &&
+        val.__glubean_type === "bootstrap-attachment" &&
+        typeof val.testId === "string");
+}
 /**
  * Check if a value looks like a ProtocolContract.
  * ProtocolContract extends Array<Test> and has `_projection` with protocol + target.
@@ -90,6 +110,12 @@ export function protocolContractToNormalized(value, exportName) {
             extensions: c.extensions,
             schemas: c.schemas,
             meta: c.meta,
+            given: c.given,
+            hasVerify: c.hasVerify,
+            verifyRules: c.verifyRules,
+            runnability: c.runnability,
+            hasNeeds: c.hasNeeds,
+            needsSchema: c.needsSchema,
         })),
     };
 }
@@ -180,20 +206,142 @@ function autoBuildFlowBuilder(val) {
     }
     return val;
 }
-// =============================================================================
-// File-level extraction
-// =============================================================================
-// Per-path mtime cache used by extractContractFromFile() to decide when
-// to bust Node's ESM module cache on re-import. See the comment inside
-// that function for the full reasoning.
+/**
+ * Convert a BootstrapAttachment runtime export to a marker. Splits
+ * `testId` into contractId + caseKey at the LAST dot (contractId can have
+ * dots, e.g. `v2.orders.create.success`). Returns null for malformed shapes
+ * (no dot, leading dot, trailing dot) — caller skips them.
+ */
+export function bootstrapAttachmentToNormalized(attachment, exportName) {
+    const dotIndex = attachment.testId.lastIndexOf(".");
+    if (dotIndex <= 0 || dotIndex === attachment.testId.length - 1) {
+        return null;
+    }
+    const contractId = attachment.testId.slice(0, dotIndex);
+    const caseKey = attachment.testId.slice(dotIndex + 1);
+    return {
+        exportName,
+        testId: attachment.testId,
+        contractId,
+        caseKey,
+    };
+}
+function normalizeRunnability(runnability) {
+    if (!runnability)
+        return undefined;
+    const normalized = {};
+    if (runnability.requireAttachment !== undefined) {
+        normalized.requireAttachment = runnability.requireAttachment;
+    }
+    if (runnability.requireSession !== undefined) {
+        normalized.requireSession = runnability.requireSession;
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+/**
+ * Synthesize the §7.3 attachment inventory from raw materials.
+ *
+ * Algorithm (per attachment-model §7.3):
+ *  1. Seed: each contract case → `kind: "raw"` entry (testId = `${id}.${key}`).
+ *  2. Apply overlays: each marker → REPLACE the raw entry with the same
+ *     testId by a `kind: "bootstrap-overlay"` entry. Carry `rawBypass`
+ *     when the target case has `needsSchema` (explicit-input bypass
+ *     available per §5.1).
+ *  3. Duplicate detection: two markers with the same testId → push a
+ *     load-time error. Keep the first; subsequent overlays ignored.
+ *  4. Append flows as `kind: "flow"` entries.
+ *
+ * Overlays whose testId doesn't match any contract case stand alone —
+ * we still emit them as `bootstrap-overlay` (no `rawBypass`, no targetRef
+ * verification). This keeps cross-file overlay registration discoverable
+ * even when the contract module hasn't been scanned yet.
+ */
+export function synthesizeAttachments(contracts, flows, markers) {
+    const errors = [];
+    // Index cases by testId for O(1) lookup during overlay application.
+    const caseByTestId = new Map();
+    for (const contract of contracts) {
+        for (const c of contract.cases) {
+            caseByTestId.set(`${contract.id}.${c.key}`, { contract, case: c });
+        }
+    }
+    // Step 1: seed raw entries. Reads `runnability` directly from the case
+    // projection (post-Phase-2f-fix: the adapter now threads it as a
+    // first-class field, no longer hidden under `extensions`).
+    const byTestId = new Map();
+    for (const [testId, { contract, case: c }] of caseByTestId) {
+        const runnability = normalizeRunnability(c.runnability);
+        byTestId.set(testId, {
+            kind: "raw",
+            testId,
+            contractId: contract.id,
+            caseKey: c.key,
+            exportName: contract.exportName,
+            ...(runnability ? { runnability } : {}),
+        });
+    }
+    // Step 2 + 3: apply overlays, detect duplicates.
+    const seenOverlayIds = new Set();
+    for (const marker of markers) {
+        if (seenOverlayIds.has(marker.testId)) {
+            errors.push({
+                file: marker.exportName,
+                error: `Duplicate bootstrap overlay for testId "${marker.testId}" (export "${marker.exportName}"). Per attachment-model §7.3 testId uniqueness is enforced.`,
+            });
+            continue;
+        }
+        seenOverlayIds.add(marker.testId);
+        // rawBypass is available iff the target case declared `needs`
+        // (hasNeeds === true). This is decoupled from needsSchema projection:
+        // a case with a custom safeParse-only validator still satisfies
+        // "explicit input can run the raw case" even when the JSON Schema
+        // projection is null. If the schema projected, we decorate the
+        // bypass slot with it; otherwise bypass is still advertised.
+        const target = caseByTestId.get(marker.testId);
+        const overlay = {
+            kind: "bootstrap-overlay",
+            testId: marker.testId,
+            exportName: marker.exportName,
+            targetRef: { contractId: marker.contractId, caseKey: marker.caseKey },
+            bootstrap: {},
+            ...(target?.case.hasNeeds
+                ? {
+                    rawBypass: {
+                        available: true,
+                        needsSchema: target.case.needsSchema,
+                    },
+                }
+                : {}),
+        };
+        byTestId.set(marker.testId, overlay);
+    }
+    // Step 4: append flows.
+    const attachments = Array.from(byTestId.values());
+    for (const flow of flows) {
+        attachments.push({
+            kind: "flow",
+            testId: flow.id,
+            exportName: flow.exportName,
+            flow,
+        });
+    }
+    return { attachments, errors };
+}
+// Per-path mtime cache used by collectRawMaterials() to decide when to
+// bust Node's ESM module cache on re-import. See the comment inside that
+// function for the full reasoning.
 const _importMtimeCache = new Map();
 /**
- * Extract contracts + flows from a single file by dynamic import.
- * One file's import failure does not block others.
+ * Internal: dynamically import a file and collect raw materials
+ * (contracts / flows / overlay markers / errors) without synthesis.
+ * Both `extractContractFromFile` and `extractContractsFromProject` use
+ * this — the former synthesizes per-file, the latter synthesizes
+ * project-wide so cross-file overlay replacement and dedup work.
  */
-export async function extractContractFromFile(filePath) {
+async function collectRawMaterials(filePath) {
     const contracts = [];
     const flows = [];
+    const markers = [];
     const errors = [];
     const absolutePath = resolve(filePath);
     try {
@@ -242,19 +390,47 @@ export async function extractContractFromFile(filePath) {
             else if (isProtocolContract(value)) {
                 contracts.push(protocolContractToNormalized(value, exportName));
             }
+            else if (isBootstrapAttachment(value)) {
+                const marker = bootstrapAttachmentToNormalized(value, exportName);
+                if (marker)
+                    markers.push(marker);
+            }
         }
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         errors.push({ file: absolutePath, error: message });
     }
-    return { contracts, flows: flows.length > 0 ? flows : undefined, errors };
+    return { contracts, flows, markers, errors };
+}
+/**
+ * Extract contracts + attachments from a single file by dynamic import.
+ * One file's import failure does not block others.
+ *
+ * Per-file synthesis: only this file's contracts/flows/markers are seen.
+ * Cross-file overlay replacement (overlay in fileA targets case in fileB)
+ * only resolves at project level via `extractContractsFromProject`.
+ */
+export async function extractContractFromFile(filePath) {
+    const raw = await collectRawMaterials(filePath);
+    const synth = synthesizeAttachments(raw.contracts, raw.flows, raw.markers);
+    return {
+        contracts: raw.contracts,
+        attachments: synth.attachments,
+        errors: [...raw.errors, ...synth.errors],
+    };
 }
 // =============================================================================
 // Project-level extraction
 // =============================================================================
 /**
- * Find all .contract.{ts,js,mjs} and .flow.{ts,js,mjs} files in a directory tree.
+ * Find all .contract.{ts,js,mjs}, .flow.{ts,js,mjs}, and
+ * .bootstrap.{ts,js,mjs} files in a directory tree.
+ *
+ * v10 attachment model §7.4 mandates eager loading of `.bootstrap.` files
+ * so overlay registrations fire during module evaluation. Without this,
+ * filtered runs (CLI / MCP) could miss overlay registrations and silently
+ * fall through to the no-overlay path.
  */
 function findContractAndFlowFiles(dir) {
     const files = [];
@@ -267,7 +443,9 @@ function findContractAndFlowFiles(dir) {
                 walk(full);
             else {
                 const base = basename(entry);
-                if (base.includes(".contract.") || base.includes(".flow.")) {
+                if (base.includes(".contract.") ||
+                    base.includes(".flow.") ||
+                    base.includes(".bootstrap.")) {
                     files.push(full);
                 }
             }
@@ -277,29 +455,95 @@ function findContractAndFlowFiles(dir) {
     return files;
 }
 /**
- * Extract contracts + flows from all recognized files in a project.
+ * Extract contracts + attachments from all recognized files in a project.
+ *
+ * Project-level synthesis: collects raw materials (contracts, flows,
+ * overlay markers) across all `.contract.` / `.flow.` / `.bootstrap.`
+ * files, then runs `synthesizeAttachments` once. This is what enables
+ * cross-file overlay replacement (overlay in `signup.bootstrap.ts`
+ * replacing the raw entry for a case in `signup.contract.ts`) and
+ * project-wide duplicate-overlay detection per §7.3.
  */
 export async function extractContractsFromProject(dir) {
     const files = findContractAndFlowFiles(dir);
-    if (files.length === 0)
-        return { contracts: [], errors: [] };
+    if (files.length === 0) {
+        return { contracts: [], attachments: [], errors: [] };
+    }
     const allContracts = [];
     const allFlows = [];
+    const allMarkers = [];
     const allErrors = [];
     for (const filePath of files) {
-        const { contracts, flows, errors } = await extractContractFromFile(filePath);
-        allContracts.push(...contracts);
-        if (flows)
-            allFlows.push(...flows);
-        allErrors.push(...errors);
+        const raw = await collectRawMaterials(filePath);
+        allContracts.push(...raw.contracts);
+        allFlows.push(...raw.flows);
+        allMarkers.push(...raw.markers);
+        allErrors.push(...raw.errors);
     }
+    const synth = synthesizeAttachments(allContracts, allFlows, allMarkers);
     return {
         contracts: allContracts,
-        flows: allFlows.length > 0 ? allFlows : undefined,
-        errors: allErrors,
+        attachments: synth.attachments,
+        errors: [...allErrors, ...synth.errors],
     };
 }
 // =============================================================================
+// Eager overlay loading — attachment-model §7.4
+//
+// "Runner MUST eagerly load all *.contract.ts and *.bootstrap.ts files in
+// the contracts root before resolving attachments. Overlay registration is
+// a semantic input to runnable inventory; making it depend on import path
+// leads to nondeterministic runs."
+//
+// CLI/MCP/ProjectRunner call this before any test runs so a filtered run
+// (e.g. `glubean run path/to/single.contract.ts`) still picks up sibling
+// `*.bootstrap.ts` overlay registrations.
+// =============================================================================
+/**
+ * Eagerly import every `*.bootstrap.{ts,js,mjs}` file under `dir` so
+ * `contract.bootstrap()` calls execute during module evaluation and
+ * register their overlays in the SDK's bootstrap registry.
+ *
+ * Idempotent: subsequent calls re-import the same module URLs; Node's
+ * ESM module cache short-circuits unless the file's mtime changed (the
+ * same cache-busting strategy `collectRawMaterials` uses).
+ *
+ * Errors: per-file failures are returned; the caller decides whether
+ * to abort or continue. We return errors instead of throwing because a
+ * single broken bootstrap file shouldn't kill an otherwise-working run.
+ */
+export async function loadProjectOverlays(dir) {
+    const allFiles = findContractAndFlowFiles(dir);
+    const bootstrapFiles = allFiles.filter((f) => basename(f).includes(".bootstrap."));
+    const loaded = [];
+    const errors = [];
+    for (const filePath of bootstrapFiles) {
+        const absolutePath = resolve(filePath);
+        try {
+            let mtimeKey = 0;
+            try {
+                mtimeKey = statSync(absolutePath).mtimeMs;
+            }
+            catch {
+                // fall through with mtimeKey=0
+            }
+            const baseUrl = pathToFileURL(absolutePath).href;
+            const lastSeen = _importMtimeCache.get(absolutePath);
+            const importUrl = lastSeen === undefined || lastSeen === mtimeKey
+                ? baseUrl
+                : `${baseUrl}?t=${mtimeKey}`;
+            _importMtimeCache.set(absolutePath, mtimeKey);
+            await import(importUrl);
+            loaded.push(absolutePath);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push({ file: absolutePath, error: message });
+        }
+    }
+    return { loaded, errors };
+}
+// =============================================================================
 // Backward-compat: isHttpContract — removed permanently in v0.2.
 // =============================================================================
 /** @deprecated Removed in v0.2 — HTTP now goes through isProtocolContract. */