@interf/compiler 0.9.5 → 0.16.0

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

@@ -0,0 +1,318 @@
+import { type ArtifactRef, type CompileRun, type InterfRunEvent, type ProofRecord } from "./execution/lib/schema.js";
+import { type RunEventSink } from "./execution/events.js";
+import { type ReadinessState } from "../contracts/lib/schema.js";
+import type { SourcePreparationConfig } from "../project/lib/schema.js";
+import { type ActionProposalCreateRequest, type ActionProposalPlan, type ActionProposalResource, type CompileRunCreateRequest, type CompileRunResource, type MethodResource, type LocalServiceHealth, type LocalJobEvent, type LocalJobEventAppendRequest, type LocalExecutorStatus, type LocalJobRunResource, type LocalRunHandlerResult, type PortableContextResource, type PreparationResource, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type RunObservabilityResource, type ServiceRegistryWorkspace, type SourceFileResource, type WorkspaceFileResource, type VerifyRunCreateRequest, type VerifyRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult, type MethodChangeResult, type PreparationChangeResult, type PreparationSetupResult, type ResetResult } from "./lib/schema.js";
+export interface LocalServiceCompileRunContext {
+    runId: string;
+    sourcePath: string;
+    compiledPath: string;
+    preparationConfig: SourcePreparationConfig;
+    events: RunEventSink;
+}
+export interface LocalServiceVerifyRunContext {
+    runId: string;
+    sourcePath: string;
+    compiledPath: 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;
+        portable_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>;
+    createCompileRun(request: CompileRunCreateRequest, context: LocalServiceCompileRunContext): Promise<LocalRunHandlerResult>;
+    createVerifyRun(request: VerifyRunCreateRequest, context: LocalServiceVerifyRunContext): Promise<LocalRunHandlerResult>;
+    createReadinessCheckDraft(request: ReadinessCheckDraftCreateRequest, context: LocalServiceJobRunContext): Promise<ReadinessCheckDraftResult>;
+    createMethodAuthoringRun(request: MethodAuthoringCreateRequest, context: LocalServiceJobRunContext): Promise<MethodAuthoringResult>;
+}
+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;
+}
+/**
+ * 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 method 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
+     * (methods, action proposals, runs listings) needs an anchor to load
+     * shared state (user-library methods, bundled methods, 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 compile-run cancellation handles, keyed by run id. Populated
+     * when a compile 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.
+     */
+    private activeCompileRuns;
+    /**
+     * Idempotency-key cache for `POST /v1/compile-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`.
+     */
+    private idempotencyKeyCache;
+    /**
+     * Read-side caches. Polling clients (Compiler 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 compileRunCache;
+    private readonly verifyRunCache;
+    private readonly readinessCache;
+    private readonly sourceFilesCache;
+    private readonly methodListingCache;
+    constructor(options: LocalServiceRuntimeOptions);
+    setBoundPort(port: number): void;
+    /** 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;
+    /**
+     * Snapshot of registered preparations for the registry / status output.
+     * Wire shape (`ServiceRegistryWorkspace`) keeps the legacy
+     * "workspace" name for backward compatibility with the public health
+     * response and `~/.interf/services.json`. Synthetic-workspace bridge
+     * code; do not rename without coordinating an API break.
+     */
+    registeredPreparationSnapshots(): ServiceRegistryWorkspace[];
+    /** 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): ReadinessState[];
+    getPreparationReadiness(prepDataDir: string, preparationName: string): ReadinessState | null;
+    listReadiness(prepDataDir: string): ReadinessState[];
+    getReadiness(prepDataDir: string, preparationName: string): ReadinessState | null;
+    computePreparationReadiness(prepDataDir: string, preparation: SourcePreparationConfig): ReadinessState;
+    private computePreparationReadinessUncached;
+    listSourceFiles(prepDataDir: string, preparationName?: string | null): SourceFileResource[];
+    listWorkspaceFiles(prepDataDir: string): WorkspaceFileResource[];
+    listMethods(prepDataDir: string): MethodResource[];
+    getMethod(prepDataDir: string, methodId: string): MethodResource | 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;
+    /**
+     * Method-scoped runs: every method-authoring or method-improvement job
+     * whose `method` matches `methodId`. Surfaced through
+     * `GET /v1/methods/<id>/runs` so Method Detail can show the full audit
+     * trail of authoring + improvement work for a Method.
+     */
+    listMethodRuns(prepDataDir: string, methodId: string): RunObservabilityResource[];
+    private createJobRun;
+    private appendJobRunEvent;
+    createReadinessCheckDraftRun(prepDataDir: string, requestValue: unknown): Promise<LocalJobRunResource>;
+    applyMethodChange(prepDataDir: string, requestValue: unknown): MethodChangeResult;
+    applyPreparationSetup(prepDataDir: string, requestValue: unknown): PreparationSetupResult;
+    applyPreparationChange(prepDataDir: string, requestValue: unknown): PreparationChangeResult;
+    applyReset(prepDataDir: string, requestValue: unknown): ResetResult;
+    createMethodAuthoringRun(prepDataDir: string, requestValue: unknown, jobType?: "method-authoring" | "method-improvement"): Promise<LocalJobRunResource>;
+    listPortableContexts(prepDataDir: string): PortableContextResource[];
+    getPortableContext(prepDataDir: string, preparationName: string): PortableContextResource | null;
+    listCompileRuns(prepDataDir: string): CompileRunResource[];
+    listCompileRunsForPreparation(prepDataDir: string, preparationName: string): CompileRun[];
+    getCompileRun(prepDataDir: string, runId: string): CompileRunResource | null;
+    getCompileRunEvents(prepDataDir: string, runId: string): InterfRunEvent[] | null;
+    getCompileRunProof(prepDataDir: string, runId: string): ProofRecord[] | null;
+    getCompileRunArtifacts(prepDataDir: string, runId: string): ArtifactRef[] | null;
+    createCompileRun(prepDataDir: string, requestValue: unknown): Promise<CompileRunResource>;
+    /**
+     * Cancel an in-flight compile run. Marks the persisted record as
+     * `cancelled`, emits a `run.failed` 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.
+     */
+    cancelCompileRun(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.
+     */
+    findIdempotentCompileRun(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}.
+     */
+    recordIdempotentCompileRun(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 runCompileInBackground;
+    private runTestInBackground;
+    private runReadinessCheckDraftInBackground;
+    private runReadinessCheckDraftInBackgroundInner;
+    private runMethodAuthoringInBackground;
+    private runMethodAuthoringInBackgroundInner;
+    private jobRunContext;
+    private defaultPreparationName;
+    private planActionProposal;
+    private directServiceActionClarification;
+    private buildActionProposal;
+    private submitActionProposal;
+    private resolvePreparationConfig;
+    private ensureCompiledForRun;
+    private readCompileRun;
+    private writeCompileRun;
+    private writeJobRun;
+    private writeActionProposal;
+    private setJobRunResult;
+    private recordCompileRunEvent;
+    private refreshCompileRunFromRuntime;
+    private emitRuntimeDerivedEvents;
+    private readLatestReadinessRun;
+    private checksEvaluatedEvent;
+    private readinessUpdatedEvent;
+    private writeVerifyRun;
+}
+export declare function createLocalServiceRuntime(options: LocalServiceRuntimeOptions): LocalServiceRuntime;