@prismatic-io/lux 0.0.1

package/src/orchestrator/authored-dependencies.ts

@@ -0,0 +1,193 @@
+import { lstat, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseSync, visitorKeys } from "oxc-parser";
+import { contentHash, valueHash } from "../core/index.js";
+
+const isIdentityStableBareSpecifier = (specifier: string): boolean =>
+  specifier.startsWith("node:") ||
+  specifier === "@prismatic-io/lux" ||
+  specifier.startsWith("@prismatic-io/lux/");
+
+const EXCLUDED_IDENTITY_DIRECTORIES = new Set([".git", ".lux-runs", "dist", "lib", "node_modules"]);
+
+const authoredModuleSpecifiers = (path: string, source: string): string[] => {
+  const parsed = parseSync(path, source, {
+    sourceType: "module",
+    astType: "ts",
+    preserveParens: true,
+    showSemanticErrors: true,
+  });
+  const parseError = parsed.errors.find((error) => error.severity === "Error");
+  if (parseError) {
+    throw new Error(`authored evaluation code failed to parse: ${path}: ${parseError.message}`);
+  }
+  const specifiers: string[] = [];
+  const visit = (node: unknown): void => {
+    if (!node || typeof node !== "object" || Array.isArray(node)) return;
+    const record = node as Record<string, unknown>;
+    const type = typeof record.type === "string" ? record.type : "";
+    if (
+      type === "ImportDeclaration" ||
+      type === "ExportNamedDeclaration" ||
+      type === "ExportAllDeclaration"
+    ) {
+      const sourceNode = record.source as { value?: unknown } | null | undefined;
+      if (sourceNode && typeof sourceNode.value === "string") specifiers.push(sourceNode.value);
+    }
+    if (type === "ImportExpression") {
+      const sourceNode = record.source as { type?: unknown; value?: unknown } | undefined;
+      if (sourceNode?.type !== "Literal" || typeof sourceNode.value !== "string") {
+        throw new Error(
+          `authored evaluation code cannot use a non-literal dynamic import: ${path}`,
+        );
+      }
+      specifiers.push(sourceNode.value);
+    }
+    for (const key of visitorKeys[type] ?? []) {
+      const child = record[key];
+      if (Array.isArray(child)) {
+        for (const item of child) visit(item);
+      } else {
+        visit(child);
+      }
+    }
+  };
+  visit(parsed.program);
+  return specifiers;
+};
+
+const isOutsideRoot = (fromRoot: string): boolean =>
+  fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot);
+
+const assertIdentityPathContained = (
+  absoluteRoot: string,
+  absolutePath: string,
+  kind: "entrypoint" | "import",
+  detail: string,
+): string => {
+  const fromRoot = relative(absoluteRoot, absolutePath);
+  if (isOutsideRoot(fromRoot)) {
+    throw new Error(`authored evaluation ${kind} escapes config root: ${detail}`);
+  }
+  if (fromRoot.split(sep).some((component) => EXCLUDED_IDENTITY_DIRECTORIES.has(component))) {
+    throw new Error(`authored evaluation ${kind} enters an identity-excluded directory: ${detail}`);
+  }
+  return fromRoot;
+};
+
+const resolveAuthoredImport = async (
+  absoluteRoot: string,
+  canonicalRoot: string,
+  importer: string,
+  specifier: string,
+): Promise<string> => {
+  let unresolved: string;
+  try {
+    const importerUrl = pathToFileURL(join(absoluteRoot, importer));
+    unresolved = resolve(fileURLToPath(new URL(specifier, importerUrl)));
+  } catch {
+    throw new Error(`authored evaluation code has an invalid file import: ${importer}`);
+  }
+  assertIdentityPathContained(absoluteRoot, unresolved, "import", `${importer} -> ${specifier}`);
+
+  let info: Awaited<ReturnType<typeof lstat>>;
+  try {
+    info = await lstat(unresolved);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`authored evaluation import cannot be resolved: ${importer} -> ${specifier}`);
+    }
+    throw error;
+  }
+  const fromRoot = assertIdentityPathContained(
+    absoluteRoot,
+    unresolved,
+    "import",
+    `${importer} -> ${specifier}`,
+  );
+  if (info.isSymbolicLink() || !info.isFile()) {
+    throw new Error(
+      `authored evaluation import must resolve to a regular, non-symlink file: ${importer} -> ${specifier}`,
+    );
+  }
+  if ((await realpath(unresolved)) !== resolve(canonicalRoot, fromRoot)) {
+    throw new Error(
+      `authored evaluation import path must not contain symlinks: ${importer} -> ${specifier}`,
+    );
+  }
+  return fromRoot;
+};
+
+/**
+ * Authored callbacks are trusted code. This walk accounts for bytes visible
+ * through static ESM without implying that an identifier blacklist is a
+ * JavaScript security sandbox.
+ */
+const authoredDependencyGraph = async (
+  root: string,
+  entryPaths: readonly string[],
+): Promise<string[]> => {
+  const absoluteRoot = resolve(root);
+  const canonicalRoot = await realpath(absoluteRoot);
+  const pending = [...new Set(entryPaths)];
+  const visited = new Set<string>();
+  while (pending.length > 0) {
+    const entry = pending.pop();
+    if (!entry) continue;
+    const absolutePath = resolve(absoluteRoot, entry);
+    const path = assertIdentityPathContained(
+      absoluteRoot,
+      absolutePath,
+      "entrypoint",
+      `'${entry}'`,
+    );
+    if (visited.has(path)) continue;
+    const info = await lstat(absolutePath);
+    if (info.isSymbolicLink() || !info.isFile()) {
+      throw new Error(
+        `authored evaluation entrypoint must be a regular, non-symlink file: ${path}`,
+      );
+    }
+    if ((await realpath(absolutePath)) !== resolve(canonicalRoot, path)) {
+      throw new Error(`authored evaluation entrypoint path must not contain symlinks: ${path}`);
+    }
+    visited.add(path);
+    if (!/\.[cm]?[jt]sx?$/i.test(path)) continue;
+    const rawSource = await readFile(absolutePath, "utf8");
+    for (const specifier of authoredModuleSpecifiers(path, rawSource)) {
+      if (!specifier.startsWith(".") && !isAbsolute(specifier) && !specifier.startsWith("file:")) {
+        if (!isIdentityStableBareSpecifier(specifier)) {
+          throw new Error(
+            `authored evaluation code cannot import mutable bare package '${specifier}': ${path}`,
+          );
+        }
+        continue;
+      }
+      pending.push(await resolveAuthoredImport(absoluteRoot, canonicalRoot, path, specifier));
+    }
+  }
+  return [...visited].sort();
+};
+
+export const assertAuthoredImportsContained = async (
+  root: string,
+  entryPaths: readonly string[],
+): Promise<void> => {
+  await authoredDependencyGraph(root, entryPaths);
+};
+
+export const authoredDependencyGraphHash = async (
+  root: string,
+  entryPaths: readonly string[],
+): Promise<string> => {
+  const absoluteRoot = resolve(root);
+  return valueHash(
+    await Promise.all(
+      (await authoredDependencyGraph(absoluteRoot, entryPaths)).map(async (path) => ({
+        path,
+        hash: contentHash(await readFile(join(absoluteRoot, path))),
+      })),
+    ),
+  );
+};

