feat: P2 operator, preprocessing state/service, and runtime config lease

This commit is contained in:
2026-08-11 18:40:11 +02:00
parent ca391ba59c
commit f7c2b69837
10 changed files with 2501 additions and 31 deletions
@@ -0,0 +1,505 @@
import { createHash, randomBytes } from "node:crypto";
import { readdirSync, readFileSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
import { isIP } from "node:net";
import { join } from "node:path";
import type { WorkspaceDescriptor } from "./schema.js";
import {
PreprocessingStateStore,
type FkReviewRecord,
type PreprocessingJobState,
type SessionInventoryRow,
} from "./preprocessing-state.js";
import type { DeterministicRuntimeConfigLease } from "./runtime-config-lease.js";
export interface WorkspaceOperationResult {
schemaVersion: 1;
status: "succeeded" | "unchanged" | "dry_run" | "blocked" | "failed";
code:
| "ok" | "workspace_not_found" | "workspace_not_activatable"
| "binding_missing" | "preprocessing_conflict"
| "preprocessing_resume_mismatch" | "manual_review_required"
| "evidence_materialization_required" | "effective_config_mismatch"
| "semantic_index_incompatible" | "annotation_invalid"
| "egress_policy_refused";
workspaceId: string;
workspaceRevision: string;
descriptorBlob: string;
operation: string;
runId?: string;
childRuns?: Record<string, string>;
completedStages: string[];
counts?: Record<string, number>;
artifactIdentities?: Array<{ kind: string; digest: string }>;
/** Suggested FK annotations YAML for the operator to write to --output (schema suggest-fks). */
suggestedFksYaml?: string;
warnings?: string[];
}
export interface ChildProcessRequest {
argv: string[];
configPath: string;
}
interface ActiveRuntime {
workspace: WorkspaceDescriptor;
workspaceId: string;
workspaceRevision: string;
descriptorBlob: string;
catalogBlob: string;
configLease: DeterministicRuntimeConfigLease;
}
interface ChildProcessResult {
exitCode: number;
stdout: string;
stderr: string;
}
export interface WorkspacePreprocessingServiceDeps {
dataRoot: string;
acquireActiveRuntime(workspaceId: string): Promise<ActiveRuntime>;
runChild(request: ChildProcessRequest): Promise<ChildProcessResult>;
listSessions(workspaceId: string): Promise<readonly SessionInventoryRow[]>;
semanticPreflight(workspace: WorkspaceDescriptor): Promise<
{ ok: true } | { ok: false; code: "workspace_not_activatable" | "semantic_index_incompatible" }
>;
httpPrivateHostAllowlist?: readonly string[];
}
interface RunScope {
runtime: ActiveRuntime;
state: PreprocessingStateStore;
job: PreprocessingJobState;
}
function digest(value: string | Buffer): string {
return `sha256:${createHash("sha256").update(value).digest("hex")}`;
}
function baseResult(
runtime: ActiveRuntime,
operation: string,
status: WorkspaceOperationResult["status"],
code: WorkspaceOperationResult["code"],
extra: Omit<Partial<WorkspaceOperationResult>, "schemaVersion" | "status" | "code" | "workspaceId" | "workspaceRevision" | "descriptorBlob" | "operation"> = {},
): WorkspaceOperationResult {
return {
schemaVersion: 1,
status,
code,
workspaceId: runtime.workspaceId,
workspaceRevision: runtime.workspaceRevision,
descriptorBlob: runtime.descriptorBlob,
operation,
completedStages: [],
...extra,
};
}
function isPrivateHost(hostname: string): boolean {
if (hostname === "localhost" || hostname === "metadata.google.internal") return true;
const address = isIP(hostname);
if (address === 4) {
if (/^127\./.test(hostname) || /^10\./.test(hostname) || /^192\.168\./.test(hostname)) return true;
if (/^169\.254\./.test(hostname) || /^0\./.test(hostname)) return true;
const match = /^172\.(\d+)\./.exec(hostname);
return Boolean(match && Number(match[1]) >= 16 && Number(match[1]) <= 31);
}
if (address === 6) {
const normalized = hostname.toLowerCase();
return normalized === "::1" || normalized.startsWith("fe80:") || normalized.startsWith("fd") || normalized.startsWith("fc");
}
return hostname.endsWith(".internal");
}
function noEvidenceWarning(workspace: WorkspaceDescriptor): string[] {
return workspace.evidence === undefined ? ["workspace has no Evidence source"] : [];
}
export class WorkspacePreprocessingService {
constructor(private readonly deps: WorkspacePreprocessingServiceDeps) {}
async inspect(options: { workspaceId: string }): Promise<WorkspaceOperationResult> {
try {
const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
return baseResult(runtime, "inspect", "succeeded", "ok", {
artifactIdentities: [
{ kind: "descriptor", digest: runtime.descriptorBlob },
{ kind: "catalog", digest: runtime.catalogBlob },
{ kind: "runtime_config", digest: runtime.configLease.configDigest },
],
});
} catch {
return {
schemaVersion: 1,
status: "failed",
code: "workspace_not_activatable",
workspaceId: options.workspaceId,
workspaceRevision: "",
descriptorBlob: "",
operation: "inspect",
completedStages: [],
};
}
}
async preprocessDwh(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
const scope = await this.startRun(options.workspaceId, "preprocess dwh", options.resumeRunId);
if (scope.job.completedStages.includes("dwh")) {
return baseResult(scope.runtime, "preprocess dwh", "unchanged", "ok", {
runId: scope.job.runId,
childRuns: scope.job.childRuns,
completedStages: [...scope.job.completedStages],
});
}
const payload = await this.runJsonStage(scope.runtime, [
"preprocess", "dwh", "--steps", "introspect,lsh",
...(scope.job.childRuns.dwh ? ["--resume", scope.job.childRuns.dwh] : []),
"--json", "-c", "/dev/fd/3",
]);
const childRun = this.requireRunId(payload.run_id);
scope.job.childRuns.dwh = childRun;
if (!scope.job.completedStages.includes("dwh")) scope.job.completedStages.push("dwh");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
return baseResult(scope.runtime, "preprocess dwh", "succeeded", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
});
}
async suggestFks(options: {
workspaceId: string;
fromSql?: ReadonlyArray<{ name: string; sql: string }>;
assume?: readonly string[];
resumeRunId?: string;
}): Promise<WorkspaceOperationResult> {
const scope = await this.startRun(options.workspaceId, "schema suggest-fks", options.resumeRunId);
return await this.runSuggestStage(scope, options.fromSql ?? [], options.assume ?? []);
}
async checkSchema(options: {
workspaceId: string;
annotationsYaml?: string;
reviewedCandidatesDigest?: string;
}): Promise<WorkspaceOperationResult> {
const runtime = await this.deps.acquireActiveRuntime(options.workspaceId);
const state = this.state(runtime.workspaceId);
if ((options.annotationsYaml === undefined) !== (options.reviewedCandidatesDigest === undefined)) {
return baseResult(runtime, "schema check", "failed", "annotation_invalid");
}
if (options.reviewedCandidatesDigest === undefined) {
const payload = await this.runJsonStage(runtime, ["schema", "check", "--json", "-c", "/dev/fd/3"]);
return baseResult(runtime, "schema check", Number(payload.orphan_count ?? 0) === 0 ? "succeeded" : "failed", Number(payload.orphan_count ?? 0) === 0 ? "ok" : "annotation_invalid");
}
const reviewedCandidatesDigest = options.reviewedCandidatesDigest;
const runId = this.findRunIdByCandidateDigest(state, reviewedCandidatesDigest);
if (!runId) return baseResult(runtime, "schema check", "failed", "annotation_invalid");
const request = await this.withStagedInputs(runtime.workspaceId, [
{ flag: "--annotations", name: "annotations.yaml", contents: options.annotationsYaml! },
], async (argv) => await this.runJsonStage(runtime, [
"schema", "check", ...argv,
"--reviewed-candidates", reviewedCandidatesDigest,
"--json", "-c", "/dev/fd/3",
]));
if (request.reviewed_candidates_digest !== reviewedCandidatesDigest || typeof request.annotations_digest !== "string") {
return baseResult(runtime, "schema check", "failed", "annotation_invalid", { runId });
}
const annotationsDigest = request.annotations_digest;
const review = state.writeFkReview(runId, {
reviewedCandidatesDigest,
annotationsDigest,
workspaceRevision: runtime.workspaceRevision,
});
const job = state.readJob(runId);
if (!job.completedStages.includes("fk_review")) {
job.reviewDigest = review.digest;
job.completedStages.push("fk_review");
state.writeJob(job);
}
return baseResult(runtime, "schema check", "succeeded", "ok", {
runId,
completedStages: [...job.completedStages],
artifactIdentities: [{ kind: "fk_review", digest: review.digest }],
});
}
async indexSchema(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
const scope = await this.startRun(options.workspaceId, "index-schema", options.resumeRunId);
const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
if (!semantic.ok) return baseResult(scope.runtime, "index-schema", "failed", semantic.code, { runId: scope.job.runId });
if (scope.job.completedStages.includes("schema_index")) {
return baseResult(scope.runtime, "index-schema", "unchanged", "ok", {
runId: scope.job.runId,
completedStages: [...scope.job.completedStages],
});
}
const payload = await this.runJsonStage(scope.runtime, ["vector", "index-schema", "--json", "-c", "/dev/fd/3"]);
const counts = this.numberRecord(payload.counts);
scope.job.completedStages.push("schema_index");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
return baseResult(scope.runtime, "index-schema", "succeeded", "ok", {
runId: scope.job.runId,
completedStages: [...scope.job.completedStages],
counts,
});
}
async preprocessEvidence(options: { workspaceId: string; dryRun?: boolean; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
const scope = await this.startRun(options.workspaceId, "preprocess evidence", options.resumeRunId);
if (scope.runtime.workspace.evidence === undefined) {
return baseResult(scope.runtime, "preprocess evidence", "unchanged", "ok", {
warnings: noEvidenceWarning(scope.runtime.workspace),
});
}
const policy = this.evidencePolicy(scope.runtime.workspace);
if (policy !== undefined) return baseResult(scope.runtime, "preprocess evidence", policy.status, policy.code, { warnings: policy.warnings });
const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
if (!semantic.ok) return baseResult(scope.runtime, "preprocess evidence", "failed", semantic.code, { runId: scope.job.runId });
if (scope.job.completedStages.includes("evidence") && !options.dryRun) {
return baseResult(scope.runtime, "preprocess evidence", "unchanged", "ok", {
runId: scope.job.runId,
completedStages: [...scope.job.completedStages],
});
}
const payload = await this.runJsonStage(scope.runtime, [
"preprocess", "evidence",
...(options.dryRun ? ["--dry-run"] : []),
...(scope.job.childRuns.evidence ? ["--resume", scope.job.childRuns.evidence] : []),
"--json", "-c", "/dev/fd/3",
]);
if (typeof payload.run_id === "string") scope.job.childRuns.evidence = this.requireRunId(payload.run_id);
if (!options.dryRun && !scope.job.completedStages.includes("evidence")) scope.job.completedStages.push("evidence");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
return baseResult(scope.runtime, "preprocess evidence", options.dryRun ? "dry_run" : "succeeded", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
counts: this.numberRecord(payload.counts),
});
}
async run(options: { workspaceId: string; resumeRunId?: string }): Promise<WorkspaceOperationResult> {
const scope = await this.startRun(options.workspaceId, "preprocess run", options.resumeRunId);
if (!scope.job.completedStages.includes("dwh")) {
const payload = await this.runJsonStage(scope.runtime, [
"preprocess", "dwh", "--steps", "introspect,lsh",
...(scope.job.childRuns.dwh ? ["--resume", scope.job.childRuns.dwh] : []),
"--json", "-c", "/dev/fd/3",
]);
scope.job.childRuns.dwh = this.requireRunId(payload.run_id);
scope.job.completedStages.push("dwh");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
}
if (!scope.job.completedStages.includes("fk_suggest")) {
const suggest = await this.runSuggestStage(scope, [], []);
if (suggest.code === "manual_review_required") return suggest;
}
const candidate = this.state(scope.runtime.workspaceId).readFkCandidates(scope.job.runId);
if (candidate && !scope.job.completedStages.includes("fk_review")) {
const review = this.state(scope.runtime.workspaceId).readFkReview(scope.job.runId);
if (!review || review.reviewedCandidatesDigest !== candidate.digest) {
return baseResult(scope.runtime, "preprocess run", "blocked", "manual_review_required", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
artifactIdentities: [{ kind: "fk_candidates", digest: candidate.digest }],
});
}
scope.job.completedStages.push("fk_review");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
}
const semantic = await this.deps.semanticPreflight(scope.runtime.workspace);
if (!semantic.ok) return baseResult(scope.runtime, "preprocess run", "failed", semantic.code, { runId: scope.job.runId });
if (!scope.job.completedStages.includes("schema_index")) {
const payload = await this.runJsonStage(scope.runtime, ["vector", "index-schema", "--json", "-c", "/dev/fd/3"]);
scope.job.completedStages.push("schema_index");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
const warnings = noEvidenceWarning(scope.runtime.workspace);
if (scope.runtime.workspace.evidence === undefined) {
return baseResult(scope.runtime, "preprocess run", "succeeded", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
counts: this.numberRecord(payload.counts),
warnings,
});
}
}
if (scope.runtime.workspace.evidence === undefined) {
return baseResult(scope.runtime, "preprocess run", "succeeded", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
warnings: noEvidenceWarning(scope.runtime.workspace),
});
}
const policy = this.evidencePolicy(scope.runtime.workspace);
if (policy !== undefined) {
return baseResult(scope.runtime, "preprocess run", policy.status, policy.code, {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
warnings: policy.warnings,
});
}
if (!scope.job.completedStages.includes("evidence")) {
const payload = await this.runJsonStage(scope.runtime, [
"preprocess", "evidence",
...(scope.job.childRuns.evidence ? ["--resume", scope.job.childRuns.evidence] : []),
"--json", "-c", "/dev/fd/3",
]);
if (typeof payload.run_id === "string") scope.job.childRuns.evidence = this.requireRunId(payload.run_id);
scope.job.completedStages.push("evidence");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
return baseResult(scope.runtime, "preprocess run", "succeeded", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
counts: this.numberRecord(payload.counts),
});
}
return baseResult(scope.runtime, "preprocess run", "unchanged", "ok", {
runId: scope.job.runId,
childRuns: { ...scope.job.childRuns },
completedStages: [...scope.job.completedStages],
});
}
private async startRun(workspaceId: string, operation: string, resumeRunId?: string): Promise<RunScope> {
const runtime = await this.deps.acquireActiveRuntime(workspaceId);
const state = this.state(runtime.workspaceId);
await state.assertSessionInventoryCompatible(runtime.workspaceRevision, await this.deps.listSessions(runtime.workspaceId));
const job = await state.beginJob({
operation,
runId: resumeRunId,
workspaceRevision: runtime.workspaceRevision,
descriptorBlob: runtime.descriptorBlob,
catalogBlob: runtime.catalogBlob,
configDigest: runtime.configLease.configDigest,
bindingDigest: runtime.configLease.bindingDigest,
});
return { runtime, state, job };
}
private state(workspaceId: string): PreprocessingStateStore {
return new PreprocessingStateStore({ dataRoot: this.deps.dataRoot, workspaceId });
}
private async runSuggestStage(
scope: RunScope,
fromSql: ReadonlyArray<{ name: string; sql: string }>,
assume: readonly string[],
): Promise<WorkspaceOperationResult> {
const payload = await this.withStagedInputs(scope.runtime.workspaceId, fromSql.map((entry) => ({
flag: "--from-sql",
name: entry.name,
contents: entry.sql,
})), async (stagedArgv) => await this.runJsonStage(scope.runtime, [
"schema", "suggest-fks", ...stagedArgv,
...assume.flatMap((value) => ["--assume", value]),
"--json", "-c", "/dev/fd/3",
]));
const candidateCount = Number(payload.candidate_count ?? 0);
const candidateYaml = typeof payload.candidate_yaml === "string" ? payload.candidate_yaml : "";
let artifactIdentities: Array<{ kind: string; digest: string }> | undefined;
if (candidateCount > 0) {
const persisted = this.state(scope.runtime.workspaceId).writeFkCandidates(scope.job.runId, candidateYaml);
scope.job.candidateDigest = persisted.digest;
artifactIdentities = [{ kind: "fk_candidates", digest: persisted.digest }];
}
if (!scope.job.completedStages.includes("fk_suggest")) scope.job.completedStages.push("fk_suggest");
this.state(scope.runtime.workspaceId).writeJob(scope.job);
const resultExtra = {
runId: scope.job.runId,
completedStages: [...scope.job.completedStages],
...(artifactIdentities ? { artifactIdentities } : {}),
...(candidateYaml.length > 0 ? { suggestedFksYaml: candidateYaml } : {}),
};
if (candidateCount > 0) {
return baseResult(scope.runtime, scope.job.operation === "preprocess run" ? "preprocess run" : "schema suggest-fks", "blocked", "manual_review_required", {
...resultExtra,
childRuns: { ...scope.job.childRuns },
});
}
return baseResult(scope.runtime, scope.job.operation === "preprocess run" ? "preprocess run" : "schema suggest-fks", "succeeded", "ok", resultExtra);
}
private async runJsonStage(runtime: ActiveRuntime, argv: string[]): Promise<Record<string, unknown>> {
const result = await this.deps.runChild({ argv, configPath: runtime.configLease.path });
if (result.exitCode !== 0) throw new Error("workspace child failed");
return JSON.parse(result.stdout) as Record<string, unknown>;
}
private requireRunId(value: unknown): string {
if (typeof value !== "string" || !/^[0-9a-f]{32}$/.test(value)) throw new Error("child run id is invalid");
return value;
}
private numberRecord(value: unknown): Record<string, number> | undefined {
if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, nested]) => [key, Number(nested)]));
}
private async withStagedInputs<T>(
workspaceId: string,
inputs: ReadonlyArray<{ flag: string; name: string; contents: string }>,
fn: (argv: string[]) => Promise<T>,
): Promise<T> {
if (inputs.length === 0) return await fn([]);
const root = join(this.deps.dataRoot, "sessions", workspaceId, "preprocessing", `.stage-${randomBytes(6).toString("hex")}`);
mkdirSync(root, { recursive: true, mode: 0o700 });
const argv: string[] = [];
const paths: string[] = [];
try {
for (const input of inputs) {
const path = join(root, input.name);
writeFileSync(path, input.contents, { encoding: "utf8", flag: "wx", mode: 0o600 });
paths.push(path);
argv.push(input.flag, path);
}
return await fn(argv);
} finally {
rmSync(root, { recursive: true, force: true });
}
}
private findRunIdByCandidateDigest(state: PreprocessingStateStore, digestValue: string): string | undefined {
for (const entry of readdirSync(state.fkCandidatesDirectory(), { withFileTypes: true })) {
if (!entry.isFile() || entry.isSymbolicLink() || !/^[0-9a-f]{32}\.yaml$/.test(entry.name)) continue;
const runId = entry.name.slice(0, -".yaml".length);
if (state.readFkCandidates(runId)?.digest === digestValue) return runId;
}
return undefined;
}
private evidencePolicy(workspace: WorkspaceDescriptor): {
status: WorkspaceOperationResult["status"];
code: WorkspaceOperationResult["code"];
warnings?: string[];
} | undefined {
const evidence = workspace.evidence;
if (!evidence) return undefined;
if (evidence.source.type === "filesystem") {
return { status: "blocked", code: "evidence_materialization_required" };
}
if (evidence.source.type === "http") {
for (const value of evidence.source.uris) {
const host = new URL(value).hostname;
if (isPrivateHost(host) && !(evidence.source.allow_private_hosts && this.deps.httpPrivateHostAllowlist?.includes(host))) {
return { status: "failed", code: "egress_policy_refused" };
}
}
return undefined;
}
if (
evidence.source.endpoint_url !== undefined
|| evidence.source.credentials === "ambient"
|| evidence.source.allow_private_endpoint
|| evidence.source.allow_insecure_endpoint
) {
return { status: "failed", code: "egress_policy_refused" };
}
return undefined;
}
}