@interf/compiler 0.22.0 → 0.33.0

package/dist/packages/engine/runtime.d.ts

@@ -1,371 +0,0 @@
-import { type ArtifactRef, type BuildRun, type InterfRunEvent, type ProofRecord } from "./execution/lib/schema.js";
-import { type RunEventSink } from "./execution/events.js";
-import { type Readiness } from "../contracts/lib/schema.js";
-import type { SourcePreparationConfig } from "../project/lib/schema.js";
-import { type BillingEventSink } from "./build/billing-events.js";
-import type { IdempotencyStore, RunLeaseStore, TokenValidator } from "./cloud-seams.js";
-import { type ActionProposalCreateRequest, type ActionProposalPlan, type ActionProposalResource, type BuildRunCreateRequest, type BuildRunResource, type BuildPlanResource, type LocalServiceHealth, type LocalJobEvent, type LocalJobEventAppendRequest, type LocalExecutorStatus, type LocalJobRunResource, type LocalRunHandlerResult, type VerifiableContextResource, type PreparationResource, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type RunObservabilityResource, type SourceFileResource, type VerifyRunCreateRequest, type VerifyRunResource, type BuildPlanAuthoringCreateRequest, type BuildPlanAuthoringResult, type BuildPlanChangeResult, type PreparationChangeResult, type PreparationSetupResult, type ResetResult } from "./lib/schema.js";
-export interface LocalServiceBuildRunContext {
-    runId: string;
-    sourcePath: string;
-    verifiableContextPath: string;
-    preparationConfig: SourcePreparationConfig;
-    events: RunEventSink;
-}
-export interface LocalServiceVerifyRunContext {
-    runId: string;
-    sourcePath: string;
-    verifiableContextPath: string;
-    preparationConfig: SourcePreparationConfig;
-}
-export interface LocalServiceJobRunContext {
-    runId: string;
-    sourcePath: string;
-    emit(event: LocalJobEventAppendRequest): void;
-}
-export interface LocalServiceActionPlanningContext {
-    sourcePath: string;
-    preparations: SourcePreparationConfig[];
-    preparationHealth: Array<{
-        name: string;
-        readiness_checks: number;
-        verifiable_context_ready: boolean;
-        can_check_readiness: boolean;
-        recommended_next_actions: string[];
-    }>;
-    sourceFolders: Array<{
-        value: string;
-        label: string;
-        hint: string;
-    }>;
-    recentProposals: ActionProposalResource[];
-}
-export interface LocalServiceRunHandlers {
-    planActionProposal(request: ActionProposalCreateRequest, context: LocalServiceActionPlanningContext): Promise<ActionProposalPlan>;
-    createBuildRun(request: BuildRunCreateRequest, context: LocalServiceBuildRunContext): Promise<LocalRunHandlerResult>;
-    createVerifyRun(request: VerifyRunCreateRequest, context: LocalServiceVerifyRunContext): Promise<LocalRunHandlerResult>;
-    createReadinessCheckDraft(request: ReadinessCheckDraftCreateRequest, context: LocalServiceJobRunContext): Promise<ReadinessCheckDraftResult>;
-    createBuildPlanAuthoringRun(request: BuildPlanAuthoringCreateRequest, context: LocalServiceJobRunContext): Promise<BuildPlanAuthoringResult>;
-}
-export interface LocalServiceRuntimeOptions {
-    rootPath: string;
-    host: string;
-    port: number;
-    packageVersion?: string;
-    startedAt?: string;
-    handlers?: Partial<LocalServiceRunHandlers>;
-    /**
-     * Per-instance bearer token. The server requires it on mutating
-     * requests. Optional only so test code that does not exercise auth can
-     * skip generating one; production startup always provides a token.
-     */
-    authToken?: string;
-    /**
-     * 0.17 — optional injection point for the per-Artifact billing event
-     * sink. Local default writes a JSONL file alongside the run record;
-     * cloud variants will inject a Metronome HTTP sender once the
-     * Stripe/Metronome integration ships in 0.18+.
-     */
-    billingEventSink?: BillingEventSink;
-    /**
-     * 0.17 — cloud-variant interface seams. Local default: in-process
-     * Maps on the runtime (current behavior). Cloud variants pass shared
-     * implementations so multi-replica engines coordinate. See
-     * `cloud-seams.ts` for the contract.
-     */
-    idempotencyStore?: IdempotencyStore;
-    runLeaseStore?: RunLeaseStore;
-}
-/**
- * Per-preparation context tracked by the runtime. Multiple preparations can
- * be registered against one running service; each one owns its rootPath and
- * activity timestamps. Routes pass the preparation explicitly to every
-   * runtime operation that needs one, so there is no swap-state to manage.
- */
-export interface PreparationContext {
-    rootPath: string;
-    startedAt: string;
-    lastActivity: string;
-}
-export declare class LocalServiceRuntime {
-    readonly host: string;
-    port: number;
-    readonly startedAt: string;
-    readonly packageVersion?: string;
-    readonly handlers: Partial<LocalServiceRunHandlers>;
-    /**
-     * The seed root path the runtime was constructed with. Used as a
-     * non-preparation fallback when a preparation-independent route
-     * (Build Plans, action proposals, runs listings) needs an anchor to load
-     * shared state (user-library Build Plans, bundled Build Plans, etc).
-     */
-    readonly rootPath: string;
-    /**
-     * Per-instance bearer token. Mutating routes require this on the
-     * Authorization header. `null` means token-less mode (test harness).
-     */
-    readonly authToken: string | null;
-    /** Map of prepDataDir -> PreparationContext. */
-    private preparationContexts;
-    /** Hook called whenever a preparation is registered or deregistered. */
-    private onRegistryChanged;
-    /** In-flight runs across all preparations. Used for `idle_for_seconds`. */
-    private activeRunCount;
-    /**
-     * Active Build run cancellation handles, keyed by run id. Populated
-     * when a Build run is launched and cleared once the run reaches a
-     * terminal state. Each entry remembers where the persisted record lives
-     * so cancel can mark it without re-resolving the Preparation.
-     *
-     * TODO(cloud): when the cloud variant lands, wire `RunLeaseStore`
-     * (see `cloud-seams.ts` B4.2) through this map. Multi-replica engines
-     * need a shared lease store so a replica can take over a run whose
-     * owning replica died.
-     */
-    private activeBuildRuns;
-    /**
-     * Idempotency-key cache for `POS../../build-runs`. Outer key is the
-     * resolved preparation root; inner key is the client-supplied idempotency
-     * value. Namespacing per preparation prevents key collisions across
-     * tenants on the same engine (CSO finding: a malicious preparation could
-     * otherwise hijack another preparation's run id by reusing its key).
-     * Entries expire after `IDEMPOTENCY_TTL_MS`.
-     *
-     * TODO(cloud): when the cloud variant lands, wire `IdempotencyStore`
-     * (see `cloud-seams.ts` B4.1) through this map. Multi-replica engines
-     * need a shared store so retries that land on a different replica
-     * still hit the same dedupe entry.
-     */
-    private idempotencyKeyCache;
-    /**
-     * Read-side caches. Polling clients (Interf UI, CLI status loops)
-     * hit list/get endpoints multiple times per second; without these,
-     * every request re-walks the filesystem and re-parses every JSON
-     * record through Zod. The runtime invalidates each cache on the
-     * matching write path. See {@link runtime-caches} for design notes.
-     */
-    private readonly buildRunCache;
-    private readonly verifyRunCache;
-    private readonly readinessCache;
-    private readonly sourceFilesCache;
-    private readonly buildPlanListingCache;
-    /**
-     * 0.17 — sink for per-Artifact billing events. Set once at construction.
-     * Lazy-defaults to a per-run JSONL writer when no override was injected.
-     */
-    private readonly billingEventSink;
-    /**
-     * 0.17 — cloud-variant injection points. The local engine accepts
-     * these on the options surface but does not consume them yet — the
-     * in-process Maps remain authoritative for idempotency and
-     * run-lease state. The cloud variant fork will swap to these stores;
-     * the option-fields are documented here so the cloud build has a
-     * stable target. See `cloud-seams.ts` for the contracts.
-     */
-    readonly cloudIdempotencyStore: IdempotencyStore | null;
-    readonly cloudRunLeaseStore: RunLeaseStore | null;
-    private cloudTokenValidator;
-    constructor(options: LocalServiceRuntimeOptions);
-    setBoundPort(port: number): void;
-    /**
-     * 0.17 — token validator setter for cloud variants. Stored on the
-     * runtime so `isAuthorizedMutation` in `server.ts` can opt into the
-     * async per-account check when present. Local default: never set —
-     * the static bearer-token check runs.
-     */
-    setTokenValidator(validator: TokenValidator | null): void;
-    getTokenValidator(): TokenValidator | null;
-    /** Set a hook that fires whenever the registered preparations change. */
-    setOnRegistryChanged(handler: (() => void) | null): void;
-    /**
-     * Register a preparation with this runtime. Returns the PreparationContext.
-     * Idempotent: re-registering an existing preparation updates `lastActivity`.
-     */
-    registerPreparation(prepDataDir: string): PreparationContext;
-    /**
-     * Remove a preparation from the runtime. Returns true if a preparation was
-     * removed.
-     */
-    deregisterPreparation(prepDataDir: string): boolean;
-    /**
-     * Most recently active preparation, or the first registered if none has
-     * activity yet. Server code uses this as the fallback when a request
-     * does not specify a preparation. Throws if none are registered.
-     */
-    defaultPreparationDataDir(): string;
-    /** Look up a preparation context by rootPath. */
-    getPreparationContext(prepDataDir: string): PreparationContext | null;
-    /** All registered preparations, ordered by registration time. */
-    listRegisteredPreparations(): PreparationContext[];
-    /** True when no preparations are registered. */
-    hasNoPreparations(): boolean;
-    /** Number of registered preparations. */
-    registeredPreparationCount(): number;
-    /** Increment in-flight run counter. Call when a long-running run starts. */
-    beginActiveRun(): void;
-    /** Decrement in-flight run counter. Pair with `beginActiveRun`. */
-    endActiveRun(): void;
-    /** Sum of in-flight runs across all preparations. */
-    activeRuns(): number;
-    /**
-     * Mark the preparation as recently active. Routes call this on entry so
-     * `idleForSeconds` and the registry snapshots stay in sync with the
-     * actual request cadence.
-     */
-    touchPreparation(prepDataDir: string): void;
-    /** Seconds since the most recent preparation activity (0 if active). */
-    idleForSeconds(): number;
-    health(prepDataDir?: string): LocalServiceHealth;
-    listPreparations(prepDataDir: string): PreparationResource[];
-    getPreparation(prepDataDir: string, preparationName: string): PreparationResource | null;
-    listPreparationReadiness(prepDataDir: string): Readiness[];
-    getPreparationReadiness(prepDataDir: string, preparationName: string): Readiness | null;
-    listReadiness(prepDataDir: string): Readiness[];
-    getReadiness(prepDataDir: string, preparationName: string): Readiness | null;
-    computePreparationReadiness(prepDataDir: string, preparation: SourcePreparationConfig): Readiness;
-    private computePreparationReadinessUncached;
-    listSourceFiles(prepDataDir: string, preparationName?: string | null): SourceFileResource[];
-    listBuildPlans(prepDataDir: string): BuildPlanResource[];
-    getBuildPlanResource(prepDataDir: string, buildPlanId: string): BuildPlanResource | null;
-    listJobs(prepDataDir: string): LocalJobRunResource[];
-    getJob(prepDataDir: string, runId: string): LocalJobRunResource | null;
-    getJobEvents(prepDataDir: string, runId: string): LocalJobEvent[] | null;
-    getExecutorStatus(): LocalExecutorStatus;
-    selectExecutor(requestValue: unknown): LocalExecutorStatus;
-    /**
-     * Snapshot of the merged agents registry (built-in detected + custom)
-     * with the current role-map and resolved active agent.
-     */
-    getAgentsRegistry(): {
-        agents: import("../contracts/lib/schema.js").AgentRecord[];
-        role_map: import("../contracts/lib/schema.js").RoleMap;
-        active_agent: import("../contracts/lib/schema.js").AgentRecord | null;
-    };
-    registerCustomAgent(input: {
-        name: string;
-        display_name: string;
-        command: string;
-    }): {
-        agents: import("../contracts/lib/schema.js").AgentRecord[];
-        role_map: import("../contracts/lib/schema.js").RoleMap;
-        active_agent: import("../contracts/lib/schema.js").AgentRecord | null;
-    };
-    unregisterCustomAgent(name: string): {
-        agents: import("../contracts/lib/schema.js").AgentRecord[];
-        role_map: import("../contracts/lib/schema.js").RoleMap;
-        active_agent: import("../contracts/lib/schema.js").AgentRecord | null;
-    };
-    patchAgentsRoleMap(patch: Record<string, string>): {
-        role_map: import("../contracts/lib/schema.js").RoleMap;
-        active_agent: import("../contracts/lib/schema.js").AgentRecord | null;
-    };
-    listActionProposals(prepDataDir: string): ActionProposalResource[];
-    getActionProposal(prepDataDir: string, proposalId: string): ActionProposalResource | null;
-    createActionProposal(prepDataDir: string, requestValue: unknown): Promise<ActionProposalResource>;
-    decideActionProposal(prepDataDir: string, proposalId: string, requestValue: unknown): Promise<ActionProposalResource | null>;
-    listRunObservability(prepDataDir: string): RunObservabilityResource[];
-    getRunObservability(prepDataDir: string, runId: string): RunObservabilityResource | null;
-    /**
-     * Build Plan Activity runs: every Build Plan draft or improvement job whose
-     * Build Plan id matches `buildPlanId`. Surfaced through
-     * `GET /v1/build-plans/<id>/runs` so Build Plan detail can show the full
-     * audit trail of authoring + improvement work.
-     */
-    listBuildPlanRuns(prepDataDir: string, buildPlanId: string): RunObservabilityResource[];
-    private createJobRun;
-    private appendJobRunEvent;
-    createReadinessCheckDraftRun(prepDataDir: string, requestValue: unknown): Promise<LocalJobRunResource>;
-    applyBuildPlanChange(prepDataDir: string, requestValue: unknown): BuildPlanChangeResult;
-    applyPreparationSetup(prepDataDir: string, requestValue: unknown): PreparationSetupResult;
-    applyPreparationChange(prepDataDir: string, requestValue: unknown): PreparationChangeResult;
-    applyReset(prepDataDir: string, requestValue: unknown): ResetResult;
-    createBuildPlanAuthoringRun(prepDataDir: string, requestValue: unknown, jobType?: "build-plan-draft" | "build-plan-improvement"): Promise<LocalJobRunResource>;
-    listVerifiableContexts(prepDataDir: string): VerifiableContextResource[];
-    getVerifiableContext(prepDataDir: string, preparationName: string): VerifiableContextResource | null;
-    listBuildRuns(prepDataDir: string): BuildRunResource[];
-    listBuildRunsForPreparation(prepDataDir: string, preparationName: string): BuildRun[];
-    getBuildRun(prepDataDir: string, runId: string): BuildRunResource | null;
-    getBuildRunEvents(prepDataDir: string, runId: string): InterfRunEvent[] | null;
-    getBuildRunProof(prepDataDir: string, runId: string): ProofRecord[] | null;
-    getBuildRunArtifacts(prepDataDir: string, runId: string): ArtifactRef[] | null;
-    createBuildRun(prepDataDir: string, requestValue: unknown): Promise<BuildRunResource>;
-    /**
-     * Cancel an in-flight Build run. Marks the persisted record as
-     * `cancelled`, emits a `run.cancelled` event to capture the cancellation in
-     * the run timeline, and clears the active handle so retries may start a
-     * fresh run. If the run already finished, returns
-     * `{ cancelled: false, reason: "already finished" }` and persists nothing.
-     */
-    cancelBuildRun(runId: string): {
-        cancelled: boolean;
-        reason?: string;
-    };
-    /**
-     * Look up the run id previously associated with this idempotency key in
-     * `prepDataDir`. Returns null when the key is unknown or its TTL has
-     * elapsed. The preparation argument is required so that the same key in
-     * two different preparations always returns two different runs.
-     */
-    findIdempotentBuildRun(prepDataDir: string, key: string): string | null;
-    /**
-     * Cache the run id created (or returned) for this idempotency key in
-     * `prepDataDir`. Entries expire after `IDEMPOTENCY_TTL_MS`. Pruning
-     * is opportunistic: the previous implementation walked every entry on
-     * every read AND write, which was O(N) per request. Now we only sweep
-     * when the cache grows past {@link IDEMPOTENCY_PRUNE_THRESHOLD}.
-     */
-    recordIdempotentBuildRun(prepDataDir: string, key: string, runId: string): void;
-    /** Total cached idempotency entries across all preparations. */
-    private totalIdempotencyEntries;
-    private pruneIdempotencyKeyCache;
-    /**
-     * Test seam: force the cached entry for `key` in `prepDataDir` to be
-     * expired so the next lookup returns null. Returns true when an entry was
-     * found and expired. Tests use this in place of fake timers because the
-     * idempotency TTL is one hour and faking `Date.now()` would destabilize
-     * unrelated runtime state.
-     */
-    expireIdempotencyKeyForTesting(prepDataDir: string, key: string): boolean;
-    listVerifyRuns(prepDataDir: string): VerifyRunResource[];
-    listVerifyRunsForPreparation(prepDataDir: string, preparationName: string): VerifyRunResource[];
-    getVerifyRun(prepDataDir: string, runId: string): VerifyRunResource | null;
-    createVerifyRun(prepDataDir: string, requestValue: unknown): Promise<VerifyRunResource>;
-    private runBuildInBackground;
-    private runTestInBackground;
-    private runReadinessCheckDraftInBackground;
-    private runReadinessCheckDraftInBackgroundInner;
-    private runBuildPlanAuthoringInBackground;
-    private runBuildPlanAuthoringInBackgroundInner;
-    private jobRunContext;
-    private defaultPreparationName;
-    private planActionProposal;
-    private directServiceActionClarification;
-    private buildActionProposal;
-    private submitActionProposal;
-    private resolvePreparationConfig;
-    private ensureVerifiableContextForRun;
-    private readBuildRun;
-    private hydrateBuildRunFromRuntime;
-    private finalizeInterruptedBuildRuns;
-    private finalizeInterruptedJobRuns;
-    /**
-     * 0.17 — emit per-Artifact billing events when a Build run reaches
-     * a terminal state. STUB FORM: writes a JSONL file alongside the run
-     * record by default. Production sink (Metronome HTTP) wires in 0.18+.
-     * The JSONL output is observability/dev fixture, NOT production
-     * billing data.
-     */
-    private emitBillingEventsForRun;
-    private writeBuildRun;
-    private writeJobRun;
-    private writeActionProposal;
-    private setJobRunResult;
-    private recordBuildRunEvent;
-    private refreshBuildRunFromRuntime;
-    private emitRuntimeDerivedEvents;
-    private readLatestReadinessRun;
-    private checksEvaluatedEvent;
-    private readinessUpdatedEvent;
-    private writeVerifyRun;
-}
-export declare function createLocalServiceRuntime(options: LocalServiceRuntimeOptions): LocalServiceRuntime;