@abelxiaoxing/cadence 1.8.4 → 2.0.1

package/src/service/contracts/active.ts

@@ -0,0 +1,82 @@
+/** Bounded current original-work roster, separate from historical run reduction. */
+import {
+  canonicalJson,
+  closed,
+  decodeId,
+  decodePublicError,
+  invalid,
+  LIMITS,
+  list,
+  literal,
+  oneOf,
+  type PublicError,
+} from "./core.ts";
+export interface ActiveRunRef {
+  taskId: string;
+  runId: string;
+  operationId: string;
+  epoch: string;
+  kind: "start" | "generate-plan" | "check";
+  stage: "accepted-unallocated" | "active" | "draining";
+}
+export type ActiveRuns = {
+  storeId: string;
+  workspaceId: string;
+  epoch: string;
+} & (
+  | { status: "complete"; runs: ActiveRunRef[] }
+  | { status: "unavailable"; error: PublicError }
+);
+export function decodeActiveRuns(v: unknown): ActiveRuns {
+  canonicalJson({ kind: "ok", value: v }, LIMITS.pageBytes);
+  const complete =
+    Object.getOwnPropertyDescriptor(v ?? {}, "status")?.value === "complete";
+  const o = closed(v, [
+    "storeId",
+    "workspaceId",
+    "epoch",
+    "status",
+    complete ? "runs" : "error",
+  ]);
+  const base = {
+    storeId: decodeId(o.storeId),
+    workspaceId: decodeId(o.workspaceId),
+    epoch: decodeId(o.epoch),
+  };
+  if (!complete) {
+    literal(o.status, "unavailable");
+    return { ...base, status: "unavailable", error: noEffect(o.error) };
+  }
+  const runs = list(o.runs, LIMITS.episodes, (v): ActiveRunRef => {
+    const r = closed(v, [
+      "taskId",
+      "runId",
+      "operationId",
+      "epoch",
+      "kind",
+      "stage",
+    ]);
+    return {
+      taskId: decodeId(r.taskId),
+      runId: decodeId(r.runId),
+      operationId: decodeId(r.operationId),
+      epoch: decodeId(r.epoch),
+      kind: oneOf(r.kind, ["start", "generate-plan", "check"]),
+      stage: oneOf(r.stage, ["accepted-unallocated", "active", "draining"]),
+    };
+  });
+  if (
+    runs.some((r) => r.epoch !== base.epoch) ||
+    new Set(runs.map((r) => r.runId)).size !== runs.length ||
+    new Set(runs.map((r) => r.taskId)).size !== runs.length ||
+    new Set(runs.map((r) => r.operationId)).size !== runs.length
+  )
+    invalid();
+  return { ...base, status: "complete", runs };
+}
+
+function noEffect(v: unknown): PublicError {
+  const error = decodePublicError(v);
+  literal(error.effect, "none");
+  return error;
+}

package/src/service/contracts/budget.ts

