@gate-forge/core 0.1.0

package/dist/schemas/runner-adapter.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Runner-adapter contract (plan 2026-09-13 phase 2 item 6): the small
+ * interface every test-runner adapter implements so inventory, instance
+ * resolution, and execution have one shape.
+ *
+ * This module is TYPES ONLY (no runtime code): adapters live in their
+ * packs (the Playwright and bounded pytest adapters in
+ * `@gate-forge/pack-playwright/discovery`), while the contract belongs to
+ * the engine so CLI/pipeline code can depend on the shape without
+ * depending on a pack.
+ *
+ * Honesty rules baked into the contract:
+ * - `capabilities` is declared, never implied: an adapter that cannot
+ *   execute says so (`not-wired-until-phase-4`); callers fail closed
+ *   instead of guessing.
+ * - `execute` returns a structured outcome envelope — runner exit codes
+ *   alone are never a gate result (plan §5.1 row "Execution result").
+ */
+import type { TestCatalogEntry } from './test-catalog.js';
+/** Availability of one adapter capability. */
+export type RunnerCapability = 'available' | 'not-wired-until-phase-4' | 'unsupported';
+/** The declared capabilities of one adapter. */
+export interface RunnerCapabilities {
+    /** Enumerate the runner's tests into catalog entries. */
+    inventory: RunnerCapability;
+    /** Map a logical key to concrete runtime instances (project/param). */
+    resolveInstances: RunnerCapability;
+    /**
+     * Execute a selection under trusted supervision and return the
+     * structured outcome envelope. `not-wired-until-phase-4` until the
+     * trusted supervisor owns the run (plan phase 4).
+     */
+    execute: RunnerCapability;
+}
+/** One concrete runtime instance a logical test resolves to. */
+export interface RunnerTestInstance {
+    /** The logical key the instance belongs to (§5.2 identity rules). */
+    logicalKey: string;
+    /** Runner project, e.g. `chromium` (framework IDs identify instances). */
+    project: string | null;
+    /**
+     * The framework's own instance id (playwright spec id, pytest node
+     * id). Framework IDs identify runtime instances; the logical key
+     * stays the stable mapping identity.
+     */
+    frameworkId: string;
+}
+/** The tests an execute call is asked to run (exact, never a wildcard). */
+export interface RunnerSelection {
+    /** Exact logical keys selected for the run. */
+    logicalKeys: readonly string[];
+}
+/** Environment identity an execute call runs under (plan §3.3 rule 4). */
+export interface RunnerExecutionEnv {
+    /** Absolute run-state directory (excluded from tracked inputs). */
+    stateDir: string;
+    /** Run id the execution binds to. */
+    runId: string;
+    /** Extra env the supervisor wires for the run (already sanitized). */
+    vars: Readonly<Record<string, string>>;
+}
+/** Per-instance outcome of a supervised execution (plan §5.1 row 4). */
+export interface RunnerInstanceOutcome {
+    logicalKey: string;
+    /** The concrete instance that ran. */
+    project: string | null;
+    frameworkId: string;
+    /** passed | failed | skipped | fixme — first attempt, no retries. */
+    status: 'passed' | 'failed' | 'skipped' | 'fixme' | 'not-run';
+    /** Attempt number (1 = first attempt; required retries stay zero). */
+    attempt: number;
+    /**
+     * True when the instance is an expected failure (e.g. Playwright
+     * `test.fail()`): an expected-failure exemption never proves behavior
+     * (plan §3.3 rule 3) and supervision blocks on it.
+     */
+    expectedFailure?: boolean;
+}
+/**
+ * The structured outcome envelope `execute` resolves with. Runner
+ * reporter data is INPUT here, never signature authority (plan §5.1).
+ * Phase 4 extends the envelope with the supervision surfaces trusted
+ * runner supervision needs (fixture/teardown outcome, shard
+ * completeness, retry detection, engine versions) — all optional so
+ * earlier adapters remain valid.
+ */
+export interface RunnerExecutionEnvelope {
+    /** Framework process exit code (supplementary, never decisive). */
+    processExit: number | null;
+    /** Whether the COMPLETE selected set ran (no missing cases/shards). */
+    complete: boolean;
+    /** One outcome per planned instance. */
+    outcomes: readonly RunnerInstanceOutcome[];
+    /** Single-cause detail when the run is incomplete. */
+    incompleteDetail?: string;
+    /**
+     * Setup/teardown/runner-body outcome observed during the run
+     * (plan §3.3 rule 5: the complete run — fixtures and teardown
+     * included — must end successfully). Absent = unknown (fail closed
+     * downstream).
+     */
+    fixtureOutcome?: 'passed' | 'failed' | 'unknown';
+    /**
+     * Shard completeness when the runner reports sharding; null/absent
+     * means the runner reported none (single-shard runs).
+     */
+    shards?: {
+        complete: boolean;
+        detail: string;
+    } | null;
+    /** True when retry-assisted execution was detected (retries must be 0). */
+    retriesDetected?: boolean;
+    /** Detail describing the retry detection. */
+    retriesDetail?: string;
+    /** Runtime engine versions captured during the run (honest subset). */
+    engines?: Record<string, string>;
+    /** Browser versions when the runner reports them (may be empty). */
+    browsers?: Record<string, string>;
+}
+/**
+ * The adapter contract (plan phase 2 item 6): inventory, instance
+ * resolution, execution, outcomes. Adapters must be deterministic and
+ * fail closed: enumeration never returns an empty inventory for a scan
+ * that failed, and undeclared capabilities are rejected by callers.
+ *
+ * @typeParam TEntry - the catalog entry row shape the adapter emits.
+ */
+export interface TestRunnerAdapter<TEntry extends object = TestCatalogEntry> {
+    /** Runner name the adapter serves, e.g. `playwright`. */
+    readonly runner: string;
+    /** Declared capabilities — callers must honor, never assume. */
+    readonly capabilities: RunnerCapabilities;
+    /**
+     * Enumerates the runner's configured tests.
+     *
+     * Args:
+     *   cwd: absolute repo root the runner configuration lives under.
+     *
+     * Returns:
+     *   Promise<TEntry[]>: catalog entry rows (unresolved rows included —
+     *   never an empty list for a failed scan).
+     */
+    inventory(cwd: string): Promise<readonly TEntry[]>;
+    /**
+     * Resolves one logical key to its concrete runtime instances.
+     *
+     * Args:
+     *   logicalKey: the stable logical identity (§5.2).
+     *   cwd: absolute repo root.
+     *
+     * Returns:
+     *   Promise<RunnerTestInstance[]>: matching instances (empty when the
+     *   key has no current instance — a visible stale mapping, §5.2).
+     */
+    resolveInstances(logicalKey: string, cwd: string): Promise<readonly RunnerTestInstance[]>;
+    /**
+     * Executes a selection under trusted supervision. Adapters whose
+     * `capabilities.execute` is not `available` reject here (fail closed).
+     *
+     * Args:
+     *   selection: exact logical keys to run.
+     *   env: run-state dir + run identity the execution binds to.
+     *
+     * Returns:
+     *   Promise<RunnerExecutionEnvelope>: structured outcome envelope.
+     */
+    execute(selection: RunnerSelection, env: RunnerExecutionEnv): Promise<RunnerExecutionEnvelope>;
+}
+//# sourceMappingURL=runner-adapter.d.ts.map

