@interf/compiler 0.9.5 → 0.13.0

package/dist/packages/local-service/runtime.d.ts

@@ -2,7 +2,7 @@ import { type ArtifactRef, type CompileRun, type InterfRunEvent, type ProofRecor
 import { type RunEventSink } from "../execution/events.js";
 import { type ReadinessState } from "../contracts/lib/schema.js";
 import type { SourcePreparationConfig } from "../project-model/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 PreparationReadinessState, type PreparationResource, type ReadinessCheckDraftCreateRequest, type ReadinessCheckDraftResult, type RunObservabilityResource, type SourceFileResource, type WorkspaceFileResource, type TestRunCreateRequest, type TestRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult, type MethodChangeResult, type PreparationChangeResult, type PreparationSetupResult, type ResetResult } from "./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 TestRunCreateRequest, type TestRunResource, type MethodAuthoringCreateRequest, type MethodAuthoringResult, type MethodChangeResult, type PreparationChangeResult, type PreparationSetupResult, type WorkspaceBootstrapResult, type ResetResult } from "./lib/schema.js";
 export interface LocalServiceCompileRunContext {
     runId: string;
     sourcePath: string;
@@ -52,63 +52,217 @@ export interface LocalServiceRuntimeOptions {
     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-workspace context tracked by the runtime. Multiple workspaces can be
+ * registered against one running service; each one owns its rootPath and
+ * activity timestamps. Routes pass the workspace 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 rootPath: string;
     readonly host: string;
-    readonly port: number;
+    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 workspaces;
+    /** Hook called whenever a workspace is registered or deregistered. */
+    private onRegistryChanged;
+    /** In-flight runs across all workspaces. 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 workspace root; inner key is the client-supplied idempotency
+     * value. Namespacing per workspace prevents key collisions across
+     * tenants on the same engine (CSO finding: a malicious workspace could
+     * otherwise hijack another workspace'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 testRunCache;
+    private readonly readinessCache;
+    private readonly sourceFilesCache;
+    private readonly methodListingCache;
     constructor(options: LocalServiceRuntimeOptions);
-    health(): LocalServiceHealth;
-    listPreparations(): PreparationResource[];
-    getPreparation(preparationName: string): PreparationResource | null;
-    listPreparationReadiness(): PreparationReadinessState[];
-    getPreparationReadiness(preparationName: string): PreparationReadinessState | null;
-    listReadiness(): ReadinessState[];
-    getReadiness(preparationName: string): ReadinessState | null;
-    computePreparationReadiness(preparation: SourcePreparationConfig): ReadinessState;
-    listSourceFiles(preparationName?: string | null): SourceFileResource[];
-    listWorkspaceFiles(): WorkspaceFileResource[];
-    listMethods(): MethodResource[];
-    getMethod(methodId: string): MethodResource | null;
-    listJobs(): LocalJobRunResource[];
-    getJob(runId: string): LocalJobRunResource | null;
-    getJobEvents(runId: string): LocalJobEvent[] | null;
+    setBoundPort(port: number): void;
+    /** Set a hook that fires whenever the registered workspaces change. */
+    setOnRegistryChanged(handler: (() => void) | null): void;
+    /**
+     * Register a workspace with this runtime. Returns the PreparationContext.
+     * Idempotent: re-registering an existing workspace updates `lastActivity`.
+     */
+    registerPreparation(prepDataDir: string): PreparationContext;
+    /**
+     * Remove a workspace from the runtime. Returns true if a workspace was
+     * removed.
+     */
+    deregisterPreparation(prepDataDir: string): boolean;
+    /**
+     * Most recently active workspace, or the first registered if none has
+     * activity yet. Server code uses this as the fallback when a request
+     * omits the workspace header. Throws if no workspace is registered.
+     */
+    defaultPreparationDataDir(): string;
+    /** Look up a workspace context by rootPath. */
+    getPreparationContext(prepDataDir: string): PreparationContext | null;
+    /** All registered workspaces, ordered by registration time. */
+    listRegisteredPreparations(): PreparationContext[];
+    /** True when no workspaces are registered. */
+    hasNoWorkspaces(): boolean;
+    /** Number of registered workspaces. */
+    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 workspaces. */
+    activeRuns(): number;
+    /**
+     * Mark the workspace 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 workspaces for the registry / status output. */
+    registeredPreparationSnapshots(): ServiceRegistryWorkspace[];
+    /** Seconds since the most recent workspace 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;
-    listActionProposals(): ActionProposalResource[];
-    getActionProposal(proposalId: string): ActionProposalResource | null;
-    createActionProposal(requestValue: unknown): Promise<ActionProposalResource>;
-    decideActionProposal(proposalId: string, requestValue: unknown): Promise<ActionProposalResource | null>;
-    listRunObservability(): RunObservabilityResource[];
-    getRunObservability(runId: string): RunObservabilityResource | 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;
     private createJobRun;
     private appendJobRunEvent;
-    createReadinessCheckDraftRun(requestValue: unknown): Promise<LocalJobRunResource>;
-    applyMethodChange(requestValue: unknown): MethodChangeResult;
-    applyPreparationSetup(requestValue: unknown): PreparationSetupResult;
-    applyPreparationChange(requestValue: unknown): PreparationChangeResult;
-    applyReset(requestValue: unknown): ResetResult;
-    createMethodAuthoringRun(requestValue: unknown, jobType?: "method-authoring" | "method-improvement"): Promise<LocalJobRunResource>;
-    listPortableContexts(): PortableContextResource[];
-    getPortableContext(preparationName: string): PortableContextResource | null;
-    listCompileRuns(): CompileRunResource[];
-    listCompileRunsForPreparation(preparationName: string): CompileRun[];
-    getCompileRun(runId: string): CompileRunResource | null;
-    getCompileRunEvents(runId: string): InterfRunEvent[] | null;
-    getCompileRunProof(runId: string): ProofRecord[] | null;
-    getCompileRunArtifacts(runId: string): ArtifactRef[] | null;
-    createCompileRun(requestValue: unknown): Promise<CompileRunResource>;
-    listTestRuns(): TestRunResource[];
-    listTestRunsForPreparation(preparationName: string): TestRunResource[];
-    getTestRun(runId: string): TestRunResource | null;
-    createTestRun(requestValue: unknown): Promise<TestRunResource>;
+    createReadinessCheckDraftRun(prepDataDir: string, requestValue: unknown): Promise<LocalJobRunResource>;
+    applyMethodChange(prepDataDir: string, requestValue: unknown): MethodChangeResult;
+    /**
+     * Bootstrap the workspace's source-folder binding and seed the default
+     * Method. Idempotent: re-running with the same source folder preserves
+     * existing preparations and reports `changed: false`.
+     *
+     * The CLI calls this in place of writing `interf.json` directly, so the
+     * operation is recorded by the service (and visible to other clients).
+     */
+    bootstrapWorkspace(prepDataDir: string, requestValue: unknown): WorkspaceBootstrapResult;
+    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 workspace argument is required so that the same key in
+     * two different workspaces 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 workspaces. */
+    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;
+    listTestRuns(prepDataDir: string): TestRunResource[];
+    listTestRunsForPreparation(prepDataDir: string, preparationName: string): TestRunResource[];
+    getTestRun(prepDataDir: string, runId: string): TestRunResource | null;
+    createTestRun(prepDataDir: string, requestValue: unknown): Promise<TestRunResource>;
     private runCompileInBackground;
     private runTestInBackground;
     private runReadinessCheckDraftInBackground;
+    private runReadinessCheckDraftInBackgroundInner;
     private runMethodAuthoringInBackground;
+    private runMethodAuthoringInBackgroundInner;
     private jobRunContext;
     private defaultPreparationName;
     private planActionProposal;