@@ -0,0 +1,148 @@
+import {
+  type CaptureBudget,
+  decodeCaptureBudget,
+  decodeRecordingInput,
+  type PublicRecordingInput,
+} from "./capture.ts";
+import { ContractError, canonicalJson, LIMITS, utf8Bytes } from "./core.ts";
+import {
+  decodeOwnerRecordingInput,
+  type OwnerRecordingInput,
+} from "./history.ts";
+
+/** Resource accounting only: no persistence, accepting sink, scheduler or timer.
+ * One instance per W3 child/owner ingress. The caller must reserve BEFORE copying
+ * source values. Bytes mean encoded-data/retention budgets, not total JS heap.
+ */
+export class CaptureBudgetPool {
+  private leases = new Set<CaptureBudgetLease>();
+  reserve(input: CaptureBudget): CaptureBudgetLease {
+    const budget = decodeCaptureBudget(input);
+    const lease = new CaptureBudgetLease(
+      (next) => this.check(lease, next),
+      () => {
+        this.leases.delete(lease);
+      },
+      budget,
+    );
+    this.check(lease, budget);
+    this.leases.add(lease);
+    return lease;
+  }
+  get accounting(): {
+    leases: number;
+    bytes: number;
+    sourceFrames: number;
+    outputChunks: number;
+  } {
+    const values = [...this.leases].map((l) => l.budget);
+    return {
+      leases: values.length,
+      bytes: values.reduce((n, b) => n + b.retainedBytes + b.outputBytes, 0),
+      sourceFrames: values.reduce((n, b) => n + b.sourceFrames, 0),
+      outputChunks: values.reduce((n, b) => n + b.outputChunks, 0),
+    };
+  }
+  /** Internal lease update: replacement is checked before any accounting mutation. */
+  private check(lease: CaptureBudgetLease, budget: CaptureBudget): void {
+    const values = [...this.leases]
+      .filter((l) => l !== lease)
+      .map((l) => l.budget)
+      .concat(budget);
+    const fits = (items: CaptureBudget[], bytes: number, frames: number) =>
+      items.reduce((n, b) => n + b.retainedBytes + b.outputBytes, 0) <= bytes &&
+      // Source and transformed events share the SAME frame ceiling while both
+      // are retained. A prefix-only/empty lease still occupies one slot.
+      items.reduce(
+        (n, b) => n + Math.max(1, b.sourceFrames + b.outputChunks),
+        0,
+      ) <= frames;
+    if (
+      !fits(values, LIMITS.ownerQueueBytes, LIMITS.ownerQueueFrames) ||
+      !fits(
+        values.filter((b) => b.lane === "data"),
+        LIMITS.ownerQueueBytes - LIMITS.ownerControlBytes,
+        LIMITS.ownerQueueFrames - LIMITS.ownerControlFrames,
+      )
+    )
+      throw new ContractError("capacity");
+  }
+}
+class CaptureBudgetLease {
+  private state: "reserved" | "in-flight" | "released" = "reserved";
+  constructor(
+    private readonly resize: (budget: CaptureBudget) => void,
+    private readonly forget: () => void,
+    private value: CaptureBudget,
+  ) {}
+  get budget(): CaptureBudget {
+    return { ...this.value };
+  }
+  grow(input: CaptureBudget): void {
+    if (this.state !== "reserved") throw new ContractError("conflict");
+    const extra = decodeCaptureBudget(input);
+    if (extra.lane !== this.value.lane) throw new ContractError("invalid");
+    const next = decodeCaptureBudget({
+      lane: extra.lane,
+      sourceFrames: extra.sourceFrames + this.value.sourceFrames,
+      retainedBytes: extra.retainedBytes + this.value.retainedBytes,
+      outputBytes: extra.outputBytes + this.value.outputBytes,
+      outputChunks: extra.outputChunks + this.value.outputChunks,
+    });
+    this.resize(next);
+    this.value = next;
+  }
+  beginWorker(input: PublicRecordingInput): PublicRecordingInput {
+    if (this.state !== "reserved") throw new ContractError("conflict");
+    this.size(input);
+    const value = decodeRecordingInput(input);
+    this.chunks(value.events.length);
+    if (
+      this.value.lane === "control" &&
+      value.events.some(
+        (e) =>
+          !["ready", "capture-status", "worker-failure", "final"].includes(
+            e.event.kind,
+          ),
+      )
+    )
+      throw new ContractError("invalid");
+    this.state = "in-flight";
+    return value;
+  }
+  beginOwner(input: OwnerRecordingInput): OwnerRecordingInput {
+    if (this.state !== "reserved") throw new ContractError("conflict");
+    this.size(input);
+    const value = decodeOwnerRecordingInput(input);
+    this.chunks(value.events.length);
+    if (
+      this.value.sourceFrames !== 0 ||
+      (this.value.lane === "control" &&
+        value.events.some((e) => e.kind !== "fact"))
+    )
+      throw new ContractError("invalid");
+    this.state = "in-flight";
+    return value;
+  }
+  private size(input: unknown): void {
+    // No unreserved decoded copy is retained: check encoded output ceiling first.
+    if (
+      utf8Bytes(canonicalJson(input, this.value.outputBytes)) >
+      this.value.outputBytes
+    )
+      throw new ContractError("capacity");
+  }
+  private chunks(count: number): void {
+    if (count > this.value.outputChunks) throw new ContractError("capacity");
+  }
+  release(): void {
+    if (this.state !== "reserved") throw new ContractError("conflict");
+    this.state = "released";
+    this.forget();
+  }
+  settled(): void {
+    if (this.state !== "in-flight") throw new ContractError("conflict");
+    this.state = "released";
+    this.forget();
+  }
+}

