@kungfu-tech/buildchain 4.1.3-alpha.0 → 4.1.3-alpha.2

package/packages/core/workflow/attempt/identity.js

@@ -0,0 +1,165 @@
+import {
+  createIntent,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import {
+  object,
+  text,
+  list,
+  choice,
+  unique,
+  relativePath,
+} from "../../consumer/contract/shape.js";
+import { CONSUMER_CONTRACT } from "../../consumer/contract/plan.js";
+
+export const PIPELINE_PHASES = [
+  "admission",
+  "build",
+  "review",
+  "warrant",
+  "merge",
+  "publish",
+  "distribution",
+  "next-development",
+];
+export const SOURCE_GENERATION = "buildchain.source-generation/v1";
+export const BUSINESS_ATTEMPT = "buildchain.business-attempt/v1";
+const ROOT = /^sha256:[0-9a-f]{64}$/u;
+
+export function pipelineIntent({
+  repository,
+  repositoryId,
+  pullRequest,
+  targetBranch,
+  phases,
+  runtime,
+}) {
+  text(repository, "repository", /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/u);
+  text(repositoryId, "repositoryId");
+  if (!Number.isSafeInteger(pullRequest) || pullRequest < 1)
+    throw new Error("Invalid PR intent number");
+  text(
+    targetBranch,
+    "targetBranch",
+    /^(?:dev|alpha|release|publish-gate)\/[A-Za-z0-9/._-]+$/u,
+  );
+  list(phases, "phases", (phase, field) =>
+    choice(phase, PIPELINE_PHASES, field),
+  );
+  unique(phases, "phases");
+  if (
+    phases.some(
+      (phase, i) =>
+        i &&
+        PIPELINE_PHASES.indexOf(phase) <=
+          PIPELINE_PHASES.indexOf(phases[i - 1]),
+    )
+  )
+    throw new Error("Intent phases must follow pipeline order");
+  if (phases[0] !== "admission")
+    throw new Error("Intent must begin with admission");
+  return createIntent({
+    repository,
+    key: `pr-${pullRequest}:${targetBranch}`,
+    expectedNodes: phases,
+    runtime,
+    source: { kind: "pipeline", repositoryId, pullRequest, targetBranch },
+  });
+}
+
+export function sourceGeneration(intent, source, baseCommit) {
+  object(
+    source,
+    [
+      "schema",
+      "repository",
+      "commit",
+      "tree",
+      "configPath",
+      "configBlob",
+      "configDigest",
+      "contract",
+    ],
+    [],
+    "source",
+  );
+  if (
+    source.schema !== "buildchain.consumer-source/v1" ||
+    source.contract !== CONSUMER_CONTRACT ||
+    source.repository !== intent.repository
+  )
+    throw new Error("Generation requires the admitted consumer source");
+  for (const key of ["commit", "tree", "configBlob"])
+    text(source[key], `source.${key}`, /^[0-9a-f]{40}$/u);
+  relativePath(source.configPath, "source.configPath");
+  text(source.configDigest, "source.configDigest", ROOT);
+  text(baseCommit, "baseCommit", /^[0-9a-f]{40}$/u);
+  const value = {
+    schema: SOURCE_GENERATION,
+    intent: intent.id,
+    source: structuredClone(source),
+    baseCommit,
+  };
+  return { ...value, id: recordDigest(value) };
+}
+
+export function validateGeneration(value, intent) {
+  object(
+    value,
+    ["schema", "intent", "source", "baseCommit", "id"],
+    [],
+    "generation",
+  );
+  const expected = sourceGeneration(intent, value.source, value.baseCommit);
+  if (recordDigest(value) !== recordDigest(expected))
+    throw new Error("Generation identity mismatch");
+  return value;
+}
+
+export function businessAttempt({
+  intent,
+  generation,
+  predecessor = "",
+  requestKey,
+}) {
+  validateGeneration(generation, intent);
+  text(requestKey, "requestKey");
+  if (requestKey.length > 240)
+    throw new Error("Attempt request key exceeds its bound");
+  if (predecessor) text(predecessor, "predecessor", /^attempt-[0-9a-f]{64}$/u);
+  const value = {
+    schema: BUSINESS_ATTEMPT,
+    intent: intent.id,
+    generation: generation.id,
+    predecessor,
+    requestKey,
+  };
+  return { ...value, id: `attempt-${recordDigest(value).slice(7)}` };
+}
+
+export function validateAttempt(value, intent, generation) {
+  object(
+    value,
+    ["schema", "intent", "generation", "predecessor", "requestKey", "id"],
+    [],
+    "attempt",
+  );
+  const expected = businessAttempt({
+    intent,
+    generation,
+    predecessor: value.predecessor,
+    requestKey: value.requestKey,
+  });
+  if (recordDigest(value) !== recordDigest(expected))
+    throw new Error("Business attempt identity mismatch");
+  return value;
+}
+
+export function providerWriter(value, repository) {
+  object(value, ["repository", "runId", "runAttempt", "jobId"], [], "writer");
+  if (value.repository !== repository)
+    throw new Error("Writer belongs to a different repository");
+  for (const key of ["runId", "runAttempt", "jobId"])
+    text(value[key], `writer.${key}`, /^[1-9][0-9]*$/u);
+  return `${value.runId}:${value.runAttempt}:${value.jobId}`;
+}

package/packages/core/workflow/attempt/journal.js

@@ -0,0 +1,87 @@
+import {
+  canonicalJson,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import { readBusinessAttempt } from "./reader.js";
+
+export const ATTEMPT_JOURNAL = "buildchain.attempt-journal/v1";
+
+export function journalSnapshot(intent, records) {
+  readBusinessAttempt({ intent, records });
+  const body = { schema: ATTEMPT_JOURNAL, intent, records };
+  return { ...body, root: recordDigest(body) };
+}
+
+export function validateJournal(snapshot, intent) {
+  if (
+    snapshot?.schema !== ATTEMPT_JOURNAL ||
+    canonicalJson(snapshot.intent) !== canonicalJson(intent) ||
+    canonicalJson(snapshot) !==
+      canonicalJson(journalSnapshot(intent, snapshot.records))
+  )
+    throw new Error("Attempt journal identity or content root drift");
+  return snapshot;
+}
+
+// The provider atomically appends a single-parent Git commit with force=false.
+// Discussion is a projection of these admitted bytes, never a competing writer.
+export function atomicAttemptJournal(provider, intent) {
+  readBusinessAttempt({ intent, records: [] });
+  async function read() {
+    const loaded = await provider.read(intent);
+    const snapshot = loaded
+      ? validateJournal(loaded.snapshot, intent)
+      : journalSnapshot(intent, []);
+    return {
+      commit: loaded?.commit || "",
+      snapshot,
+      ...readBusinessAttempt(snapshot),
+    };
+  }
+  async function append(record, expectedHead) {
+    const observed = await read();
+    if (observed.snapshot.records.some((event) => event.id === record.id)) {
+      // Never acknowledge an invalid body merely because its ID was copied.
+      const prior = observed.snapshot.records.find(
+        (event) => event.id === record.id,
+      );
+      if (canonicalJson(prior) !== canonicalJson(record))
+        throw new Error("Conflicting attempt record bytes");
+      return observed;
+    }
+    if ((observed.head || "") !== expectedHead)
+      throw new Error("Stale attempt head; reobserve before writing");
+    if (record.node === "attempt") {
+      if (record.predecessor !== (observed.attempt || ""))
+        throw new Error("Recovery must succeed the current attempt");
+    } else if (record.attempt !== observed.attempt)
+      throw new Error("A superseded attempt cannot append new results");
+    const snapshot = journalSnapshot(intent, [
+      ...observed.snapshot.records,
+      record,
+    ]);
+    let failure;
+    try {
+      await provider.append({
+        intent,
+        snapshot,
+        expectedCommit: observed.commit,
+      });
+    } catch (error) {
+      failure = error;
+    }
+    // A lost response can follow a committed append. Reconcile the immutable
+    // record in live history; never retry the old parent with force=true.
+    const result = await read();
+    if (
+      !result.snapshot.records.some(
+        (event) => canonicalJson(event) === canonicalJson(record),
+      )
+    )
+      throw (
+        failure || new Error("Attempt append missing from provider readback")
+      );
+    return result;
+  }
+  return { read, append };
+}

package/packages/core/workflow/attempt/materials.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { object, text, choice } from "../../consumer/contract/shape.js";
+import { recordDigest } from "../../release/discussion/envelope.js";
+
+export const MATERIAL_KINDS = [
+  "artifact",
+  "checkpoint",
+  "receipt",
+  "passport",
+  "provider-readback",
+];
+
+export function materialReference(value, attempt, repository = "") {
+  object(
+    value,
+    ["id", "kind", "digest", "bytes", "url", "generation", "producerAttempt"],
+    [],
+    "material",
+  );
+  text(value.id, "material.id", /^[a-z][a-z0-9._/-]*$/u);
+  choice(value.kind, MATERIAL_KINDS, "material.kind");
+  text(value.digest, "material.digest", /^sha256:[0-9a-f]{64}$/u);
+  if (!Number.isSafeInteger(value.bytes) || value.bytes < 1)
+    throw new Error("Invalid material byte size");
+  const url = new URL(value.url);
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !["github.com", "api.github.com"].includes(url.hostname)
+  )
+    throw new Error(
+      "Material must use a permanent GitHub URL without credentials or signed queries",
+    );
+  if (
+    repository &&
+    !(url.hostname === "github.com"
+      ? url.pathname.startsWith(`/${repository}/releases/download/`) ||
+        url.pathname.startsWith(`/${repository}/actions/runs/`)
+      : url.pathname.startsWith(`/repos/${repository}/actions/artifacts/`) ||
+        url.pathname.startsWith(`/repos/${repository}/releases/assets/`))
+  )
+    throw new Error("Material belongs to another consumer repository");
+  if (
+    value.generation !== attempt.generation ||
+    value.producerAttempt !== attempt.id
+  )
+    throw new Error(
+      "Material is not qualified for this exact attempt and generation",
+    );
+  return { ...value };
+}
+
+export function verifyMaterialBytes(reference, bytes) {
+  const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+  if (bytes.length !== reference.bytes || digest !== reference.digest)
+    throw new Error(`Material integrity mismatch: ${reference.id}`);
+  return { id: reference.id, digest, bytes: bytes.length };
+}
+
+export function indexMaterials(index, references, attempt) {
+  for (const reference of references) {
+    materialReference(reference, attempt);
+    const old = index[reference.id];
+    if (old && recordDigest(old) !== recordDigest(reference))
+      throw new Error(`Immutable material identity conflict: ${reference.id}`);
+    index[reference.id] = { ...reference };
+  }
+  return index;
+}

package/packages/core/workflow/attempt/reader-entry.js

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+import { readBusinessAttempt } from "./reader.js";
+export { readBusinessAttempt } from "./reader.js";
+
+// Captured, provider-authenticated JSON only. No live ref lookup or effects.
+if (typeof require !== "undefined" && require.main === module) {
+  const state = readBusinessAttempt(JSON.parse(fs.readFileSync(0, "utf8")));
+  const { status, reason, attempt, generation, missing, recovery } = state;
+  process.stdout.write(
+    `${JSON.stringify({ status, reason, attempt, generation, missing, recovery })}\n`,
+  );
+}

package/packages/core/workflow/attempt/reader.js

@@ -0,0 +1,149 @@
+import {
+  canonicalJson,
+  encodeRecord,
+  recordDigest,
+} from "../../release/discussion/envelope.js";
+import { readReleaseDiscussion } from "../../release/discussion/reader.js";
+import { pipelineIntent } from "./identity.js";
+import { validateAttemptRecord } from "./records.js";
+import { indexMaterials } from "./materials.js";
+
+export const MAX_ATTEMPT_RECORDS = 10_000;
+const MAX_HISTORY_BYTES = 32 * 1024 * 1024;
+
+function validateIntent(intent) {
+  const source = intent.source;
+  if (source?.kind !== "pipeline") throw new Error("Not a pipeline intent");
+  const expected = pipelineIntent({
+    ...source,
+    repository: intent.repository,
+    phases: intent.expectedNodes,
+    runtime: intent.runtime,
+  });
+  if (recordDigest(expected) !== recordDigest(intent))
+    throw new Error("Pipeline intent identity mismatch");
+}
+
+function foldAttempt(events, intent) {
+  events.sort((a, b) => a.sequence - b.sequence);
+  const roots = events.filter((record) => record.node === "attempt");
+  if (roots.length !== 1 || roots[0] !== events[0])
+    throw new Error("Attempt requires exactly one initial root");
+  const phases = Object.create(null),
+    materials = Object.create(null),
+    keys = new Set(),
+    runs = new Map();
+  let previous = null;
+  for (const record of events) {
+    const value = record.payload;
+    if (
+      value.identity.id !== roots[0].payload.identity.id ||
+      value.generation.id !== roots[0].payload.generation.id
+    )
+      throw new Error("Attempt changed its immutable generation");
+    if (
+      record.sequence !== (previous ? previous.sequence + 1 : 0) ||
+      value.previous !== (previous?.id || "")
+    )
+      throw new Error(
+        "Attempt record chain has a gap, fork or missing predecessor",
+      );
+    if (keys.has(value.eventKey))
+      throw new Error("Conflicting duplicate event key");
+    keys.add(value.eventKey);
+    if (record.node !== "attempt") {
+      const before = intent.expectedNodes.slice(
+        0,
+        intent.expectedNodes.indexOf(record.node),
+      );
+      if (before.some((phase) => phases[phase]?.payload.state !== "success"))
+        throw new Error("Phase predecessor has not succeeded");
+      const old = phases[record.node];
+      if (
+        old &&
+        ["success", "failure", "cancelled", "superseded"].includes(
+          old.payload.state,
+        )
+      )
+        throw new Error(
+          "Terminal phase history is immutable; recover in a successor attempt",
+        );
+      phases[record.node] = record;
+    }
+    indexMaterials(materials, value.materials, value.identity);
+    runs.set(record.writer, value.writer);
+    previous = record;
+  }
+  return {
+    identity: roots[0].payload.identity,
+    generation: roots[0].payload.generation,
+    head: previous.id,
+    events,
+    phases,
+    materials,
+    runs: [...runs.values()],
+  };
+}
+
+// This projection is evidence navigation, never a Warrant or publication authorization.
+export function readBusinessAttempt({ intent, records }) {
+  validateIntent(intent);
+  if (!Array.isArray(records) || records.length > MAX_ATTEMPT_RECORDS)
+    throw new Error("Attempt record count exceeds its bound");
+  if (Buffer.byteLength(canonicalJson(records)) > MAX_HISTORY_BYTES)
+    throw new Error("Attempt history byte bound exceeded");
+  const unique = new Map(),
+    grouped = new Map();
+  for (const record of records) {
+    validateAttemptRecord(record, intent);
+    unique.set(record.id, record);
+  }
+  for (const record of unique.values()) {
+    const events = grouped.get(record.attempt) || [];
+    events.push(record);
+    grouped.set(record.attempt, events);
+  }
+  const lineage = readReleaseDiscussion({
+    body: encodeRecord(intent),
+    records: [...unique.values()],
+  });
+  const history = lineage.attempts.map((id) =>
+    foldAttempt(grouped.get(id), intent),
+  );
+  const current = history.at(-1);
+  if (!current)
+    return {
+      intent,
+      status: "pending",
+      reason: "not-admitted",
+      attempt: "",
+      missing: intent.expectedNodes,
+      history,
+      recovery: null,
+    };
+  const missing = intent.expectedNodes.filter(
+    (phase) => current.phases[phase]?.payload.state !== "success",
+  );
+  const states = Object.values(current.phases).map((record) => record.payload);
+  const stopped = states.find((value) =>
+    ["failure", "cancelled", "superseded"].includes(value.state),
+  );
+  const waiting = states.find((value) => value.state === "waiting");
+  const status =
+    stopped?.state ||
+    (missing.length ? (waiting ? "waiting" : "running") : "complete");
+  return {
+    intent,
+    attempt: current.identity.id,
+    generation: current.generation.id,
+    status,
+    reason: stopped?.reason || waiting?.reason || status,
+    head: current.head,
+    missing,
+    phases: current.phases,
+    materials: current.materials,
+    runs: current.runs,
+    history,
+    recovery: status === "complete" ? null : { attempt: current.identity.id },
+  };
+}

package/packages/core/workflow/attempt/records.js

@@ -0,0 +1,153 @@
+import {
+  createProgress,
+  recordDigest,
+  encodeRecord,
+} from "../../release/discussion/envelope.js";
+import { object, text, choice, unique } from "../../consumer/contract/shape.js";
+import { providerWriter, validateAttempt } from "./identity.js";
+import { materialReference } from "./materials.js";
+
+export const ATTEMPT_EVENT = "buildchain.business-attempt-event/v1";
+export const STATES = [
+  "running",
+  "waiting",
+  "success",
+  "failure",
+  "cancelled",
+  "superseded",
+];
+const ENVELOPE_STATUS = {
+  running: "running",
+  waiting: "running",
+  success: "success",
+  failure: "failure",
+  cancelled: "cancelled",
+  superseded: "cancelled",
+};
+
+export function attemptRecord({
+  intent,
+  attempt,
+  generation,
+  writer,
+  runtime,
+  previous = null,
+  eventKey,
+  phase,
+  state,
+  reason = "",
+  materials = [],
+}) {
+  validateAttempt(attempt, intent, generation);
+  const writerId = providerWriter(writer, intent.repository);
+  choice(state, STATES, "state");
+  text(eventKey, "eventKey");
+  if (
+    eventKey.length > 240 ||
+    typeof reason !== "string" ||
+    reason.length > 2000
+  )
+    throw new Error("Attempt event text exceeds its bound");
+  if (!previous && (phase !== "attempt" || state !== "running"))
+    throw new Error("Open an attempt root before phase progress");
+  if (
+    previous &&
+    (previous.attempt !== attempt.id ||
+      previous.payload.generation.id !== generation.id)
+  )
+    throw new Error(
+      "Record predecessor belongs to another attempt or generation",
+    );
+  if (!Array.isArray(materials) || materials.length > 100)
+    throw new Error("Attempt event material bound exceeded");
+  unique(
+    materials.map((item) => item.id),
+    "materials",
+  );
+  materials.forEach((item) =>
+    materialReference(item, attempt, intent.repository),
+  );
+  return createProgress({
+    intent,
+    attempt: attempt.id,
+    predecessor: attempt.predecessor,
+    writer: writerId,
+    runtime,
+    node: phase,
+    status: ENVELOPE_STATUS[state],
+    sequence: previous ? previous.sequence + 1 : 0,
+    payload: {
+      schema: ATTEMPT_EVENT,
+      identity: attempt,
+      generation,
+      writer: { ...writer },
+      previous: previous?.id || "",
+      eventKey,
+      state,
+      reason,
+      materials: structuredClone(materials),
+    },
+  });
+}
+
+export function validateAttemptRecord(record, intent) {
+  const value = record.payload;
+  object(
+    value,
+    [
+      "schema",
+      "identity",
+      "generation",
+      "writer",
+      "previous",
+      "eventKey",
+      "state",
+      "reason",
+      "materials",
+    ],
+    [],
+    "attemptEvent",
+  );
+  if (value.schema !== ATTEMPT_EVENT)
+    throw new Error("Attempt event requires its historical runtime reader");
+  validateAttempt(value.identity, intent, value.generation);
+  const { id, ...content } = record;
+  if (
+    id !== recordDigest(content) ||
+    record.attempt !== value.identity.id ||
+    record.intent !== intent.id ||
+    record.predecessor !== value.identity.predecessor
+  )
+    throw new Error("Attempt record identity mismatch");
+  if (providerWriter(value.writer, intent.repository) !== record.writer)
+    throw new Error("Attempt provider writer mismatch");
+  choice(value.state, STATES, "attemptEvent.state");
+  if (record.status !== ENVELOPE_STATUS[value.state])
+    throw new Error("Attempt record status mismatch");
+  if (value.previous)
+    text(value.previous, "previous", /^sha256:[0-9a-f]{64}$/u);
+  const expected = attemptRecord({
+    intent,
+    attempt: value.identity,
+    generation: value.generation,
+    writer: value.writer,
+    runtime: record.runtime,
+    previous: value.previous
+      ? {
+          id: value.previous,
+          attempt: record.attempt,
+          payload: value,
+          sequence: record.sequence - 1,
+        }
+      : null,
+    eventKey: value.eventKey,
+    phase: record.node,
+    state: value.state,
+    reason: value.reason,
+    materials: value.materials,
+  });
+  if (recordDigest(expected) !== recordDigest(record))
+    throw new Error("Invalid attempt record envelope");
+  encodeRecord(record);
+  return record;
+}