pi-daddy 0.23.0 → 0.24.0

package/src/experiment-store.ts

@@ -13,7 +13,8 @@ export async function ownedDirectory(path: string) {
   if (!s.isDirectory() || s.isSymbolicLink() || s.uid !== BigInt(process.getuid!()) || (s.mode & 0o077n) !== 0n || await realpath(path) !== path) throw new Error("canonical private experiment directory required");
   return s;
 }
-export async function readExperimentFile(path: string, max: number): Promise<Buffer> {
+export async function readExperimentFile(path: string, max: number, options: { appendOnly?: true } = {}): Promise<Buffer> {
+  if (Object.keys(options).some(key => key !== "appendOnly") || options.appendOnly !== undefined && options.appendOnly !== true) throw new TypeError("invalid experiment read mode");
   const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   return runWithFinalizers(async () => {
     const s = await file.stat({ bigint: true });
@@ -21,7 +22,14 @@ export async function readExperimentFile(path: string, max: number): Promise<Buf
     const data = Buffer.alloc(Number(s.size)); let offset = 0;
     while (offset < data.length) { const n = (await file.read(data, offset, data.length - offset, offset)).bytesRead; if (!n) throw new Error("short experiment read"); offset += n; }
     const end = await file.stat({ bigint: true }), current = await lstat(path, { bigint: true });
-    if (end.size !== s.size || end.mtimeNs !== s.mtimeNs || current.dev !== s.dev || current.ino !== s.ino || current.nlink !== 1n) throw new Error("experiment source changed");
+    const identityChanged = current.dev !== s.dev || current.ino !== s.ino || current.nlink !== 1n;
+    if (!options.appendOnly && (end.size !== s.size || end.mtimeNs !== s.mtimeNs || identityChanged)) throw new Error("experiment source changed");
+    if (options.appendOnly) {
+      if (end.size < s.size || identityChanged) throw new Error("experiment source changed");
+      const verify = Buffer.alloc(data.length); let checked = 0;
+      while (checked < verify.length) { const n = (await file.read(verify, checked, verify.length - checked, checked)).bytesRead; if (!n) throw new Error("short experiment read"); checked += n; }
+      if (!verify.equals(data)) throw new Error("experiment source changed");
+    }
     return data;
   }, [{ label: "experiment read close failed", run: () => file.close() }]);
 }
@@ -59,7 +67,7 @@ export function experimentStore(value: ExperimentBinding) {
     if (String(root.dev) !== b.device || String(root.ino) !== b.inode || String(file.dev) !== b.journalDevice || String(file.ino) !== b.journalInode) throw new Error("experiment identity replaced");
   };
   const read = async () => {
-    await check(); const bytes = await readExperimentFile(path, 256 * 1024); await check();
+    await check(); const bytes = await readExperimentFile(path, 256 * 1024, { appendOnly: true }); await check();
     const text = new TextDecoder("utf8", { fatal: true }).decode(bytes); if (!text.endsWith("\n")) throw new Error("torn experiment journal");
     const lines = text.slice(0, -1).split("\n"); if (lines.length > 260 || experimentHash(parseWorkJson(lines[0])) !== experimentHash(b)) throw new Error("experiment header/bound mismatch");
     let previous = experimentHash(b); const events: Record<string, unknown>[] = [];

package/src/work-command.ts

@@ -0,0 +1,179 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import {
+  appendWorkLedgerEventOnce,
+  buildWorkOccurrenceEvent,
+  buildWorkRevisionEvent,
+  buildWorkSnapshotEvent,
+  parseWorkLedgerText,
+  projectWorkLedger,
+  type EventRef,
+  type RevisionRef,
+  type WorkFrozen,
+  type WorkOccurrencePayload,
+  type WorkProjectionContext,
+  type WorkRevision,
+} from "./work-ledger.ts";
+import { withFileLock } from "./file-lock.ts";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9._:/@+\-]{0,127}$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const sha256 = (value: string): string => createHash("sha256").update(value).digest("hex");
+const eventRef = (event: { eventId: string; digest: string }): EventRef => ({ eventId: event.eventId, digest: event.digest });
+const revisionRef = (event: { payload: { revision: { kind: WorkRevision["kind"]; id: string; revision: number; digest: string } } }): RevisionRef => {
+  const { kind, id, revision, digest } = event.payload.revision;
+  return { kind, id, revision, digest };
+};
+
+export interface DeclaredWorkState {
+  readonly version: "pi-daddy-declared-work-v1";
+  readonly id: string;
+  readonly outcomeDigest: string;
+  readonly ledgerPath: string;
+  readonly statePath: string;
+  readonly grantLedgerPath: string | null;
+  readonly selectedSnapshot: NonNullable<WorkProjectionContext["selectedSnapshot"]>;
+  readonly scope: RevisionRef;
+  readonly intent: RevisionRef;
+  readonly obligation: RevisionRef;
+  readonly policy: RevisionRef;
+}
+
+interface StoredDeclaredWorkState extends Omit<DeclaredWorkState, "statePath"> {}
+
+export interface DeclareWorkInput {
+  cwd: string;
+  id: string;
+  outcome: string;
+}
+
+function paths(input: DeclareWorkInput): { ledgerPath: string; statePath: string; grantLedgerPath: null } {
+  const root = resolve(input.cwd);
+  return { ledgerPath: join(root, ".pi", "work.jsonl"), statePath: join(root, ".pi", "work-current.json"), grantLedgerPath: null };
+}
+
+const exactKeys = (value: object, expected: readonly string[]): boolean => {
+  const actual = Object.keys(value).sort();
+  return actual.length === expected.length && actual.every((key, index) => key === [...expected].sort()[index]);
+};
+const validRef = (value: unknown, kind: WorkRevision["kind"]): value is RevisionRef => {
+  if (!value || typeof value !== "object" || !exactKeys(value, ["kind", "id", "revision", "digest"])) return false;
+  const ref = value as RevisionRef;
+  return ref.kind === kind && ID.test(ref.id) && Number.isSafeInteger(ref.revision) && ref.revision > 0 && DIGEST.test(ref.digest);
+};
+
+export async function loadDeclaredWork(statePath: string): Promise<WorkFrozen<DeclaredWorkState> | null> {
+  let text: string;
+  try { text = await readFile(statePath, "utf8"); }
+  catch (error) { if ((error as { code?: string }).code === "ENOENT") return null; throw error; }
+  try {
+    const value = JSON.parse(text) as StoredDeclaredWorkState;
+    if (!value || typeof value !== "object" || !exactKeys(value, [
+      "version", "id", "outcomeDigest", "ledgerPath", "grantLedgerPath", "selectedSnapshot", "scope", "intent", "obligation", "policy",
+    ]) || value.version !== "pi-daddy-declared-work-v1" || !ID.test(value.id) || !DIGEST.test(value.outcomeDigest) ||
+      typeof value.ledgerPath !== "string" || !isAbsolute(value.ledgerPath) ||
+      (value.grantLedgerPath !== null && (typeof value.grantLedgerPath !== "string" || !isAbsolute(value.grantLedgerPath))) ||
+      !validRef(value.scope, "scope") || !validRef(value.intent, "goal") || !validRef(value.obligation, "obligation") || !validRef(value.policy, "policy") ||
+      !value.selectedSnapshot || typeof value.selectedSnapshot !== "object" ||
+      !exactKeys(value.selectedSnapshot, ["snapshot", "event"]) ||
+      !exactKeys(value.selectedSnapshot.snapshot, ["id", "digest"]) || !ID.test(value.selectedSnapshot.snapshot.id) || !DIGEST.test(value.selectedSnapshot.snapshot.digest) ||
+      !exactKeys(value.selectedSnapshot.event, ["eventId", "digest"]) || !ID.test(value.selectedSnapshot.event.eventId) || !DIGEST.test(value.selectedSnapshot.event.digest)) {
+      throw new Error("shape");
+    }
+    const expectedLedger = resolve(dirname(statePath), "work.jsonl");
+    if (resolve(value.ledgerPath) !== expectedLedger) throw new Error("relocated");
+    const ledger = await readFile(value.ledgerPath, "utf8");
+    const ingestion = parseWorkLedgerText(ledger);
+    const projection = projectWorkLedger(ledger, { selectedSnapshot: value.selectedSnapshot, authority: null });
+    const obligation = projection.obligations.find(item => item.binding.obligation.digest === value.obligation.digest);
+    if (!ingestion.complete || projection.scopeState !== "valid" || !obligation || projection.selectedSnapshot?.digest !== value.selectedSnapshot.snapshot.digest) throw new Error("unbound");
+    return Object.freeze({ ...value, statePath: resolve(statePath) });
+  } catch {
+    throw new Error("invalid declared work state; no task was selected");
+  }
+}
+
+export async function declareWork(input: DeclareWorkInput): Promise<WorkFrozen<DeclaredWorkState>> {
+  if (!input || typeof input !== "object" || Object.keys(input).some(key => !["cwd", "id", "outcome"].includes(key))) {
+    throw new TypeError("unsupported work declaration field");
+  }
+  if (!ID.test(input.id) || typeof input.outcome !== "string" || !input.outcome.trim()) throw new TypeError("work declaration requires an identifier and non-empty outcome");
+  const resolved = paths(input), outcomeDigest = sha256(input.outcome.trim());
+  await mkdir(dirname(resolved.ledgerPath), { recursive: true });
+  await mkdir(dirname(resolved.statePath), { recursive: true });
+  return withFileLock(resolved.statePath, "declared work", async () => {
+    const existing = await loadDeclaredWork(resolved.statePath);
+    if (existing) {
+      if (existing.id === input.id && existing.outcomeDigest === outcomeDigest) return existing;
+      throw new Error(`declared work id ${input.id} already names a different outcome`);
+    }
+    const pendingPath = `${resolved.statePath}.pending`;
+    let prepared: { version: "pi-daddy-work-preparation-v1"; id: string; outcomeDigest: string; createdAt: string };
+    try {
+      prepared = JSON.parse(await readFile(pendingPath, "utf8"));
+      if (!prepared || Object.keys(prepared).sort().join() !== "createdAt,id,outcomeDigest,version" || prepared.version !== "pi-daddy-work-preparation-v1" || prepared.id !== input.id || prepared.outcomeDigest !== outcomeDigest || Number.isNaN(Date.parse(prepared.createdAt))) throw new Error("invalid");
+    } catch (error) {
+      if ((error as { code?: string }).code !== "ENOENT") throw new Error("another or invalid work declaration is pending; no events were replaced");
+      prepared = { version: "pi-daddy-work-preparation-v1", id: input.id, outcomeDigest, createdAt: new Date().toISOString() };
+      await writeFile(pendingPath, `${JSON.stringify(prepared)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    }
+    const now = new Date(prepared.createdAt);
+    const revision = (kind: WorkRevision["kind"], name: string, patch: Partial<Omit<WorkRevision, "digest">> = {}) =>
+      buildWorkRevisionEvent({ eventId: `work:${input.id}:${name}:1`, now, revision: {
+        kind, id: `work:${input.id}:${name}`, revision: 1, scopeId: `work:${input.id}:scope`, predecessor: null,
+        contentDigest: sha256(`${name}\0${outcomeDigest}`), parent: null, dependencies: [], ownerId: "local-operator",
+        permittedEffects: [], policy: null, ...patch,
+      } });
+    const scope = revision("scope", "scope"), policy = revision("policy", "policy");
+    const intent = revision("goal", "goal", { parent: revisionRef(scope) });
+    const obligation = revision("obligation", "obligation", { parent: revisionRef(intent), policy: revisionRef(policy) });
+    const binding = { intent: revisionRef(intent), obligation: revisionRef(obligation), artifact: null, policy: revisionRef(policy) };
+    const snapshot = buildWorkSnapshotEvent({ eventId: `work:${input.id}:snapshot:1`, now, snapshot: {
+      snapshotId: `work:${input.id}:selected`, scope: revisionRef(scope), revisions: [revisionRef(policy), revisionRef(intent), revisionRef(obligation)], bindings: [binding],
+    } });
+    for (const event of [scope, policy, intent, obligation, snapshot]) await appendWorkLedgerEventOnce({ path: resolved.ledgerPath, grantLedgerPath: resolved.grantLedgerPath }, event);
+    const stored: StoredDeclaredWorkState = {
+      version: "pi-daddy-declared-work-v1", id: input.id, outcomeDigest, ledgerPath: resolved.ledgerPath, grantLedgerPath: resolved.grantLedgerPath,
+      selectedSnapshot: { snapshot: { id: snapshot.payload.snapshot.snapshotId, digest: snapshot.payload.snapshot.digest }, event: eventRef(snapshot) },
+      scope: revisionRef(scope), intent: revisionRef(intent), obligation: revisionRef(obligation), policy: revisionRef(policy),
+    };
+    const temporary = `${resolved.statePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temporary, `${JSON.stringify(stored, null, 2)}\n`, { encoding: "utf8", mode: 0o600, flag: "wx" });
+      await rename(temporary, resolved.statePath);
+    } finally { await rm(temporary, { force: true }); }
+    await rm(pendingPath);
+    return Object.freeze({ ...stored, statePath: resolved.statePath });
+  });
+}
+
+export type DeclaredOccurrenceIdentity = Pick<WorkOccurrencePayload["labels"], "toolCallId" | "taskId" | "workspaceId" | "definitionDigest" | "configurationDigest" | "modelId" | "effortId"> & {
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string | null;
+  variantId: string | null;
+  now: Date;
+};
+
+export async function appendDeclaredWorkOccurrence(state: WorkFrozen<DeclaredWorkState>, identity: DeclaredOccurrenceIdentity,
+  occurrenceState: WorkOccurrencePayload["state"]): Promise<void> {
+  const { executionId, parentExecutionId, childId, variantId, now, ...rawLabels } = identity;
+  const label = (name: string, value: string | null): string | null => value === null ? null : ID.test(value) ? value : `${name}:${sha256(value)}`;
+  const labels = {
+    toolCallId: label("toolcall", rawLabels.toolCallId), taskId: label("task", rawLabels.taskId),
+    workspaceId: label("workspace", rawLabels.workspaceId), definitionDigest: rawLabels.definitionDigest,
+    configurationDigest: rawLabels.configurationDigest, modelId: label("model", rawLabels.modelId), effortId: label("effort", rawLabels.effortId),
+  };
+  const event = buildWorkOccurrenceEvent({
+    eventId: `work:${state.id}:attempt:${identity.executionId}:${occurrenceState}`,
+    now,
+    payload: {
+      scope: state.scope, obligation: state.obligation, executionId,
+      parentExecutionId, childId, variantId: label("variant", variantId), artifact: null,
+      provenance: "observed", state: occurrenceState,
+      labels: { sessionId: null, branchLeafId: null, ...labels },
+    },
+  });
+  await appendWorkLedgerEventOnce({ path: state.ledgerPath, grantLedgerPath: state.grantLedgerPath }, event);
+}