package/src/service/contracts/build.ts

@@ -0,0 +1,67 @@
+/** Compatibility is independent of authentication and of task confirmation. */
+import { closed, decodeHash, oneOf } from "./core.ts";
+export interface BrowserBuild {
+  sourceHash: string;
+  contractHash: string;
+  buildId: string;
+}
+export type ClientBuild =
+  | { kind: "native"; contractHash: string }
+  | ({ kind: "browser" } & BrowserBuild);
+export interface ServiceBuild {
+  contractHash: string;
+  assets: BrowserBuild;
+}
+export function decodeBrowserBuild(value: unknown): BrowserBuild {
+  const o = closed(value, ["sourceHash", "contractHash", "buildId"]);
+  return {
+    sourceHash: decodeHash(o.sourceHash),
+    contractHash: decodeHash(o.contractHash),
+    buildId: decodeHash(o.buildId),
+  };
+}
+export function decodeClientBuild(value: unknown): ClientBuild {
+  const kind = oneOf(
+    Object.getOwnPropertyDescriptor(value ?? {}, "kind")?.value,
+    ["native", "browser"],
+  );
+  const o = closed(
+    value,
+    kind === "native"
+      ? ["kind", "contractHash"]
+      : ["kind", "contractHash", "sourceHash", "buildId"],
+  );
+  return kind === "native"
+    ? { kind, contractHash: decodeHash(o.contractHash) }
+    : {
+        kind,
+        ...decodeBrowserBuild({
+          contractHash: o.contractHash,
+          sourceHash: o.sourceHash,
+          buildId: o.buildId,
+        }),
+      };
+}
+export function decodeServiceBuild(value: unknown): ServiceBuild {
+  const o = closed(value, ["contractHash", "assets"]);
+  return {
+    contractHash: decodeHash(o.contractHash),
+    assets: decodeBrowserBuild(o.assets),
+  };
+}
+export function compatibleBuild(
+  server: ServiceBuild | undefined,
+  client: ClientBuild | null,
+  safety = false,
+): boolean {
+  return (
+    !!server &&
+    !!client &&
+    client.contractHash === server.contractHash &&
+    (safety ||
+      (server.assets.contractHash === server.contractHash &&
+        (client.kind === "native" ||
+          (client.buildId === server.assets.buildId &&
+            client.sourceHash === server.assets.sourceHash))))
+  );
+}

package/src/service/contracts/capture.ts

@@ -0,0 +1,48 @@
+/** Compatibility import path only; worker-public.mjs owns the executable codec and declarations. */
+export {
+  advanceCapture,
+  type CallDeclarationLink,
+  type CaptureBudget,
+  type CaptureEvent,
+  type CaptureFrame,
+  type CapturePosition,
+  type CheckNativeSettlement,
+  type CommittedBatch,
+  type ContentOwner,
+  callLink,
+  childSatisfied,
+  type DetailCommit,
+  type DetailDescriptor,
+  decodeCaptureBudget,
+  decodeCaptureEvent,
+  decodeCaptureFrame,
+  decodeCheckNativeSettlement,
+  decodeCommittedBatch,
+  decodeContentOwner,
+  decodeDetailCommit,
+  decodeDetailDescriptor,
+  decodeFinalRecording,
+  decodeFinalSelection,
+  decodeOmittedBlock,
+  decodeRecordingEvent,
+  decodeRecordingInput,
+  decodeRecordingLink,
+  decodeRunSettlement,
+  decodeSourceIdentity,
+  decodeSourceRange,
+  decodeWorkerCompletion,
+  type FinalRecording,
+  type FinalSelection,
+  type OmittedBlock,
+  type OwnerDetailCommit,
+  type PublicRecordingInput,
+  type RecordingEvent,
+  type RecordingLink,
+  type RequiredChildSettlement,
+  type RunSettlement,
+  type SanitizedCaptureEvent,
+  type SourceIdentity,
+  type SourceRange,
+  settlementOutcome,
+  type WorkerCompletion,
+} from "../../worker-public.mjs";

