harnery 0.32.0 → 0.34.0

package/src/core/events/v3/bootstrap.ts

@@ -0,0 +1,226 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fsyncParentDirectory } from "../../workflow/durable-record.ts";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+import { ADAPTER_CAPABILITY_PROFILES_V3 } from "./capabilities.ts";
+import {
+  buildActivationManifestV3,
+  buildCandidateGenesisManifestV3,
+  type CandidateGenesisManifestV3,
+  EVENT_V3_ACTIVATION_MANIFEST,
+  EVENT_V3_GENESIS_MANIFEST,
+  type EventV3ControlState,
+  readEventV3ControlState,
+  repairEventV3ControlPair,
+} from "./control.ts";
+import { loadOrCreateFingerprintKeyStoreV3 } from "./fingerprint-keys.ts";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
+import { liveEventV3BuildId, livePlatformV3 } from "./live-routing.ts";
+
+export interface InitializeEventLedgerV3Input {
+  coordRoot: string;
+  harneryBuild: string;
+  hostBuild: string;
+  configDigest: `sha256:${string}`;
+  approvalRecordId: string;
+  forceNewEpoch?: boolean;
+  resumeCandidate?: boolean;
+  now?: () => Date;
+}
+
+export interface InitializeEventLedgerV3Result {
+  state: "active";
+  initialized: boolean;
+  archived_epoch?: string;
+  control: Extract<EventV3ControlState, { state: "active" }>;
+}
+
+/**
+ * Ensure programmatic Harnery entry points have the same universal V3
+ * boundary as `harn init`. Only a genuinely absent control pair is created;
+ * candidate, damaged, or incompatible state still fails closed.
+ */
+export function ensureEventLedgerV3(
+  coordRoot: string,
+  approvalRecordId = "harnery-runtime-v3-universal",
+): Extract<EventV3ControlState, { state: "active" }> {
+  const root = resolve(coordRoot);
+  const current = readEventV3ControlState(root);
+  if (current.state === "active") return current;
+  if (current.state !== "closed") {
+    throw new Error(`event_v3_control_unavailable:${current.state}`);
+  }
+  const configPath = join(root, ".harnery", "config.jsonc");
+  return initializeEventLedgerV3({
+    coordRoot: root,
+    harneryBuild: repositoryBuild(rootOfHarnery()),
+    hostBuild: repositoryBuild(root),
+    configDigest: sha256V3(existsSync(configPath) ? readFileSync(configPath) : Buffer.from("{}\n")),
+    approvalRecordId,
+  }).control;
+}
+
+/**
+ * Ensure a root has one current V3 epoch. An incompatible or explicitly
+ * replaced epoch is moved intact to the V3 archive before the new control
+ * pair is published. No historical ledger bytes are rewritten or deleted.
+ */
+export function initializeEventLedgerV3(
+  input: InitializeEventLedgerV3Input,
+): InitializeEventLedgerV3Result {
+  const root = resolve(input.coordRoot);
+  let current = readEventV3ControlState(root);
+  if (input.resumeCandidate && current.state === "repairable") {
+    current = repairEventV3ControlPair(root);
+  }
+  if (!input.forceNewEpoch && current.state === "active") {
+    return { state: "active", initialized: false, control: current };
+  }
+  if (!input.forceNewEpoch && input.resumeCandidate && current.state === "candidate") {
+    return activateCandidateEpoch(root, current.genesis, input.approvalRecordId);
+  }
+  if (!input.forceNewEpoch && current.state === "candidate") {
+    throw new Error("event_v3_candidate_requires_explicit_activation_or_epoch_replacement");
+  }
+
+  const now = input.now ?? (() => new Date());
+  const createdAt = now().toISOString();
+  const archivedEpoch = archiveCurrentEpoch(root, createdAt);
+  const keys = loadOrCreateFingerprintKeyStoreV3(root, now);
+  const harneryBuild = safeBuild(input.harneryBuild);
+  const hostBuild = safeBuild(input.hostBuild);
+  const producerId = "prd_harnery-init" as const;
+  const bootId =
+    `boot_${createHash("sha256").update(`${root}\0${createdAt}`).digest("hex")}` as const;
+  const buildId = liveEventV3BuildId(harneryBuild);
+  const rootId = `root_${createHash("sha256").update(root).digest("hex")}` as const;
+  const instanceId =
+    `inst_init_${createHash("sha256").update(`${root}\0${createdAt}`).digest("hex")}` as const;
+  const capabilityDigests = Object.values(ADAPTER_CAPABILITY_PROFILES_V3)
+    .map((profile) => sha256V3(canonicalJsonV3(profile)))
+    .sort();
+  const candidate = buildCandidateGenesisManifestV3({
+    profile: {
+      initial_schema_digest: EVENT_V3_SCHEMA_DIGEST,
+      contract_source_digest: EVENT_V3_SCHEMA_DIGEST,
+      harnery_commit: harneryBuild,
+      host_repository_commit: hostBuild,
+      producer_build_ids: [buildId],
+      adapter_capability_profile_digests: capabilityDigests,
+      config_digest: input.configDigest,
+      canonicalizer_version: "harnery-jcs-nfc-v1",
+      fingerprint_version: "hmac-sha256-v1",
+      privacy_key_epoch: keys.active_epoch_id,
+      candidate_created_at: createdAt,
+    },
+    root_id: rootId,
+    instance_id: instanceId,
+    producer: {
+      producer_id: producerId,
+      boot_id: bootId,
+      sequence: 1,
+      build_id: buildId,
+      platform: livePlatformV3(),
+    },
+  });
+  publishControlFile(join(root, EVENT_V3_GENESIS_MANIFEST), candidate);
+  const candidateState = repairEventV3ControlPair(root);
+  if (candidateState.state !== "candidate") {
+    throw new Error(`event_v3_candidate_initialization_failed:${candidateState.state}`);
+  }
+  const activated = activateCandidateEpoch(root, candidate, input.approvalRecordId);
+  return {
+    ...activated,
+    ...(archivedEpoch ? { archived_epoch: archivedEpoch } : {}),
+  };
+}
+
+function activateCandidateEpoch(
+  root: string,
+  candidate: CandidateGenesisManifestV3,
+  approvalRecordId: string,
+): InitializeEventLedgerV3Result {
+  const producer = candidate.event.producer;
+  const activation = buildActivationManifestV3({
+    candidate,
+    approval_record_id: approvalRecordId,
+    activation_approved_at: candidate.profile.candidate_created_at,
+    producer: {
+      producer_id: producer.producer_id as `prd_${string}`,
+      boot_id: producer.boot_id as `boot_${string}`,
+      sequence: producer.sequence + 1,
+      build_id: producer.build_id as `build_${string}`,
+      platform: producer.platform,
+      ...(producer.bridge ? { bridge: producer.bridge } : {}),
+    },
+  });
+  publishControlFile(join(root, EVENT_V3_ACTIVATION_MANIFEST), activation);
+  const active = repairEventV3ControlPair(root);
+  if (active.state !== "active") {
+    throw new Error(`event_v3_activation_failed:${active.state}`);
+  }
+  return { state: "active", initialized: true, control: active };
+}
+
+function archiveCurrentEpoch(root: string, createdAt: string): string | undefined {
+  const current = join(root, ".harnery", "ledgers", "v3");
+  if (!existsSync(current)) return undefined;
+  const archives = join(root, ".harnery", "ledgers", "v3-archives");
+  mkdirSync(archives, { recursive: true, mode: 0o700 });
+  const stamp = createdAt.replace(/[^0-9]/g, "");
+  let target = join(archives, `epoch-${stamp}`);
+  let suffix = 0;
+  while (existsSync(target)) target = join(archives, `epoch-${stamp}-${++suffix}`);
+  renameSync(current, target);
+  fsyncParentDirectory(target);
+  return target;
+}
+
+function publishControlFile(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.tmp.${process.pid}`;
+  const fd = openSync(temp, "wx", 0o600);
+  try {
+    writeFileSync(fd, `${canonicalJsonV3(value)}\n`, "utf8");
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  chmodSync(temp, 0o600);
+  renameSync(temp, path);
+  fsyncParentDirectory(path);
+}
+
+function safeBuild(value: string): string {
+  const normalized = value.normalize("NFC").trim();
+  if (/^[a-zA-Z0-9._-]{1,120}$/.test(normalized)) return normalized;
+  return createHash("sha256")
+    .update(normalized || "unknown")
+    .digest("hex");
+}
+
+function rootOfHarnery(): string {
+  return resolve(import.meta.dir, "../../../..");
+}
+
+function repositoryBuild(root: string): string {
+  const result = spawnSync("git", ["-C", root, "rev-parse", "HEAD"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  const commit = result.status === 0 ? result.stdout.trim() : "";
+  if (/^[0-9a-f]{40,64}$/.test(commit)) return commit;
+  return createHash("sha256").update(resolve(root)).digest("hex");
+}

package/src/core/events/v3/builder.ts

@@ -0,0 +1,59 @@
+import type { EventOfTypeV3, EventPayloadV3, EventTypeV3 } from "./contract.ts";
+import { EVENT_V3_CONTRACT_MAJOR, EVENT_V3_CONTRACT_NAME } from "./contract.ts";
+import { EVENT_V3_SCHEMA_DIGEST } from "./generated.ts";
+import { clockIdV3, eventIdV3 } from "./ids.ts";
+
+type EventWithoutDiscriminator<T extends EventTypeV3> = Omit<
+  EventOfTypeV3<T>,
+  "attestation_id" | "contract" | "event_id" | "event_type" | "payload" | "time"
+>;
+
+type RootEventTypeV3 =
+  | "ledger.genesis"
+  | "ledger.activated"
+  | "ledger.schema_advanced"
+  | "ledger.comparability_advanced";
+
+type AttestationInputV3<T extends EventTypeV3> = T extends RootEventTypeV3
+  ? { attestation_id?: never }
+  : { attestation_id: `att_${string}` };
+
+export type BuildEventV3Input<T extends EventTypeV3> = EventWithoutDiscriminator<T> &
+  AttestationInputV3<T> & {
+    payload: EventPayloadV3<T>;
+    event_id?: `evt_${string}`;
+    observed_at?: string;
+    recorded_at?: string;
+    monotonic_ns?: string;
+    clock_id?: `clk_${string}`;
+    skew?: "normal" | "regressed" | "unknown";
+  };
+
+export function buildEventV3<T extends EventTypeV3>(
+  eventType: T,
+  input: BuildEventV3Input<T>,
+): EventOfTypeV3<T> {
+  const now = input.recorded_at ?? new Date().toISOString();
+  return {
+    contract: {
+      name: EVENT_V3_CONTRACT_NAME,
+      major: EVENT_V3_CONTRACT_MAJOR,
+      schema_digest: EVENT_V3_SCHEMA_DIGEST,
+    },
+    event_id: input.event_id ?? eventIdV3(),
+    event_type: eventType,
+    time: {
+      observed_at: input.observed_at ?? now,
+      recorded_at: now,
+      ...(input.monotonic_ns ? { monotonic_ns: input.monotonic_ns } : {}),
+      clock_id: input.clock_id ?? clockIdV3(),
+      skew: input.skew ?? "unknown",
+    },
+    producer: input.producer,
+    scope: input.scope,
+    ...(input.attestation_id ? { attestation_id: input.attestation_id } : {}),
+    links: input.links,
+    provenance: input.provenance,
+    payload: input.payload,
+  } as EventOfTypeV3<T>;
+}

package/src/core/events/v3/canonical.ts

@@ -0,0 +1,153 @@
+import { createHash, createHmac, hkdfSync } from "node:crypto";
+
+export const EVENT_V3_CANONICALIZER = "harnery-jcs-nfc-v1" as const;
+
+export type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+/**
+ * Canonical JSON used for V3 contract digests, event bytes, and fingerprints.
+ *
+ * It follows RFC 8785's ECMAScript number and string serialization, adds the
+ * V3 NFC rule for keys and values, and rejects values that JSON would silently
+ * erase or reinterpret. Object keys are serialized directly instead of via an
+ * intermediate object so integer-looking keys remain in lexical order.
+ */
+export function canonicalJsonV3(value: unknown): string {
+  return serialize(value, new Set<object>());
+}
+
+export function sha256V3(value: string | Uint8Array): `sha256:${string}` {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+export interface FingerprintV3 {
+  algorithm: "hmac-sha256";
+  canonicalizer: typeof EVENT_V3_CANONICALIZER;
+  key_epoch: `pep_${string}`;
+  scope: "generation" | "root";
+  digest: `sha256:${string}`;
+}
+
+export interface FingerprintContextV3 {
+  epochId: `pep_${string}`;
+  epochKey: Uint8Array;
+  rootId: `root_${string}`;
+  generationId?: `gen_${string}`;
+}
+
+export function fingerprintV3(
+  context: FingerprintContextV3,
+  domain: string,
+  value: unknown,
+  scope: "generation" | "root" = "generation",
+): FingerprintV3 {
+  assertDomain(domain);
+  const rootKey = Buffer.from(
+    hkdfSync(
+      "sha256",
+      context.epochKey,
+      Buffer.from(context.epochId, "utf8"),
+      Buffer.from(`harnery:v3:root\0${context.rootId}`, "utf8"),
+      32,
+    ),
+  );
+  let comparisonKey = rootKey;
+  if (scope === "generation") {
+    if (!context.generationId) {
+      throw new Error("generation-scoped fingerprint requires a generation ID");
+    }
+    comparisonKey = Buffer.from(
+      hkdfSync(
+        "sha256",
+        rootKey,
+        Buffer.from(context.generationId, "utf8"),
+        Buffer.from("harnery:v3:generation", "utf8"),
+        32,
+      ),
+    );
+  }
+  const digest = createHmac("sha256", comparisonKey)
+    .update(`harnery:v3:${domain}\0`, "utf8")
+    .update(canonicalJsonV3(value), "utf8")
+    .digest("hex");
+  return {
+    algorithm: "hmac-sha256",
+    canonicalizer: EVENT_V3_CANONICALIZER,
+    key_epoch: context.epochId,
+    scope,
+    digest: `sha256:${digest}`,
+  };
+}
+
+export function normalizeNativeIdV3(
+  context: FingerprintContextV3,
+  namespace: string,
+  nativeId: string,
+): `hid_${string}` {
+  if (!/^[a-z][a-z0-9._-]{0,63}$/.test(namespace)) {
+    throw new Error("native ID namespace is invalid");
+  }
+  const rootKey = Buffer.from(
+    hkdfSync(
+      "sha256",
+      context.epochKey,
+      Buffer.from(context.epochId, "utf8"),
+      Buffer.from(`harnery:v3:root\0${context.rootId}`, "utf8"),
+      32,
+    ),
+  );
+  const digest = createHmac("sha256", rootKey)
+    .update(`harnery:v3:native-id\0${namespace}\0`, "utf8")
+    .update(nativeId.normalize("NFC"), "utf8")
+    .digest("hex");
+  return `hid_${digest}`;
+}
+
+function serialize(value: unknown, ancestors: Set<object>): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFC"));
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error("canonical JSON rejects non-finite numbers");
+    return JSON.stringify(Object.is(value, -0) ? 0 : value);
+  }
+  if (typeof value !== "object") {
+    throw new Error(`canonical JSON rejects ${typeof value}`);
+  }
+  if (ancestors.has(value)) throw new Error("canonical JSON rejects cycles");
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return `[${value.map((item) => serialize(item, ancestors)).join(",")}]`;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new Error("canonical JSON accepts only plain objects");
+    }
+    const normalized = new Map<string, unknown>();
+    for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+      const normalizedKey = key.normalize("NFC");
+      if (normalized.has(normalizedKey)) {
+        throw new Error("canonical JSON key collision after Unicode normalization");
+      }
+      normalized.set(normalizedKey, item);
+    }
+    const keys = [...normalized.keys()].sort(compareUtf16);
+    return `{${keys
+      .map((key) => `${JSON.stringify(key)}:${serialize(normalized.get(key), ancestors)}`)
+      .join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function compareUtf16(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function assertDomain(domain: string): void {
+  if (!/^[a-z][a-z0-9._-]{0,63}$/.test(domain)) {
+    throw new Error("fingerprint domain is invalid");
+  }
+}

package/src/core/events/v3/capabilities.ts

@@ -0,0 +1,171 @@
+import type { Adapter } from "../../adapter.ts";
+import { canonicalJsonV3, sha256V3 } from "./canonical.ts";
+
+export type CapabilitySupportV3 = "native" | "derived" | "conditional" | "unsupported";
+
+export type CursorExecutionModeV3 = "local" | "cloud" | "unknown";
+
+export type AdapterWaitKindV3 =
+  | "permission"
+  | "needs_input"
+  | "decision"
+  | "approval"
+  | "scheduled"
+  | "rate_limit"
+  | "unknown";
+
+export type BaseAdapterSignalV3 =
+  | "session_start"
+  | "session_end"
+  | "prompt"
+  | "turn_id"
+  | "turn_completion"
+  | "tool_request"
+  | "tool_result"
+  | "tool_failure"
+  | "tool_call_id"
+  | "tool_duration"
+  | "permission"
+  | "subagent"
+  | "shell"
+  | "pre_compaction"
+  | "post_compaction"
+  | "context_usage"
+  | "model_identity";
+
+export type AdapterSignalV3 =
+  | BaseAdapterSignalV3
+  | "model_usage"
+  | "inference_timing"
+  | "harness_timing"
+  | "capability_drift";
+
+export interface AdapterCapabilityProfileV3 {
+  format: "harnery-v3-adapter-capabilities";
+  format_version: 1;
+  adapter: Adapter;
+  signals: Record<AdapterSignalV3, CapabilitySupportV3>;
+}
+
+const SHARED_SIGNAL_SUPPORT = {
+  session_start: "native",
+  prompt: "native",
+  turn_completion: "native",
+  tool_request: "native",
+  tool_result: "native",
+  tool_failure: "native",
+  tool_call_id: "native",
+  tool_duration: "derived",
+  subagent: "native",
+  shell: "native",
+  pre_compaction: "native",
+  model_identity: "conditional",
+} as const;
+
+const BASE_SIGNAL_SUPPORT: Record<Adapter, Record<BaseAdapterSignalV3, CapabilitySupportV3>> = {
+  "claude-code": {
+    ...SHARED_SIGNAL_SUPPORT,
+    session_end: "native",
+    turn_id: "conditional",
+    permission: "native",
+    post_compaction: "native",
+    context_usage: "unsupported",
+  },
+  codex: {
+    ...SHARED_SIGNAL_SUPPORT,
+    session_end: "native",
+    turn_id: "native",
+    permission: "native",
+    post_compaction: "native",
+    context_usage: "unsupported",
+  },
+  cursor: {
+    ...SHARED_SIGNAL_SUPPORT,
+    session_end: "native",
+    turn_id: "unsupported",
+    tool_request: "conditional",
+    tool_result: "conditional",
+    tool_failure: "conditional",
+    tool_call_id: "conditional",
+    tool_duration: "conditional",
+    shell: "conditional",
+    permission: "conditional",
+    post_compaction: "unsupported",
+    context_usage: "unsupported",
+  },
+};
+
+function profile(
+  adapter: Adapter,
+  economics: Pick<Record<AdapterSignalV3, CapabilitySupportV3>, "model_usage" | "inference_timing">,
+): AdapterCapabilityProfileV3 {
+  return {
+    format: "harnery-v3-adapter-capabilities",
+    format_version: 1,
+    adapter,
+    signals: {
+      ...BASE_SIGNAL_SUPPORT[adapter],
+      ...economics,
+      harness_timing: "derived",
+      capability_drift: "derived",
+    },
+  };
+}
+
+export const ADAPTER_CAPABILITY_PROFILES_V3: Record<Adapter, AdapterCapabilityProfileV3> = {
+  "claude-code": profile("claude-code", {
+    model_usage: "conditional",
+    inference_timing: "unsupported",
+  }),
+  codex: profile("codex", {
+    model_usage: "conditional",
+    inference_timing: "unsupported",
+  }),
+  cursor: profile("cursor", {
+    model_usage: "unsupported",
+    inference_timing: "unsupported",
+  }),
+};
+
+export function adapterCapabilityProfileV3(adapter: Adapter): AdapterCapabilityProfileV3 {
+  return ADAPTER_CAPABILITY_PROFILES_V3[adapter];
+}
+
+export function adapterCapabilityProfileDigestV3(adapter: Adapter): `cap_${string}` {
+  return `cap_${sha256V3(canonicalJsonV3(adapterCapabilityProfileV3(adapter))).slice(7)}`;
+}
+
+export function adapterSignalSupportV3(
+  adapter: Adapter,
+  signal: AdapterSignalV3,
+): CapabilitySupportV3 {
+  return adapterCapabilityProfileV3(adapter).signals[signal];
+}
+
+/**
+ * Adapter hooks only expose permission waits today. Other wait kinds can be
+ * authored by coordination producers, but they are not observable from an
+ * adapter's native turn channel.
+ */
+export function adapterWaitKindSupportV3(
+  adapter: Adapter,
+  kind: AdapterWaitKindV3,
+): CapabilitySupportV3 {
+  return kind === "permission" ? adapterSignalSupportV3(adapter, "permission") : "unsupported";
+}
+
+/** No current adapter supplies an independent completed-turn wait aggregate. */
+export function adapterTurnWaitCountSupportV3(_adapter: Adapter): CapabilitySupportV3 {
+  return "unsupported";
+}
+
+/**
+ * Local Cursor sessions expose the generic tool channel. Cloud/private-worker
+ * sessions cannot guarantee whole-turn delivery because hooks may start only
+ * after the execution environment becomes writable.
+ */
+export function cursorToolChannelSupportV3(mode: CursorExecutionModeV3): CapabilitySupportV3 {
+  if (mode === "local") return "native";
+  if (mode === "cloud") return "unsupported";
+  return "conditional";
+}