package/src/orchestrator/campaign-lifecycle.ts

@@ -0,0 +1,181 @@
+import { assign, createActor, fromPromise, setup, toPromise } from "xstate";
+
+export type CampaignLifecycleEffects<Work, Result> = {
+  prepare: () => Promise<void>;
+  execute: () => Promise<Work>;
+  complete: (work: Work) => Promise<Result>;
+  resultStatus: (result: Result) => "passed" | "failed";
+  failureStatus: (error: unknown) => "failed" | "aborted";
+  recordFailure: (status: "failed" | "aborted", error: unknown) => Promise<void>;
+  close: (primaryError: unknown | null) => Promise<void>;
+};
+
+type ErasedEffects = CampaignLifecycleEffects<unknown, unknown>;
+type CampaignLifecycleContext = {
+  effects: ErasedEffects;
+  work: unknown;
+  result: unknown;
+  error: unknown;
+  terminalStatus: "passed" | "failed" | "aborted" | undefined;
+};
+type CampaignLifecycleOutcome =
+  | { status: "passed" | "failedResult"; result: unknown }
+  | { status: "failed"; error: unknown }
+  | { status: "aborted"; error: unknown };
+
+const invokeEffect = (effect: (effects: ErasedEffects) => Promise<unknown>) =>
+  fromPromise<unknown, ErasedEffects>(({ input }) => effect(input));
+
+const campaignLifecycleMachine = setup({
+  types: {
+    context: {} as CampaignLifecycleContext,
+    input: {} as { effects: ErasedEffects },
+    output: {} as CampaignLifecycleOutcome,
+  },
+  actors: {
+    prepare: invokeEffect((effects) => effects.prepare()),
+    execute: invokeEffect((effects) => effects.execute()),
+    complete: fromPromise<unknown, { effects: ErasedEffects; work: unknown }>(({ input }) =>
+      input.effects.complete(input.work),
+    ),
+    recordFailure: fromPromise<
+      void,
+      { effects: ErasedEffects; status: "failed" | "aborted"; error: unknown }
+    >(({ input }) => input.effects.recordFailure(input.status, input.error)),
+    closeSuccess: invokeEffect((effects) => effects.close(null)),
+    closeFailure: fromPromise<void, { effects: ErasedEffects; error: unknown }>(({ input }) =>
+      input.effects.close(input.error),
+    ),
+  },
+  actions: {
+    captureWork: assign({
+      work: ({ event }) => ("output" in event ? event.output : undefined),
+    }),
+    captureResult: assign({
+      result: ({ event }) => ("output" in event ? event.output : undefined),
+      terminalStatus: ({ context, event }) =>
+        "output" in event ? context.effects.resultStatus(event.output) : "failed",
+    }),
+    captureError: assign({
+      error: ({ event }) =>
+        "error" in event ? event.error : new Error("campaign lifecycle failed"),
+      terminalStatus: ({ context, event }) =>
+        context.effects.failureStatus(
+          "error" in event ? event.error : new Error("campaign lifecycle failed"),
+        ),
+    }),
+    captureReleaseError: assign({
+      error: ({ event }) => ("error" in event ? event.error : new Error("campaign release failed")),
+      terminalStatus: "failed",
+    }),
+  },
+}).createMachine({
+  id: "lux-campaign",
+  context: ({ input }) => ({
+    effects: input.effects,
+    work: undefined,
+    result: undefined,
+    error: undefined,
+    terminalStatus: undefined,
+  }),
+  initial: "preparing",
+  states: {
+    preparing: {
+      invoke: {
+        src: "prepare",
+        input: ({ context }) => context.effects,
+        onDone: { target: "executing" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    executing: {
+      invoke: {
+        src: "execute",
+        input: ({ context }) => context.effects,
+        onDone: { target: "recordingSuccess", actions: "captureWork" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    recordingSuccess: {
+      invoke: {
+        src: "complete",
+        input: ({ context }) => ({ effects: context.effects, work: context.work }),
+        onDone: { target: "closingResult", actions: "captureResult" },
+        onError: { target: "recordingFailure", actions: "captureError" },
+      },
+    },
+    recordingFailure: {
+      invoke: {
+        src: "recordFailure",
+        input: ({ context }) => ({
+          effects: context.effects,
+          status: context.terminalStatus === "aborted" ? "aborted" : "failed",
+          error: context.error,
+        }),
+        onDone: { target: "closingFailure" },
+        // Preserve the campaign's primary error when terminal persistence fails.
+        onError: { target: "closingFailure" },
+      },
+    },
+    closingResult: {
+      invoke: {
+        src: "closeSuccess",
+        input: ({ context }) => context.effects,
+        onDone: [
+          { guard: ({ context }) => context.terminalStatus === "passed", target: "passed" },
+          { target: "failedResult" },
+        ],
+        onError: { target: "recordingFailure", actions: "captureReleaseError" },
+      },
+    },
+    closingFailure: {
+      invoke: {
+        src: "closeFailure",
+        input: ({ context }) => ({ effects: context.effects, error: context.error }),
+        onDone: [
+          { guard: ({ context }) => context.terminalStatus === "aborted", target: "aborted" },
+          { target: "failed" },
+        ],
+        onError: { target: "failed" },
+      },
+    },
+    passed: { type: "final" },
+    failedResult: { type: "final" },
+    aborted: { type: "final" },
+    failed: { type: "final" },
+  },
+  output: ({ context }) => {
+    if (context.error !== undefined) {
+      return {
+        status: context.terminalStatus === "aborted" ? "aborted" : "failed",
+        error: context.error,
+      };
+    }
+    return {
+      status: context.terminalStatus === "passed" ? "passed" : "failedResult",
+      result: context.result,
+    };
+  },
+});
+
+export const executeCampaignLifecycle = async <Work, Result>(
+  effects: CampaignLifecycleEffects<Work, Result>,
+): Promise<Result> => {
+  const erased: ErasedEffects = {
+    prepare: () => effects.prepare(),
+    execute: () => effects.execute(),
+    complete: (work) => effects.complete(work as Work),
+    resultStatus: (result) => effects.resultStatus(result as Result),
+    failureStatus: (error) => effects.failureStatus(error),
+    recordFailure: (status, error) => effects.recordFailure(status, error),
+    close: (primaryError) => effects.close(primaryError),
+  };
+  const actor = createActor(campaignLifecycleMachine, { input: { effects: erased } });
+  actor.start();
+  const outcome = await toPromise(actor);
+  if (outcome.status === "failed" || outcome.status === "aborted") throw outcome.error;
+  return outcome.result as Result;
+};
+
+// Internal export for transition-level tests.
+export { campaignLifecycleMachine };

package/src/orchestrator/candidate-integrity.ts

@@ -0,0 +1,18 @@
+import { type Candidate, CandidateSchema, valueHash } from "../core/index.js";
+
+export const candidateEnvelopeHash = (candidate: Candidate): string => valueHash(candidate);
+
+export const assertCandidateEnvelopeIntegrity = (candidate: unknown): Candidate => {
+  const verified = CandidateSchema.parse(candidate);
+  if (valueHash(verified.components) !== verified.candidateHash) {
+    throw new Error("candidate contents do not match candidateHash");
+  }
+  const sourceBytes = Object.values(verified.components).reduce(
+    (total, content) => total + Buffer.byteLength(content),
+    0,
+  );
+  if (sourceBytes !== verified.sourceBytes) {
+    throw new Error("candidate contents do not match sourceBytes");
+  }
+  return verified;
+};