package/src/service/contracts/core.ts

@@ -0,0 +1,33 @@
+/** Compatibility import path only; worker-public.mjs owns the executable codec and declarations. */
+export {
+  assignmentId,
+  bool,
+  ContractError,
+  canonicalJson,
+  closed,
+  compareSequence,
+  decodeHash,
+  decodeId,
+  decodePublicError,
+  decodeSequence,
+  ERROR_CODES,
+  type ErrorCode,
+  EXPORT_SCHEMA,
+  errorStatus,
+  GRAPH_SCHEMA,
+  HISTORY_SCHEMA,
+  integer,
+  invalid,
+  LIMITS,
+  list,
+  literal,
+  nullable,
+  oneOf,
+  type PublicError,
+  parseWireJson,
+  publicError,
+  SERVICE_PROTOCOL,
+  text,
+  utf8Bytes,
+  WORKER_PROTOCOL,
+} from "../../worker-public.mjs";

package/src/service/contracts/current.ts

@@ -0,0 +1,261 @@
+/** Current owner observations, never retained-content or execution authority by inference. */
+
+import { role } from "../../worker-public.mjs";
+import {
+  bool,
+  canonicalJson,
+  closed,
+  decodeHash,
+  decodeId,
+  decodePublicError,
+  decodeSequence,
+  integer,
+  invalid,
+  LIMITS,
+  list,
+  literal,
+  nullable,
+  oneOf,
+  type PublicError,
+  text,
+} from "./core.ts";
+import {
+  type CaptureCoverage,
+  decodeCoverage,
+  type RoleSelection,
+  type TaskKind,
+} from "./domain.ts";
+import {
+  type ControlContext,
+  controlTask,
+  controlWorkspace,
+  decodeControlContext,
+  decodeGraphReadRequest,
+  type GraphReadRequest,
+  type ObservationFact,
+} from "./history.ts";
+
+export interface CurrentRequest {
+  storeId: string;
+  taskId: string | null;
+}
+export interface CurrentTask {
+  id: string;
+  kind: TaskKind;
+  revision: number;
+  identity: string;
+}
+export type SavedGraphSelection =
+  | { status: "none" }
+  | { status: "saved"; request: GraphReadRequest; planRevision: number }
+  | { status: "unavailable"; error: PublicError };
+export interface CurrentView {
+  request: CurrentRequest;
+  workspaceId: string;
+  epoch: string;
+  committedSeq: string;
+  context: ControlContext;
+  task: CurrentTask | null;
+  roles: RoleSelection[];
+  readablePlan: null | {
+    source: "current-v1";
+    text: string;
+    editable: boolean;
+    coverage: CaptureCoverage;
+  };
+  savedGraph: SavedGraphSelection;
+}
+export interface CurrentChanges {
+  request: CurrentRequest;
+  workspaceId: string;
+  epoch: string;
+  committedSeq: string;
+  context: ControlContext;
+  task: CurrentTask;
+  observation: ObservationFact;
+  text: string;
+  git: boolean;
+  coverage: CaptureCoverage;
+}
+const noEffect = (v: unknown) => {
+  const error = decodePublicError(v);
+  literal(error.effect, "none");
+  return error;
+};
+export function decodeCurrentRequest(v: unknown): CurrentRequest {
+  const o = closed(v, ["storeId", "taskId"]);
+  return { storeId: decodeId(o.storeId), taskId: nullable(o.taskId, decodeId) };
+}
+export function decodeCurrentChangesRequest(v: unknown): CurrentRequest {
+  const request = decodeCurrentRequest(v);
+  if (request.taskId === null) invalid();
+  return request;
+}
+function currentTask(v: unknown): CurrentTask {
+  const o = closed(v, ["id", "kind", "revision", "identity"]);
+  return {
+    id: decodeId(o.id),
+    kind: oneOf(o.kind, ["code", "research", "diagnosis"]),
+    revision: integer(o.revision, 1),
+    identity: decodeHash(o.identity),
+  };
+}
+export function decodeCurrentRoles(v: unknown): RoleSelection[] {
+  const roles = list(v, 3, role);
+  if (roles.length !== 3 || new Set(roles.map((r) => r.role)).size !== 3)
+    invalid();
+  return roles;
+}
+function savedGraph(v: unknown): SavedGraphSelection {
+  const status = Object.getOwnPropertyDescriptor(v ?? {}, "status")?.value;
+  if (status === "none") {
+    closed(v, ["status"]);
+    return { status };
+  }
+  if (status === "saved") {
+    const o = closed(v, ["status", "request", "planRevision"]);
+    return {
+      status,
+      request: decodeGraphReadRequest(o.request),
+      planRevision: integer(o.planRevision, 1),
+    };
+  }
+  const o = closed(v, ["status", "error"]);
+  literal(o.status, "unavailable");
+  return { status: "unavailable", error: noEffect(o.error) };
+}
+function correlate(v: {
+  request: CurrentRequest;
+  workspaceId: string;
+  epoch: string;
+  context: ControlContext;
+  task: CurrentTask | null;
+}) {
+  if (
+    v.request.taskId !== (v.task?.id ?? null) ||
+    controlWorkspace(v.context) !== v.workspaceId ||
+    controlTask(v.context) !== v.request.taskId
+  )
+    invalid();
+  if (v.context.status === "available") {
+    const c = v.context.version;
+    if (
+      c.epoch !== v.epoch ||
+      !!c.task !== !!v.task ||
+      (v.task &&
+        (c.task?.revision !== v.task.revision ||
+          c.task.identity !== v.task.identity ||
+          c.task.kind !== v.task.kind))
+    )
+      invalid();
+  }
+}
+export function decodeCurrentView(v: unknown): CurrentView {
+  canonicalJson({ kind: "ok", value: v }, LIMITS.pageBytes);
+  const o = closed(v, [
+    "request",
+    "workspaceId",
+    "epoch",
+    "committedSeq",
+    "context",
+    "task",
+    "roles",
+    "readablePlan",
+    "savedGraph",
+  ]);
+  const result: CurrentView = {
+    request: decodeCurrentRequest(o.request),
+    workspaceId: decodeId(o.workspaceId),
+    epoch: decodeId(o.epoch),
+    committedSeq: decodeSequence(o.committedSeq),
+    context: decodeControlContext(o.context),
+    task: nullable(o.task, currentTask),
+    roles: decodeCurrentRoles(o.roles),
+    savedGraph: savedGraph(o.savedGraph),
+    readablePlan: nullable(o.readablePlan, (v) => {
+      const p = closed(v, ["source", "text", "editable", "coverage"]);
+      const coverage = decodeCoverage(p.coverage),
+        editable = bool(p.editable);
+      if (
+        editable &&
+        (coverage.redacted ||
+          coverage.observed !== "complete" ||
+          coverage.source !== "complete" ||
+          coverage.omissions.length)
+      )
+        invalid();
+      return {
+        source: literal(p.source, "current-v1"),
+        text: text(p.text, 32768),
+        editable,
+        coverage,
+      };
+    }),
+  };
+  correlate(result);
+  if (!!result.task !== !!result.readablePlan) invalid();
+  const saved = result.savedGraph;
+  if (
+    saved.status === "saved" &&
+    (saved.request.storeId !== result.request.storeId ||
+      saved.request.scope.kind !== "task" ||
+      saved.request.scope.id !== result.task?.id ||
+      saved.request.snapshotSeq !== result.committedSeq ||
+      (result.context.status === "available" &&
+        (saved.request.graph.sha256 !==
+          result.context.version.task?.graphIdentity ||
+          saved.request.graph.revision !==
+            result.context.version.task?.graphRevision)))
+  )
+    invalid();
+  if (saved.status === "unavailable" && result.context.status === "available")
+    invalid();
+  return result;
+}
+export function decodeCurrentChanges(v: unknown): CurrentChanges {
+  canonicalJson({ kind: "ok", value: v }, LIMITS.pageBytes);
+  const o = closed(v, [
+    "request",
+    "workspaceId",
+    "epoch",
+    "committedSeq",
+    "context",
+    "task",
+    "observation",
+    "text",
+    "git",
+    "coverage",
+  ]);
+  const f = closed(o.observation, [
+    "identity",
+    "complete",
+    "checkoutGeneration",
+  ]);
+  const result: CurrentChanges = {
+    request: decodeCurrentChangesRequest(o.request),
+    workspaceId: decodeId(o.workspaceId),
+    epoch: decodeId(o.epoch),
+    committedSeq: decodeSequence(o.committedSeq),
+    context: decodeControlContext(o.context),
+    task: currentTask(o.task),
+    observation: {
+      identity: decodeHash(f.identity),
+      complete: bool(f.complete),
+      checkoutGeneration: integer(f.checkoutGeneration, 0),
+    },
+    text: text(o.text, 128 * 1024),
+    git: bool(o.git),
+    coverage: decodeCoverage(o.coverage),
+  };
+  correlate(result);
+  if (result.context.status === "available") {
+    const c = result.context.version;
+    if (
+      c.observation.identity !== result.observation.identity ||
+      c.observation.complete !== result.observation.complete ||
+      c.checkoutGeneration !== result.observation.checkoutGeneration
+    )
+      invalid();
+  }
+  return result;
+}

