@interf/compiler 0.13.0 → 0.18.0

package/dist/packages/{local-service → engine}/runtime.d.ts

@@ -1,8 +1,10 @@
-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-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 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";
+import { type ArtifactRef, type CompileRun, 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 "./compile/billing-events.js";
+import type { IdempotencyStore, RunLeaseStore, TokenValidator } from "./cloud-seams.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;
@@ -10,7 +12,7 @@ export interface LocalServiceCompileRunContext {
     preparationConfig: SourcePreparationConfig;
     events: RunEventSink;
 }
-export interface LocalServiceTestRunContext {
+export interface LocalServiceVerifyRunContext {
     runId: string;
     sourcePath: string;
     compiledPath: string;
@@ -41,7 +43,7 @@ export interface LocalServiceActionPlanningContext {
 export interface LocalServiceRunHandlers {
     planActionProposal(request: ActionProposalCreateRequest, context: LocalServiceActionPlanningContext): Promise<ActionProposalPlan>;
     createCompileRun(request: CompileRunCreateRequest, context: LocalServiceCompileRunContext): Promise<LocalRunHandlerResult>;
-    createTestRun(request: TestRunCreateRequest, context: LocalServiceTestRunContext): Promise<LocalRunHandlerResult>;
+    createVerifyRun(request: VerifyRunCreateRequest, context: LocalServiceVerifyRunContext): Promise<LocalRunHandlerResult>;
     createReadinessCheckDraft(request: ReadinessCheckDraftCreateRequest, context: LocalServiceJobRunContext): Promise<ReadinessCheckDraftResult>;
     createMethodAuthoringRun(request: MethodAuthoringCreateRequest, context: LocalServiceJobRunContext): Promise<MethodAuthoringResult>;
 }
@@ -58,11 +60,26 @@ export interface LocalServiceRuntimeOptions {
      * 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-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
+ * 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 {
@@ -89,25 +106,35 @@ export declare class LocalServiceRuntime {
      */
     readonly authToken: string | null;
     /** Map of prepDataDir -> PreparationContext. */
-    private workspaces;
-    /** Hook called whenever a workspace is registered or deregistered. */
+    private preparationContexts;
+    /** Hook called whenever a preparation is registered or deregistered. */
     private onRegistryChanged;
-    /** In-flight runs across all workspaces. Used for `idle_for_seconds`. */
+    /** 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.
+     *
+     * 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 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).
+     * 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;
     /**
@@ -118,62 +145,92 @@ export declare class LocalServiceRuntime {
      * matching write path. See {@link runtime-caches} for design notes.
      */
     private readonly compileRunCache;
-    private readonly testRunCache;
+    private readonly verifyRunCache;
     private readonly readinessCache;
     private readonly sourceFilesCache;
     private readonly methodListingCache;
+    /**
+     * 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;
-    /** Set a hook that fires whenever the registered workspaces change. */
+    /**
+     * 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 workspace with this runtime. Returns the PreparationContext.
-     * Idempotent: re-registering an existing workspace updates `lastActivity`.
+     * Register a preparation with this runtime. Returns the PreparationContext.
+     * Idempotent: re-registering an existing preparation updates `lastActivity`.
      */
     registerPreparation(prepDataDir: string): PreparationContext;
     /**
-     * Remove a workspace from the runtime. Returns true if a workspace was
+     * Remove a preparation from the runtime. Returns true if a preparation was
      * removed.
      */
     deregisterPreparation(prepDataDir: string): boolean;
     /**
-     * Most recently active workspace, or the first registered if none has
+     * Most recently active preparation, 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.
+     * does not specify a preparation. Throws if none are registered.
      */
     defaultPreparationDataDir(): string;
-    /** Look up a workspace context by rootPath. */
+    /** Look up a preparation context by rootPath. */
     getPreparationContext(prepDataDir: string): PreparationContext | null;
-    /** All registered workspaces, ordered by registration time. */
+    /** All registered preparations, ordered by registration time. */
     listRegisteredPreparations(): PreparationContext[];
-    /** True when no workspaces are registered. */
-    hasNoWorkspaces(): boolean;
-    /** Number of registered workspaces. */
+    /** 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 workspaces. */
+    /** Sum of in-flight runs across all preparations. */
     activeRuns(): number;
     /**
-     * Mark the workspace as recently active. Routes call this on entry so
+     * 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 workspaces for the registry / status output. */
+    /**
+     * 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 workspace activity (0 if active). */
+    /** 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;
+    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[];
     listWorkspaceFiles(prepDataDir: string): WorkspaceFileResource[];
@@ -184,25 +241,50 @@ export declare class LocalServiceRuntime {
     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;
-    /**
-     * 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;
@@ -218,7 +300,7 @@ export declare class LocalServiceRuntime {
     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
+     * `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.
@@ -230,8 +312,8 @@ export declare class LocalServiceRuntime {
     /**
      * 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.
+     * 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;
     /**
@@ -242,7 +324,7 @@ export declare class LocalServiceRuntime {
      * when the cache grows past {@link IDEMPOTENCY_PRUNE_THRESHOLD}.
      */
     recordIdempotentCompileRun(prepDataDir: string, key: string, runId: string): void;
-    /** Total cached idempotency entries across all workspaces. */
+    /** Total cached idempotency entries across all preparations. */
     private totalIdempotencyEntries;
     private pruneIdempotencyKeyCache;
     /**
@@ -253,10 +335,10 @@ export declare class LocalServiceRuntime {
      * 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>;
+    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;
@@ -272,6 +354,15 @@ export declare class LocalServiceRuntime {
     private resolvePreparationConfig;
     private ensureCompiledForRun;
     private readCompileRun;
+    private finalizeInterruptedCompileRuns;
+    /**
+     * 0.17 — emit per-Artifact billing events when a compile 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 writeCompileRun;
     private writeJobRun;
     private writeActionProposal;
@@ -282,6 +373,6 @@ export declare class LocalServiceRuntime {
     private readLatestReadinessRun;
     private checksEvaluatedEvent;
     private readinessUpdatedEvent;
-    private writeTestRun;
+    private writeVerifyRun;
 }
 export declare function createLocalServiceRuntime(options: LocalServiceRuntimeOptions): LocalServiceRuntime;