package/dist/schemas/runner-adapter.d.ts.map

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

package/dist/schemas/runner-adapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner-adapter.js.map

package/dist/schemas/runner-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-adapter.js","sourceRoot":"","sources":["../../src/schemas/runner-adapter.ts"],"names":[],"mappings":""}

package/dist/schemas/test-catalog.d.ts

@@ -0,0 +1,472 @@
+/**
+ * Test-catalog schemas (plan 2026-09-13 §5.1 row 1 + §5.2): the derived
+ * inventory of a repository's existing tests.
+ *
+ * Identity rules (§5.2, hard):
+ * - The `logicalKey` is the stable manual-mapping identity: an explicit
+ *   slug when a mapping declares one, otherwise deterministically derived
+ *   from runner + project + repo-relative file + full title path
+ *   ({@link deriveLogicalKey}).
+ * - Line numbers are DIAGNOSTICS, never identity: adding a comment keeps
+ *   the logical key stable while `sourceDigest` changes.
+ * - Duplicate logical keys are a typed parse error listing BOTH sources —
+ *   never "bind the first match".
+ *
+ * Discovery is data, not a gate result: `unresolved` entries and
+ * `parseErrors` are first-class catalog rows so a failed scan can never
+ * be misread as "no tests".
+ */
+import { z } from 'zod';
+/** Runner names with an implemented adapter (plan phase 2 item 6). */
+export declare const SUPPORTED_TEST_RUNNERS: readonly ["playwright", "pytest"];
+/**
+ * A runner name. `playwright` and `pytest` are the adapters implemented
+ * so far; any other string is legal data (an adapter must exist before
+ * its entries drive gates — plan phase 2 item 6).
+ */
+export declare const TestRunnerSchema: z.ZodString;
+/** Inferred test-runner type. */
+export type TestRunner = z.infer<typeof TestRunnerSchema>;
+/**
+ * What a test IS (plan §3.2). `unknown` is a kept, visible outcome.
+ *
+ * `server-e2e` (server-witnessed persistence channel) declares an
+ * existing test whose persistence evidence is witnessed SERVER-side:
+ * the engine's own adapter probe observes the app database directly,
+ * because the obligated state (e.g. a transactional outbox) can never
+ * honestly appear in a UI. Browser-kind tests never grade through it —
+ * the witness stamps the channel only for obligations registered
+ * `server-e2e` on the verifier-key supervisor surface, and the verdict
+ * engine admits `channel: 'server'` records only with that stamp.
+ */
+export declare const TestKindSchema: z.ZodEnum<{
+    unknown: "unknown";
+    "browser-e2e": "browser-e2e";
+    "server-e2e": "server-e2e";
+    "api-e2e": "api-e2e";
+    unit: "unit";
+    integration: "integration";
+    component: "component";
+}>;
+/** Inferred test-kind type. */
+export type TestKind = z.infer<typeof TestKindSchema>;
+/** Catalog row discovery status (plan §5.1 row 1). */
+export declare const DiscoveryStatusSchema: z.ZodEnum<{
+    unresolved: "unresolved";
+    discovered: "discovered";
+    "parse-error": "parse-error";
+}>;
+/** Inferred discovery-status type. */
+export type DiscoveryStatus = z.infer<typeof DiscoveryStatusSchema>;
+/** Reconciliation outcome against the runner's native enumeration. */
+export declare const ReconciliationStatusSchema: z.ZodEnum<{
+    matched: "matched";
+    "static-only": "static-only";
+    "list-only": "list-only";
+    unavailable: "unavailable";
+}>;
+/** Inferred reconciliation-status type. */
+export type ReconciliationStatus = z.infer<typeof ReconciliationStatusSchema>;
+/** One inference rule that fired, with the code location that fed it. */
+export declare const RuleEvidenceSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    evidence: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred rule-evidence type. */
+export type RuleEvidence = z.infer<typeof RuleEvidenceSchema>;
+/**
+ * A strong kind signal: a rule that proposes a {@link TestKind} with its
+ * code evidence. Conflicting proposals resolve to `unknown` — never to
+ * whichever rule ran last (plan phase 2 item 5: no opaque confidence).
+ */
+export declare const KindSignalSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    evidence: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+    kind: z.ZodEnum<{
+        unknown: "unknown";
+        "browser-e2e": "browser-e2e";
+        "server-e2e": "server-e2e";
+        "api-e2e": "api-e2e";
+        unit: "unit";
+        integration: "integration";
+        component: "component";
+    }>;
+}, z.core.$strict>;
+/** Inferred kind-signal type. */
+export type KindSignal = z.infer<typeof KindSignalSchema>;
+/**
+ * A weak signal (title/folder hints). Weak signals are recorded for the
+ * agent but must NEVER decide a kind by themselves (plan §3.2).
+ */
+export declare const WeakSignalSchema: z.ZodObject<{
+    ruleId: z.ZodString;
+    evidence: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred weak-signal type. */
+export type WeakSignal = z.infer<typeof WeakSignalSchema>;
+/**
+ * A behavior-category hint (plan §3.2): extensible dotted labels such as
+ * `persistence.create`. Hints only — a label never creates or satisfies
+ * a contract.
+ */
+export declare const CategorySignalSchema: z.ZodObject<{
+    label: z.ZodString;
+    ruleId: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred category-signal type. */
+export type CategorySignal = z.infer<typeof CategorySignalSchema>;
+/**
+ * Suppression/mock signals: skip, only, fixme, and known mock patterns.
+ * These qualify (and can disqualify) later proof; discovery only records
+ * them with locations (plan §3.2/§3.3).
+ */
+export declare const SuppressionSignalKindSchema: z.ZodEnum<{
+    skip: "skip";
+    only: "only";
+    fixme: "fixme";
+    mock: "mock";
+}>;
+/** Inferred suppression-signal-kind type. */
+export type SuppressionSignalKind = z.infer<typeof SuppressionSignalKindSchema>;
+/** One recorded suppression/mock signal with its location. */
+export declare const SuppressionSignalSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        skip: "skip";
+        only: "only";
+        fixme: "fixme";
+        mock: "mock";
+    }>;
+    detail: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred suppression-signal type. */
+export type SuppressionSignal = z.infer<typeof SuppressionSignalSchema>;
+/**
+ * One catalog row (plan §5.1 row 1): what test exists, plus the signals
+ * discovery gathered. Rows are NEVER dropped — an unresolvable call is
+ * a row with `discoveryStatus: 'unresolved'`, not an omission.
+ */
+export declare const TestCatalogEntrySchema: z.ZodObject<{
+    logicalKey: z.ZodString;
+    runner: z.ZodString;
+    project: z.ZodNullable<z.ZodString>;
+    file: z.ZodString;
+    titlePath: z.ZodArray<z.ZodString>;
+    title: z.ZodString;
+    sourceLocation: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+    parameterIdentity: z.ZodNullable<z.ZodString>;
+    sourceDigest: z.ZodString;
+    resolutionOrigin: z.ZodOptional<z.ZodEnum<{
+        static: "static";
+        "native-list": "native-list";
+    }>>;
+    discoveryStatus: z.ZodEnum<{
+        unresolved: "unresolved";
+        discovered: "discovered";
+        "parse-error": "parse-error";
+    }>;
+    reconciliation: z.ZodEnum<{
+        matched: "matched";
+        "static-only": "static-only";
+        "list-only": "list-only";
+        unavailable: "unavailable";
+    }>;
+    inferredKind: z.ZodEnum<{
+        unknown: "unknown";
+        "browser-e2e": "browser-e2e";
+        "server-e2e": "server-e2e";
+        "api-e2e": "api-e2e";
+        unit: "unit";
+        integration: "integration";
+        component: "component";
+    }>;
+    kindSignals: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        evidence: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+        kind: z.ZodEnum<{
+            unknown: "unknown";
+            "browser-e2e": "browser-e2e";
+            "server-e2e": "server-e2e";
+            "api-e2e": "api-e2e";
+            unit: "unit";
+            integration: "integration";
+            component: "component";
+        }>;
+    }, z.core.$strict>>;
+    weakSignals: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        evidence: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    rulesFired: z.ZodArray<z.ZodObject<{
+        ruleId: z.ZodString;
+        evidence: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    categorySignals: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        ruleId: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    suppressionSignals: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            skip: "skip";
+            only: "only";
+            fixme: "fixme";
+            mock: "mock";
+        }>;
+        detail: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    unresolvedReason: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Inferred test-catalog-entry type. */
+export type TestCatalogEntry = z.infer<typeof TestCatalogEntrySchema>;
+/** One parser failure with its source location (never swallowed). */
+export declare const CatalogParseErrorSchema: z.ZodObject<{
+    file: z.ZodString;
+    message: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** Inferred catalog-parse-error type. */
+export type CatalogParseError = z.infer<typeof CatalogParseErrorSchema>;
+/** One runner-level summary line (playwright reconciliation, pytest suites). */
+export declare const RunnerSummarySchema: z.ZodObject<{
+    runner: z.ZodString;
+    name: z.ZodString;
+    status: z.ZodEnum<{
+        discovered: "discovered";
+        unavailable: "unavailable";
+        registered: "registered";
+    }>;
+    detail: z.ZodString;
+}, z.core.$strict>;
+/** Inferred runner-summary type. */
+export type RunnerSummary = z.infer<typeof RunnerSummarySchema>;
+/**
+ * The derived test catalog (plan §5.1). Every case is a row in
+ * `entries`; `unresolved` and `parseErrors` are the typed roll-ups of
+ * the rows needing attention. `inventoryComplete` captures scan
+ * completeness SEPARATELY from classification uncertainty: `unknown`
+ * kinds do not make an inventory incomplete, a failed scan does.
+ */
+export declare const TestCatalogSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    entries: z.ZodArray<z.ZodObject<{
+        logicalKey: z.ZodString;
+        runner: z.ZodString;
+        project: z.ZodNullable<z.ZodString>;
+        file: z.ZodString;
+        titlePath: z.ZodArray<z.ZodString>;
+        title: z.ZodString;
+        sourceLocation: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+        parameterIdentity: z.ZodNullable<z.ZodString>;
+        sourceDigest: z.ZodString;
+        resolutionOrigin: z.ZodOptional<z.ZodEnum<{
+            static: "static";
+            "native-list": "native-list";
+        }>>;
+        discoveryStatus: z.ZodEnum<{
+            unresolved: "unresolved";
+            discovered: "discovered";
+            "parse-error": "parse-error";
+        }>;
+        reconciliation: z.ZodEnum<{
+            matched: "matched";
+            "static-only": "static-only";
+            "list-only": "list-only";
+            unavailable: "unavailable";
+        }>;
+        inferredKind: z.ZodEnum<{
+            unknown: "unknown";
+            "browser-e2e": "browser-e2e";
+            "server-e2e": "server-e2e";
+            "api-e2e": "api-e2e";
+            unit: "unit";
+            integration: "integration";
+            component: "component";
+        }>;
+        kindSignals: z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            evidence: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+            kind: z.ZodEnum<{
+                unknown: "unknown";
+                "browser-e2e": "browser-e2e";
+                "server-e2e": "server-e2e";
+                "api-e2e": "api-e2e";
+                unit: "unit";
+                integration: "integration";
+                component: "component";
+            }>;
+        }, z.core.$strict>>;
+        weakSignals: z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            evidence: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        rulesFired: z.ZodArray<z.ZodObject<{
+            ruleId: z.ZodString;
+            evidence: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        categorySignals: z.ZodArray<z.ZodObject<{
+            label: z.ZodString;
+            ruleId: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        suppressionSignals: z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                skip: "skip";
+                only: "only";
+                fixme: "fixme";
+                mock: "mock";
+            }>;
+            detail: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>;
+        unresolvedReason: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            detail: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    unresolved: z.ZodArray<z.ZodObject<{
+        logicalKey: z.ZodString;
+        code: z.ZodString;
+        detail: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    parseErrors: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        message: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    inventoryComplete: z.ZodBoolean;
+    runnerSummaries: z.ZodArray<z.ZodObject<{
+        runner: z.ZodString;
+        name: z.ZodString;
+        status: z.ZodEnum<{
+            discovered: "discovered";
+            unavailable: "unavailable";
+            registered: "registered";
+        }>;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Inferred test-catalog type. */
+export type TestCatalog = z.infer<typeof TestCatalogSchema>;
+/** One catalog roll-up row (inferred, for builders). */
+export type CatalogUnresolved = z.infer<(typeof TestCatalogSchema)['shape']['unresolved']['element']>;
+/** Inputs of the deterministic logical-key derivation (§5.2). */
+export interface LogicalKeyInput {
+    /** Runner name, e.g. `playwright`. */
+    runner: string;
+    /** Runner project, or `null` when none is bound yet. */
+    project: string | null;
+    /** Repo-root-relative posix file path. */
+    file: string;
+    /** Full title path (describe stack + title). */
+    titlePath: readonly string[];
+}
+/**
+ * Derives the deterministic logical key for a test (§5.2): runner,
+ * project (`-` when unbound), repo-relative file, then the full title
+ * path joined with `>`. Pure string shaping — stable across line moves
+ * and comment edits (line numbers are never identity input).
+ *
+ * Args:
+ *   input: runner, project, file, and title path.
+ *
+ * Returns:
+ *   string: e.g. `playwright:chromium:e2e/accounts.spec.ts:Accounts>creates an account`.
+ */
+export declare function deriveLogicalKey(input: LogicalKeyInput): string;
+//# sourceMappingURL=test-catalog.d.ts.map

package/dist/schemas/test-catalog.d.ts.map

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