package/src/service/contracts/domain.ts

@@ -0,0 +1,68 @@
+/** Compatibility import path only; worker-public.mjs owns the executable codec and declarations. */
+export {
+  type Action,
+  type ActionPreview,
+  type Assignment,
+  assertWorkerEnvelopeSize,
+  type ByteRange,
+  type CancelCommand,
+  type CaptureCoverage,
+  type CheckSelection,
+  type Closure,
+  type Command,
+  type CommandIdentity,
+  type ContentRef,
+  type ContextVersion,
+  checkSelection,
+  closures,
+  type Dependency,
+  type DependencyHandoff,
+  type DependencySource,
+  decodeAction,
+  decodeCancel,
+  decodeCommand,
+  decodeCommandIdentity,
+  decodeContentRef,
+  decodeContext,
+  decodeCoverage,
+  decodeCursor,
+  decodeGraph,
+  decodeHandoff,
+  decodeModelSelection,
+  decodeModelSelector,
+  decodeNativeSettlement,
+  decodeNavigation,
+  decodePreflight,
+  decodePreflightRequest,
+  decodePreview,
+  decodeScope,
+  decodeWorkerPublicRequest,
+  dependency,
+  type ExecutionOutcome,
+  type Field,
+  fields,
+  type Graph,
+  type HandoffInput,
+  type Issue,
+  type ModelSelection,
+  type ModelSelector,
+  modelApis,
+  type NativeSettlement,
+  outcomes,
+  type Preflight,
+  type PreflightRequest,
+  type Publication,
+  type Purpose,
+  type ReadCursor,
+  type RoleSelection,
+  range,
+  role,
+  roleForPurpose,
+  type Scope,
+  type TaskKind,
+  type TaskVersion,
+  tag,
+  taskVersion,
+  thinkingLevels,
+  type WorkerPublicRequest,
+} from "../../worker-public.mjs";