feat: P2 operator, preprocessing state/service, and runtime config lease
This commit is contained in:
@@ -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;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,383 @@
|
||||
import { createHash, randomBytes } from "node:crypto";
|
||||
import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
|
||||
import {
|
||||
closeSync,
|
||||
constants as fsConstants,
|
||||
fchmodSync,
|
||||
fstatSync,
|
||||
fsyncSync,
|
||||
lstatSync,
|
||||
mkdirSync,
|
||||
openSync,
|
||||
readFileSync,
|
||||
renameSync,
|
||||
unlinkSync,
|
||||
writeFileSync,
|
||||
} from "node:fs";
|
||||
import { dirname, join } from "node:path";
|
||||
|
||||
export type PreprocessingConflictCode = "preprocessing_conflict" | "preprocessing_resume_mismatch";
|
||||
|
||||
export class PreprocessingStateError extends Error {
|
||||
constructor(readonly code: PreprocessingConflictCode, message: string) {
|
||||
super(message);
|
||||
this.name = "PreprocessingStateError";
|
||||
}
|
||||
}
|
||||
|
||||
export interface SessionInventoryRow {
|
||||
id: string;
|
||||
status: string;
|
||||
archived?: boolean;
|
||||
workspaceRevision?: string | null;
|
||||
}
|
||||
|
||||
export interface WriterLockLease {
|
||||
holderPid: number;
|
||||
release(): Promise<void>;
|
||||
}
|
||||
|
||||
export interface BeginPreprocessingJobOptions {
|
||||
operation: string;
|
||||
workspaceRevision: string;
|
||||
descriptorBlob: string;
|
||||
catalogBlob: string;
|
||||
configDigest: string;
|
||||
bindingDigest: string;
|
||||
runId?: string;
|
||||
}
|
||||
|
||||
export interface PreprocessingJobState {
|
||||
schemaVersion: 1;
|
||||
runId: string;
|
||||
operation: string;
|
||||
workspaceId: string;
|
||||
workspaceRevision: string;
|
||||
descriptorBlob: string;
|
||||
catalogBlob: string;
|
||||
configDigest: string;
|
||||
bindingDigest: string;
|
||||
completedStages: string[];
|
||||
childRuns: Record<string, string>;
|
||||
status: "active" | "succeeded" | "blocked" | "failed";
|
||||
candidateDigest?: string;
|
||||
reviewDigest?: string;
|
||||
}
|
||||
|
||||
export interface FkReviewRecord {
|
||||
reviewedCandidatesDigest: string;
|
||||
annotationsDigest: string;
|
||||
workspaceRevision: string;
|
||||
}
|
||||
|
||||
function sha256(value: string | Buffer): string {
|
||||
return `sha256:${createHash("sha256").update(value).digest("hex")}`;
|
||||
}
|
||||
|
||||
function syncDirectory(directory: string): void {
|
||||
if (process.platform === "win32") return;
|
||||
const fd = openSync(directory, "r");
|
||||
try { fsyncSync(fd); } finally { closeSync(fd); }
|
||||
}
|
||||
|
||||
function ensureDirectory(path: string): string {
|
||||
mkdirSync(path, { recursive: true, mode: 0o700 });
|
||||
const entry = lstatSync(path);
|
||||
if (!entry.isDirectory() || entry.isSymbolicLink()) {
|
||||
throw new Error("preprocessing state directory is unavailable");
|
||||
}
|
||||
return path;
|
||||
}
|
||||
|
||||
function validateRunId(runId: string): string {
|
||||
if (!/^[0-9a-f]{32}$/.test(runId)) throw new Error("preprocessing run id is invalid");
|
||||
return runId;
|
||||
}
|
||||
|
||||
function writeAtomicFile(path: string, contents: string, mode: number): void {
|
||||
ensureDirectory(join(path, ".."));
|
||||
const directory = path.slice(0, path.lastIndexOf("/"));
|
||||
ensureDirectory(directory);
|
||||
const staging = `${path}.tmp-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}`;
|
||||
const fd = openSync(
|
||||
staging,
|
||||
fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
let closed = false;
|
||||
try {
|
||||
writeFileSync(fd, contents, "utf8");
|
||||
fsyncSync(fd);
|
||||
fchmodSync(fd, mode);
|
||||
closeSync(fd);
|
||||
closed = true;
|
||||
renameSync(staging, path);
|
||||
syncDirectory(directory);
|
||||
} catch (error) {
|
||||
if (!closed) try { closeSync(fd); } catch { /* preserve original failure */ }
|
||||
try { unlinkSync(staging); } catch { /* best effort */ }
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function readTrustedFile(path: string): string {
|
||||
const entry = lstatSync(path);
|
||||
if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("preprocessing state file is invalid");
|
||||
const fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
|
||||
try {
|
||||
const before = fstatSync(fd);
|
||||
if (!before.isFile() || before.nlink !== 1) throw new Error("preprocessing state file is invalid");
|
||||
const contents = readFileSync(fd, "utf8");
|
||||
const after = fstatSync(fd);
|
||||
if (
|
||||
before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.nlink !== after.nlink
|
||||
) throw new Error("preprocessing state file changed while reading");
|
||||
return contents;
|
||||
} finally {
|
||||
closeSync(fd);
|
||||
}
|
||||
}
|
||||
|
||||
function decodeJob(value: unknown): PreprocessingJobState {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new Error("preprocessing job state is invalid");
|
||||
}
|
||||
const record = value as Record<string, unknown>;
|
||||
if (
|
||||
record.schemaVersion !== 1
|
||||
|| typeof record.runId !== "string"
|
||||
|| typeof record.operation !== "string"
|
||||
|| typeof record.workspaceId !== "string"
|
||||
|| typeof record.workspaceRevision !== "string"
|
||||
|| typeof record.descriptorBlob !== "string"
|
||||
|| typeof record.catalogBlob !== "string"
|
||||
|| typeof record.configDigest !== "string"
|
||||
|| typeof record.bindingDigest !== "string"
|
||||
|| !Array.isArray(record.completedStages)
|
||||
|| typeof record.childRuns !== "object" || record.childRuns === null || Array.isArray(record.childRuns)
|
||||
|| !["active", "succeeded", "blocked", "failed"].includes(String(record.status))
|
||||
) {
|
||||
throw new Error("preprocessing job state is invalid");
|
||||
}
|
||||
return record as unknown as PreprocessingJobState;
|
||||
}
|
||||
|
||||
function decodeReview(value: unknown): FkReviewRecord {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new Error("preprocessing review state is invalid");
|
||||
}
|
||||
const record = value as Record<string, unknown>;
|
||||
if (
|
||||
typeof record.reviewedCandidatesDigest !== "string"
|
||||
|| typeof record.annotationsDigest !== "string"
|
||||
|| typeof record.workspaceRevision !== "string"
|
||||
) throw new Error("preprocessing review state is invalid");
|
||||
return record as unknown as FkReviewRecord;
|
||||
}
|
||||
|
||||
export class PreprocessingStateStore {
|
||||
private readonly root: string;
|
||||
|
||||
constructor(private readonly options: { dataRoot: string; workspaceId: string }) {
|
||||
if (!/^[a-z][a-z0-9-]{2,62}$/.test(options.workspaceId)) {
|
||||
throw new Error("workspace id is invalid");
|
||||
}
|
||||
this.root = join(options.dataRoot, "sessions", options.workspaceId, "preprocessing");
|
||||
}
|
||||
|
||||
writerLockPath(): string { return join(this.root, "writer.lock"); }
|
||||
runtimeConfigDirectory(): string { return join(this.root, "runtime-config"); }
|
||||
runtimeConfigManifestDirectory(): string { return join(this.root, "runtime-config-manifests"); }
|
||||
jobsDirectory(): string { return join(this.root, "jobs"); }
|
||||
fkCandidatesDirectory(): string { return join(this.root, "fk-candidates"); }
|
||||
fkReviewsDirectory(): string { return join(this.root, "fk-reviews"); }
|
||||
jobPath(runId: string): string { return join(this.jobsDirectory(), `${validateRunId(runId)}.json`); }
|
||||
fkCandidatesPath(runId: string): string { return join(this.fkCandidatesDirectory(), `${validateRunId(runId)}.yaml`); }
|
||||
fkReviewPath(runId: string): string { return join(this.fkReviewsDirectory(), `${validateRunId(runId)}.json`); }
|
||||
|
||||
private ensureLayout(): void {
|
||||
ensureDirectory(this.root);
|
||||
for (const directory of [
|
||||
this.runtimeConfigDirectory(),
|
||||
this.runtimeConfigManifestDirectory(),
|
||||
this.jobsDirectory(),
|
||||
this.fkCandidatesDirectory(),
|
||||
this.fkReviewsDirectory(),
|
||||
]) ensureDirectory(directory);
|
||||
}
|
||||
|
||||
async acquireWriterLock(): Promise<WriterLockLease> {
|
||||
this.ensureLayout();
|
||||
const lockPath = this.writerLockPath();
|
||||
try {
|
||||
const entry = lstatSync(lockPath);
|
||||
if (!entry.isFile() || entry.isSymbolicLink()) throw new Error("invalid writer lock path");
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
|
||||
throw new PreprocessingStateError("preprocessing_conflict", "Workspace preprocessing lock is unavailable");
|
||||
}
|
||||
}
|
||||
const holder = spawn("python3", ["-c", PreprocessingStateStore.HOLDER_PROGRAM, lockPath], {
|
||||
stdio: ["pipe", "pipe", "pipe"],
|
||||
});
|
||||
await new Promise<void>((resolve, reject) => {
|
||||
let output = "";
|
||||
const fail = (error: Error) => {
|
||||
holder.stdout.removeAllListeners("data");
|
||||
reject(error);
|
||||
};
|
||||
holder.once("error", () => fail(new PreprocessingStateError(
|
||||
"preprocessing_conflict",
|
||||
"Workspace preprocessing lock is unavailable",
|
||||
)));
|
||||
holder.once("exit", (code) => {
|
||||
fail(new PreprocessingStateError(
|
||||
"preprocessing_conflict",
|
||||
code === 73 ? "Workspace preprocessing is busy" : "Workspace preprocessing lock is unavailable",
|
||||
));
|
||||
});
|
||||
holder.stdout.on("data", (chunk: Buffer) => {
|
||||
output += chunk.toString("utf8");
|
||||
if (output === "locked\n") {
|
||||
holder.stdout.removeAllListeners("data");
|
||||
resolve();
|
||||
}
|
||||
});
|
||||
});
|
||||
let released = false;
|
||||
return {
|
||||
holderPid: holder.pid ?? 0,
|
||||
release: async () => {
|
||||
if (released) return;
|
||||
released = true;
|
||||
if (!holder.stdin.destroyed) holder.stdin.end();
|
||||
await new Promise<void>((resolve) => holder.once("exit", () => resolve()));
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async beginJob(options: BeginPreprocessingJobOptions): Promise<PreprocessingJobState> {
|
||||
this.ensureLayout();
|
||||
if (!/^[0-9a-f]{40}$/.test(options.workspaceRevision)) {
|
||||
throw new Error("workspace revision is invalid");
|
||||
}
|
||||
const runId = options.runId ?? randomBytes(16).toString("hex");
|
||||
const path = this.jobPath(runId);
|
||||
try {
|
||||
const existing = this.readJob(runId);
|
||||
if (
|
||||
existing.operation !== options.operation
|
||||
|| existing.workspaceRevision !== options.workspaceRevision
|
||||
|| existing.descriptorBlob !== options.descriptorBlob
|
||||
|| existing.catalogBlob !== options.catalogBlob
|
||||
|| existing.configDigest !== options.configDigest
|
||||
|| existing.bindingDigest !== options.bindingDigest
|
||||
) {
|
||||
throw new PreprocessingStateError(
|
||||
"preprocessing_resume_mismatch",
|
||||
"Workspace preprocessing resume no longer matches the pinned revision",
|
||||
);
|
||||
}
|
||||
return existing;
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
|
||||
if (error instanceof PreprocessingStateError) throw error;
|
||||
if (options.runId) throw error;
|
||||
}
|
||||
}
|
||||
const job: PreprocessingJobState = {
|
||||
schemaVersion: 1,
|
||||
runId,
|
||||
operation: options.operation,
|
||||
workspaceId: this.options.workspaceId,
|
||||
workspaceRevision: options.workspaceRevision,
|
||||
descriptorBlob: options.descriptorBlob,
|
||||
catalogBlob: options.catalogBlob,
|
||||
configDigest: options.configDigest,
|
||||
bindingDigest: options.bindingDigest,
|
||||
completedStages: [],
|
||||
childRuns: {},
|
||||
status: "active",
|
||||
};
|
||||
writeAtomicFile(path, `${JSON.stringify(job)}
|
||||
`, 0o600);
|
||||
return job;
|
||||
}
|
||||
|
||||
readJob(runId: string): PreprocessingJobState {
|
||||
return decodeJob(JSON.parse(readTrustedFile(this.jobPath(runId))));
|
||||
}
|
||||
|
||||
writeJob(job: PreprocessingJobState): PreprocessingJobState {
|
||||
this.ensureLayout();
|
||||
writeAtomicFile(this.jobPath(job.runId), `${JSON.stringify(job)}
|
||||
`, 0o600);
|
||||
return job;
|
||||
}
|
||||
|
||||
writeFkCandidates(runId: string, yaml: string): { path: string; digest: string } {
|
||||
this.ensureLayout();
|
||||
const path = this.fkCandidatesPath(runId);
|
||||
writeAtomicFile(path, yaml, 0o600);
|
||||
return { path, digest: sha256(yaml) };
|
||||
}
|
||||
|
||||
readFkCandidates(runId: string): { path: string; yaml: string; digest: string } | undefined {
|
||||
const path = this.fkCandidatesPath(runId);
|
||||
try {
|
||||
const yaml = readTrustedFile(path);
|
||||
return { path, yaml, digest: sha256(yaml) };
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
writeFkReview(runId: string, review: FkReviewRecord): { path: string; digest: string } {
|
||||
this.ensureLayout();
|
||||
const path = this.fkReviewPath(runId);
|
||||
const json = `${JSON.stringify(review)}
|
||||
`;
|
||||
writeAtomicFile(path, json, 0o600);
|
||||
return { path, digest: sha256(json) };
|
||||
}
|
||||
|
||||
readFkReview(runId: string): FkReviewRecord | undefined {
|
||||
try {
|
||||
return decodeReview(JSON.parse(readTrustedFile(this.fkReviewPath(runId))));
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
async assertSessionInventoryCompatible(
|
||||
workspaceRevision: string,
|
||||
sessions: readonly SessionInventoryRow[],
|
||||
): Promise<void> {
|
||||
const conflicting = sessions.find((session) => (
|
||||
session.workspaceRevision
|
||||
&& session.workspaceRevision !== workspaceRevision
|
||||
&& session.status !== "finalized"
|
||||
&& !session.archived
|
||||
));
|
||||
if (conflicting) {
|
||||
throw new PreprocessingStateError(
|
||||
"preprocessing_conflict",
|
||||
"A resumable session is pinned to a different workspace revision",
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private static readonly HOLDER_PROGRAM = [
|
||||
"import fcntl, os, sys",
|
||||
"fd = os.open(sys.argv[1], os.O_RDWR | os.O_CREAT | getattr(os, 'O_NOFOLLOW', 0), 0o600)",
|
||||
"try:",
|
||||
" fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)",
|
||||
"except BlockingIOError:",
|
||||
" sys.exit(73)",
|
||||
"sys.stdout.write('locked\\n')",
|
||||
"sys.stdout.flush()",
|
||||
"sys.stdin.buffer.read()",
|
||||
].join("\n");
|
||||
}
|
||||
@@ -0,0 +1,522 @@
|
||||
import { createHash, randomUUID } from "node:crypto";
|
||||
import {
|
||||
closeSync,
|
||||
constants as fsConstants,
|
||||
fchmodSync,
|
||||
fstatSync,
|
||||
fsyncSync,
|
||||
lstatSync,
|
||||
mkdirSync,
|
||||
openSync,
|
||||
readFileSync,
|
||||
readSync,
|
||||
renameSync,
|
||||
statSync,
|
||||
unlinkSync,
|
||||
writeFileSync,
|
||||
} from "node:fs";
|
||||
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
|
||||
import { parse, parseAllDocuments, stringify } from "yaml";
|
||||
import { resolveRuntimeBindings, type RuntimeBindings } from "./bindings.js";
|
||||
import { GitWorkspaceRepository } from "./git-repository.js";
|
||||
import { WorkspaceRegistry } from "./registry.js";
|
||||
import {
|
||||
renderRuntimeConfig,
|
||||
type RuntimeIdentity,
|
||||
type RuntimeInstallationOverlay,
|
||||
type RuntimePaths,
|
||||
type RuntimeRenderContext,
|
||||
type SemanticRuntimeConfig,
|
||||
} from "./runtime-renderer.js";
|
||||
import { parseWorkspaceYaml, validateOperationalWorkspace, type WorkspaceDescriptor } from "./schema.js";
|
||||
import type { WorkspaceRegistryConfig } from "./types.js";
|
||||
|
||||
export interface RuntimeConfigLease {
|
||||
path: string;
|
||||
workspaceId: string;
|
||||
workspaceRevision: string;
|
||||
release(): void;
|
||||
}
|
||||
|
||||
export interface RenderedWorkspaceRuntime {
|
||||
workspace: WorkspaceDescriptor;
|
||||
workspaceId: string;
|
||||
workspaceRevision: string;
|
||||
revisionContentRoot: string;
|
||||
runtimePaths: RuntimePaths;
|
||||
installationOverlay: RuntimeInstallationOverlay;
|
||||
bindings: RuntimeBindings;
|
||||
bindingDigest: string;
|
||||
renderedConfig: string;
|
||||
}
|
||||
|
||||
export interface ActiveRenderedWorkspaceRuntime extends RenderedWorkspaceRuntime {
|
||||
snapshotPath: string;
|
||||
descriptorBlob: string;
|
||||
catalogBlob: string;
|
||||
}
|
||||
|
||||
export interface DeterministicRuntimeConfigLease extends RuntimeConfigLease {
|
||||
manifestPath: string;
|
||||
descriptorBlob: string;
|
||||
catalogBlob: string;
|
||||
configDigest: string;
|
||||
bindingDigest: string;
|
||||
}
|
||||
|
||||
export class RuntimeConfigLeaseError extends Error {
|
||||
constructor(readonly code: "effective_config_mismatch", message: string) {
|
||||
super(message);
|
||||
this.name = "RuntimeConfigLeaseError";
|
||||
}
|
||||
}
|
||||
|
||||
interface SnapshotIdentity extends RuntimeIdentity {
|
||||
snapshotPath: string;
|
||||
}
|
||||
|
||||
interface PublishedRuntimeConfigManifest {
|
||||
schemaVersion: 1;
|
||||
workspaceId: string;
|
||||
workspaceRevision: string;
|
||||
descriptorBlob: string;
|
||||
catalogBlob: string;
|
||||
configDigest: string;
|
||||
bindingDigest: string;
|
||||
path: string;
|
||||
file: {
|
||||
dev: number;
|
||||
ino: number;
|
||||
size: number;
|
||||
mode: number;
|
||||
nlink: number;
|
||||
};
|
||||
}
|
||||
|
||||
function sha256(value: string | Buffer): string {
|
||||
return `sha256:${createHash("sha256").update(value).digest("hex")}`;
|
||||
}
|
||||
|
||||
function stableBindingDigest(bindings: RuntimeBindings): string {
|
||||
const encodeRecord = (value: Record<string, string>) => Object.entries(value).sort(([left], [right]) => (
|
||||
left.localeCompare(right)
|
||||
));
|
||||
return sha256(JSON.stringify({
|
||||
dwh: {
|
||||
transport: bindings.dwh.transport,
|
||||
values: encodeRecord(bindings.dwh.values),
|
||||
missing: [...bindings.dwh.missing].sort(),
|
||||
},
|
||||
evidence: {
|
||||
values: encodeRecord(bindings.evidence.values),
|
||||
missing: [...bindings.evidence.missing].sort(),
|
||||
},
|
||||
}));
|
||||
}
|
||||
|
||||
function syncDirectory(directory: string): void {
|
||||
if (process.platform === "win32") return;
|
||||
const fd = openSync(directory, "r");
|
||||
try { fsyncSync(fd); } finally { closeSync(fd); }
|
||||
}
|
||||
|
||||
function ensureTrustedDirectory(directory: string): string {
|
||||
mkdirSync(directory, { recursive: true, mode: 0o700 });
|
||||
const entry = lstatSync(directory);
|
||||
if (!entry.isDirectory() || entry.isSymbolicLink()) {
|
||||
throw new Error("runtime configuration directory is unavailable");
|
||||
}
|
||||
return directory;
|
||||
}
|
||||
|
||||
function writeAtomicFile(path: string, contents: string, mode: number): void {
|
||||
ensureTrustedDirectory(dirname(path));
|
||||
const staging = `${path}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
|
||||
const fd = openSync(
|
||||
staging,
|
||||
fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW,
|
||||
0o600,
|
||||
);
|
||||
let closed = false;
|
||||
try {
|
||||
writeFileSync(fd, contents, "utf8");
|
||||
fsyncSync(fd);
|
||||
fchmodSync(fd, mode);
|
||||
closeSync(fd);
|
||||
closed = true;
|
||||
renameSync(staging, path);
|
||||
syncDirectory(dirname(path));
|
||||
} catch (error) {
|
||||
if (!closed) try { closeSync(fd); } catch { /* preserve original error */ }
|
||||
try { unlinkSync(staging); } catch { /* best effort */ }
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function readTrustedFile(path: string): { contents: string; stat: ReturnType<typeof statSync> } {
|
||||
const entry = lstatSync(path);
|
||||
if (!entry.isFile() || entry.isSymbolicLink()) {
|
||||
throw new Error("runtime configuration file is untrusted");
|
||||
}
|
||||
const fd = openSync(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
|
||||
try {
|
||||
const before = fstatSync(fd);
|
||||
if (!before.isFile() || before.nlink !== 1) {
|
||||
throw new Error("runtime configuration file is untrusted");
|
||||
}
|
||||
const contents = readFileSync(fd, "utf8");
|
||||
const after = fstatSync(fd);
|
||||
if (
|
||||
before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.nlink !== after.nlink
|
||||
) {
|
||||
throw new Error("runtime configuration file changed while reading");
|
||||
}
|
||||
return { contents, stat: statSync(path) };
|
||||
} finally {
|
||||
closeSync(fd);
|
||||
}
|
||||
}
|
||||
|
||||
function readStrictJson(path: string): unknown {
|
||||
return JSON.parse(readTrustedFile(path).contents);
|
||||
}
|
||||
|
||||
function trustedSnapshotIdentity(snapshotPath: string): SnapshotIdentity {
|
||||
if (!isAbsolute(snapshotPath)) throw new Error("config path is not a trusted runtime snapshot");
|
||||
const commitDirectory = dirname(snapshotPath);
|
||||
const snapshotsRoot = dirname(commitDirectory);
|
||||
const pathRelative = relative(snapshotsRoot, snapshotPath);
|
||||
const match = /^([0-9a-f]{40})\/([a-z][a-z0-9-]{2,62})\.yaml$/.exec(pathRelative);
|
||||
if (pathRelative.startsWith("..") || isAbsolute(pathRelative) || !match) {
|
||||
throw new Error("config path is not a trusted runtime snapshot");
|
||||
}
|
||||
const entry = lstatSync(snapshotPath);
|
||||
if (!entry.isFile() || entry.isSymbolicLink()) {
|
||||
throw new Error("config path is not a trusted runtime snapshot");
|
||||
}
|
||||
return { snapshotPath, workspaceRevision: match[1], workspaceId: match[2] };
|
||||
}
|
||||
|
||||
function readSnapshotWorkspace(snapshotPath: string): {
|
||||
workspace: WorkspaceDescriptor;
|
||||
identity: SnapshotIdentity;
|
||||
revisionContentRoot: string;
|
||||
} {
|
||||
const identity = trustedSnapshotIdentity(snapshotPath);
|
||||
const fd = openSync(snapshotPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
|
||||
try {
|
||||
const before = fstatSync(fd);
|
||||
if (!before.isFile() || before.nlink !== 1) throw new Error("workspace snapshot is not a file");
|
||||
const source = readFileSync(fd, "utf8");
|
||||
const after = fstatSync(fd);
|
||||
if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size) {
|
||||
throw new Error("workspace snapshot changed while reading");
|
||||
}
|
||||
const workspace = validateOperationalWorkspace(parseWorkspaceYaml(source));
|
||||
if (workspace.workspace.id !== identity.workspaceId) {
|
||||
throw new Error("workspace snapshot identity does not match its path");
|
||||
}
|
||||
return { workspace, identity, revisionContentRoot: dirname(snapshotPath) };
|
||||
} finally {
|
||||
closeSync(fd);
|
||||
}
|
||||
}
|
||||
|
||||
function runtimePaths(dataRoot: string, workspaceId: string): RuntimePaths {
|
||||
if (!isAbsolute(dataRoot)) throw new Error("registry workspace runtime requires an absolute data root");
|
||||
const root = join(dataRoot, "sessions", workspaceId);
|
||||
return {
|
||||
sessions: join(root, "sessions"),
|
||||
artifacts: join(root, "artifacts"),
|
||||
indexes: join(root, "indexes"),
|
||||
};
|
||||
}
|
||||
|
||||
function installationOverlay(harnessDir: string, configPath: string): RuntimeInstallationOverlay {
|
||||
const path = isAbsolute(configPath) ? configPath : resolve(harnessDir, configPath);
|
||||
try {
|
||||
const documents = parseAllDocuments(readFileSync(path, "utf8"), { uniqueKeys: true });
|
||||
if (documents.length !== 1) throw new Error("installation config must contain one YAML document");
|
||||
const document = documents[0];
|
||||
if (document.errors.length > 0 || document.warnings.length > 0) {
|
||||
throw new Error("installation config contains invalid YAML");
|
||||
}
|
||||
const parsed = document.toJSON();
|
||||
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
|
||||
throw new Error("installation config must be a YAML mapping");
|
||||
}
|
||||
const source = parsed as Record<string, unknown>;
|
||||
return {
|
||||
...(source.session_storage === undefined ? {} : { session_storage: source.session_storage }),
|
||||
...(source.profile === undefined ? {} : { profile: source.profile }),
|
||||
};
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
function applyCollectionLifecycle(config: string, lifecycle: "require_existing"): string {
|
||||
const parsed = parse(config) as Record<string, any>;
|
||||
if (!parsed.resources || typeof parsed.resources !== "object") {
|
||||
throw new Error("runtime configuration is missing resources");
|
||||
}
|
||||
parsed.resources = { ...parsed.resources };
|
||||
parsed.resources.vector = { ...(parsed.resources.vector ?? {}), collection_lifecycle: lifecycle };
|
||||
return stringify(parsed, { lineWidth: 0, sortMapEntries: false });
|
||||
}
|
||||
|
||||
function renderWorkspaceRuntimeFromWorkspace(options: {
|
||||
workspace: WorkspaceDescriptor;
|
||||
workspaceId: string;
|
||||
workspaceRevision: string;
|
||||
revisionContentRoot: string;
|
||||
harnessDir: string;
|
||||
configPath: string;
|
||||
dataRoot: string;
|
||||
secretRoots: readonly string[];
|
||||
semanticRuntime: SemanticRuntimeConfig;
|
||||
}): RenderedWorkspaceRuntime {
|
||||
const bindings = resolveRuntimeBindings(options.workspace, process.env, options.secretRoots);
|
||||
const overlay = installationOverlay(options.harnessDir, options.configPath);
|
||||
const context: RuntimeRenderContext = {
|
||||
workspaceId: options.workspaceId,
|
||||
workspaceRevision: options.workspaceRevision,
|
||||
revisionContentRoot: options.revisionContentRoot,
|
||||
};
|
||||
return {
|
||||
workspace: options.workspace,
|
||||
workspaceId: options.workspaceId,
|
||||
workspaceRevision: options.workspaceRevision,
|
||||
revisionContentRoot: options.revisionContentRoot,
|
||||
runtimePaths: runtimePaths(options.dataRoot, options.workspaceId),
|
||||
installationOverlay: overlay,
|
||||
bindings,
|
||||
bindingDigest: stableBindingDigest(bindings),
|
||||
renderedConfig: renderRuntimeConfig(
|
||||
options.workspace,
|
||||
bindings,
|
||||
runtimePaths(options.dataRoot, options.workspaceId),
|
||||
context,
|
||||
overlay,
|
||||
options.semanticRuntime,
|
||||
),
|
||||
};
|
||||
}
|
||||
|
||||
export function renderWorkspaceRuntimeFromSnapshotPath(options: {
|
||||
snapshotPath: string;
|
||||
harnessDir: string;
|
||||
configPath: string;
|
||||
dataRoot: string;
|
||||
secretRoots: readonly string[];
|
||||
semanticRuntime: SemanticRuntimeConfig;
|
||||
}): RenderedWorkspaceRuntime {
|
||||
const snapshot = readSnapshotWorkspace(options.snapshotPath);
|
||||
return renderWorkspaceRuntimeFromWorkspace({
|
||||
workspace: snapshot.workspace,
|
||||
workspaceId: snapshot.identity.workspaceId,
|
||||
workspaceRevision: snapshot.identity.workspaceRevision,
|
||||
revisionContentRoot: snapshot.revisionContentRoot,
|
||||
harnessDir: options.harnessDir,
|
||||
configPath: options.configPath,
|
||||
dataRoot: options.dataRoot,
|
||||
secretRoots: options.secretRoots,
|
||||
semanticRuntime: options.semanticRuntime,
|
||||
});
|
||||
}
|
||||
|
||||
export async function renderActiveWorkspaceRuntime(options: {
|
||||
workspaceId: string;
|
||||
registry: WorkspaceRegistry;
|
||||
registryConfig: WorkspaceRegistryConfig;
|
||||
harnessDir: string;
|
||||
configPath: string;
|
||||
dataRoot: string;
|
||||
secretRoots: readonly string[];
|
||||
semanticRuntime: SemanticRuntimeConfig;
|
||||
}): Promise<ActiveRenderedWorkspaceRuntime> {
|
||||
const { workspace, revision } = await options.registry.read(options.workspaceId);
|
||||
const repository = new GitWorkspaceRepository(options.registryConfig);
|
||||
await repository.ensureLayout();
|
||||
const rendered = renderWorkspaceRuntimeFromWorkspace({
|
||||
workspace,
|
||||
workspaceId: revision.id,
|
||||
workspaceRevision: revision.commit,
|
||||
revisionContentRoot: dirname(revision.snapshotPath),
|
||||
harnessDir: options.harnessDir,
|
||||
configPath: options.configPath,
|
||||
dataRoot: options.dataRoot,
|
||||
secretRoots: options.secretRoots,
|
||||
semanticRuntime: options.semanticRuntime,
|
||||
});
|
||||
return {
|
||||
...rendered,
|
||||
snapshotPath: revision.snapshotPath,
|
||||
descriptorBlob: revision.blob,
|
||||
catalogBlob: (await repository.catalogBlob(revision.commit)).trim(),
|
||||
};
|
||||
}
|
||||
|
||||
function decodePublishedRuntimeConfigManifest(value: unknown): PublishedRuntimeConfigManifest {
|
||||
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration manifest is invalid");
|
||||
}
|
||||
const manifest = value as Record<string, unknown>;
|
||||
const file = manifest.file as Record<string, unknown> | undefined;
|
||||
if (
|
||||
manifest.schemaVersion !== 1
|
||||
|| typeof manifest.workspaceId !== "string"
|
||||
|| typeof manifest.workspaceRevision !== "string"
|
||||
|| typeof manifest.descriptorBlob !== "string"
|
||||
|| typeof manifest.catalogBlob !== "string"
|
||||
|| typeof manifest.configDigest !== "string"
|
||||
|| typeof manifest.bindingDigest !== "string"
|
||||
|| typeof manifest.path !== "string"
|
||||
|| !file
|
||||
|| typeof file.dev !== "number"
|
||||
|| typeof file.ino !== "number"
|
||||
|| typeof file.size !== "number"
|
||||
|| typeof file.mode !== "number"
|
||||
|| typeof file.nlink !== "number"
|
||||
) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration manifest is invalid");
|
||||
}
|
||||
return manifest as unknown as PublishedRuntimeConfigManifest;
|
||||
}
|
||||
|
||||
export async function publishDeterministicRuntimeConfigLease(options: {
|
||||
workspaceId: string;
|
||||
registry: WorkspaceRegistry;
|
||||
registryConfig: WorkspaceRegistryConfig;
|
||||
harnessDir: string;
|
||||
configPath: string;
|
||||
dataRoot: string;
|
||||
secretRoots: readonly string[];
|
||||
semanticRuntime: SemanticRuntimeConfig;
|
||||
}): Promise<DeterministicRuntimeConfigLease> {
|
||||
const rendered = await renderActiveWorkspaceRuntime(options);
|
||||
const publishedConfig = applyCollectionLifecycle(rendered.renderedConfig, "require_existing");
|
||||
const preprocessingRoot = ensureTrustedDirectory(join(
|
||||
options.dataRoot,
|
||||
"sessions",
|
||||
rendered.workspaceId,
|
||||
"preprocessing",
|
||||
));
|
||||
const configDirectory = ensureTrustedDirectory(join(preprocessingRoot, "runtime-config"));
|
||||
const manifestDirectory = ensureTrustedDirectory(join(preprocessingRoot, "runtime-config-manifests"));
|
||||
const path = join(configDirectory, `${rendered.workspaceRevision}.yaml`);
|
||||
const manifestPath = join(manifestDirectory, `${rendered.workspaceRevision}.json`);
|
||||
const configDigest = sha256(publishedConfig);
|
||||
|
||||
const verifyPublished = (): PublishedRuntimeConfigManifest | undefined => {
|
||||
let manifest: PublishedRuntimeConfigManifest | undefined;
|
||||
try {
|
||||
manifest = decodePublishedRuntimeConfigManifest(readStrictJson(manifestPath));
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
|
||||
}
|
||||
let configStat: ReturnType<typeof statSync> | undefined;
|
||||
let contents: string | undefined;
|
||||
try {
|
||||
const file = readTrustedFile(path);
|
||||
contents = file.contents;
|
||||
configStat = file.stat;
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
|
||||
}
|
||||
if (contents === undefined) return manifest;
|
||||
if ((Number(configStat!.mode) & 0o777) !== 0o400 || configStat!.nlink !== 1) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration lease changed");
|
||||
}
|
||||
if (sha256(contents) !== configDigest) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration lease changed");
|
||||
}
|
||||
if (!manifest) return undefined;
|
||||
if (
|
||||
manifest.workspaceId !== rendered.workspaceId
|
||||
|| manifest.workspaceRevision !== rendered.workspaceRevision
|
||||
|| manifest.descriptorBlob !== rendered.descriptorBlob
|
||||
|| manifest.catalogBlob !== rendered.catalogBlob
|
||||
|| manifest.configDigest !== configDigest
|
||||
|| manifest.bindingDigest !== rendered.bindingDigest
|
||||
|| manifest.path !== path
|
||||
|| manifest.file.dev !== configStat!.dev
|
||||
|| manifest.file.ino !== configStat!.ino
|
||||
|| manifest.file.size !== configStat!.size
|
||||
|| manifest.file.mode !== (Number(configStat!.mode) & 0o777)
|
||||
|| manifest.file.nlink !== configStat!.nlink
|
||||
) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration lease changed");
|
||||
}
|
||||
return manifest;
|
||||
};
|
||||
|
||||
const existing = verifyPublished();
|
||||
if (existing) {
|
||||
return {
|
||||
path,
|
||||
manifestPath,
|
||||
workspaceId: rendered.workspaceId,
|
||||
workspaceRevision: rendered.workspaceRevision,
|
||||
descriptorBlob: rendered.descriptorBlob,
|
||||
catalogBlob: rendered.catalogBlob,
|
||||
configDigest,
|
||||
bindingDigest: rendered.bindingDigest,
|
||||
release: () => undefined,
|
||||
};
|
||||
}
|
||||
|
||||
try {
|
||||
readTrustedFile(path);
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") {
|
||||
writeAtomicFile(path, publishedConfig, 0o400);
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
const published = readTrustedFile(path);
|
||||
const publishedStat = published.stat!;
|
||||
if (sha256(published.contents) !== configDigest) {
|
||||
throw new RuntimeConfigLeaseError("effective_config_mismatch", "runtime configuration lease changed");
|
||||
}
|
||||
const manifest: PublishedRuntimeConfigManifest = {
|
||||
schemaVersion: 1,
|
||||
workspaceId: rendered.workspaceId,
|
||||
workspaceRevision: rendered.workspaceRevision,
|
||||
descriptorBlob: rendered.descriptorBlob,
|
||||
catalogBlob: rendered.catalogBlob,
|
||||
configDigest,
|
||||
bindingDigest: rendered.bindingDigest,
|
||||
path,
|
||||
file: {
|
||||
dev: Number(publishedStat.dev),
|
||||
ino: Number(publishedStat.ino),
|
||||
size: Number(publishedStat.size),
|
||||
mode: Number(publishedStat.mode) & 0o777,
|
||||
nlink: Number(publishedStat.nlink),
|
||||
},
|
||||
};
|
||||
try {
|
||||
readStrictJson(manifestPath);
|
||||
} catch (error) {
|
||||
if ((error as NodeJS.ErrnoException).code === "ENOENT") {
|
||||
writeAtomicFile(manifestPath, `${JSON.stringify(manifest)}\n`, 0o600);
|
||||
} else {
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
verifyPublished();
|
||||
return {
|
||||
path,
|
||||
manifestPath,
|
||||
workspaceId: rendered.workspaceId,
|
||||
workspaceRevision: rendered.workspaceRevision,
|
||||
descriptorBlob: rendered.descriptorBlob,
|
||||
catalogBlob: rendered.catalogBlob,
|
||||
configDigest,
|
||||
bindingDigest: rendered.bindingDigest,
|
||||
release: () => undefined,
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user