@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/capability-binding.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { CapabilityKind, Feature } from '@kindgi/capabilities';
+import type { Cursor, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the capability catalog — part of the admin
+ * control plane.
+ *
+ * Capabilities are **read-only** over HTTP. They are framework-declared
+ * (see `@kindgi/specs/capability.schema.json` + the `FEATURES` enum from
+ * `@kindgi/capabilities`) and deployment-extensible at boot time via
+ * this binding — never tenant-created via the API. Deployments that
+ * expose custom capability kinds (embedding, gpu-compute, sandbox-exec,
+ * browser-session, ...) plug a binding that also lists their extensions.
+ *
+ * Cursors are opaque — the binding chooses its encoding. The API layer
+ * only validates round-trip as a string; it never inspects the payload.
+ */
+export interface CapabilityRegistryBinding {
+  /**
+   * Cursor-paginated list of capability descriptors. Optional
+   * `featureFilter` is a prefix match on `descriptor.feature` — matches
+   * the `?feature=` filter shape on the route.
+   */
+  list(input: CapabilityListInput): Promise<CapabilityPage>;
+  /**
+   * Fetch a capability descriptor by its id, or `null` when unknown.
+   * The route surfaces `null` as `404 capability-not-found`.
+   */
+  get(input: CapabilityGetInput): Promise<CapabilityDescriptor | null>;
+}
+
+/**
+ * Wire shape returned by the capability routes. Lean by design — the
+ * runtime `Capability` (`@kindgi/capabilities.Capability`) is a
+ * declarative query shape (needs / prefer / budget) that agents attach
+ * to their spec; that's a different concept from a descriptor entry in
+ * the *catalog* of features a deployment supports. The catalog entry
+ * carries the identifier + human description + the optional params
+ * schema pointer.
+ *
+ * `id` is caller-chosen — for example `feature:<feature>`
+ * (e.g. `feature:tool-use`); deployments that extend
+ * the catalog with non-LLM capability kinds may pick other conventions
+ * (`kind:embedding`, `kind:sandbox-exec`, ...).
+ */
+export interface CapabilityDescriptor {
+  readonly id: string;
+  readonly feature: Feature | string;
+  readonly description: string;
+  /**
+   * Kind of resource the capability targets. Optional — absent value
+   * defaults to `'llm-inference'`. Adapters for non-LLM kinds set this
+   * explicitly so the catalog can be filtered by kind downstream.
+   */
+  readonly kind?: CapabilityKind;
+  /**
+   * Optional JSON Schema shape describing the parameters an agent may
+   * carry alongside `{ feature }` in a `Requirement`. Opaque to the API
+   * layer — the SDK surfaces it for tooling / doc generation.
+   */
+  readonly paramsSchema?: Readonly<Record<string, unknown>>;
+}
+
+export interface CapabilityListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Prefix match on `CapabilityDescriptor.feature`. */
+  readonly featureFilter?: string;
+}
+
+export interface CapabilityGetInput {
+  readonly tenantId: TenantId;
+  readonly capabilityId: string;
+}
+
+export interface CapabilityPage {
+  readonly data: readonly CapabilityDescriptor[];
+  readonly nextCursor?: Cursor;
+}

package/src/cost-binding.ts

@@ -0,0 +1,213 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, TenantId, Timestamp } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the cost readback plane — part of the
+ * admin control plane. Read-only: tenants + operators
+ * inspect what they've spent across model calls, tool invocations,
+ * storage, and sandbox usage. Instrumentation (how records get recorded)
+ * lives at the agent / tool / sandbox layers — this surface only reads.
+ *
+ * The runtime substrate is the cost tracker — usage records carrying
+ * `resourceKind`, `providerId`, `runId`, `quantity`, `unit`, `costUsd`,
+ * `metrics` and `attributes`, plus a `recordedAt` timestamp. But the wire
+ * vocabulary differs enough (`category` instead of `resourceKind`;
+ * first-class `agentId` / `conversationId` filters that live in
+ * `attributes` at storage time; multi-dim `groupBy` that needs
+ * storage-side rollups) that a caller-plugged binding is cleaner than
+ * direct storage access — each deployment maps wire fields to whatever
+ * storage shape it uses. Trivial in-memory implementations are fine for
+ * dev + tests; production implementations run the aggregate rollups in
+ * their store.
+ *
+ * Every method is tenant-scoped. Cursors are opaque — the binding
+ * chooses its encoding. The API layer only validates round-trip as a
+ * string; it never inspects the payload.
+ *
+ * Budgets are NOT part of this interface.
+ */
+export interface CostBinding {
+  /**
+   * Cursor-paginated list of cost records. Sort order is fixed:
+   * `occurredAt desc, id desc`. Filters compose (all AND).
+   */
+  listRecords(input: CostListRecordsInput): Promise<CostRecordPage>;
+  /**
+   * Fetch a record by id, or `null` when unknown. The route surfaces
+   * `null` as `404 cost-record-not-found`.
+   */
+  getRecord(input: CostGetRecordInput): Promise<CostRecord | null>;
+  /**
+   * Multi-dimensional aggregate rollup. `groupBy` may combine any
+   * subset of `agentId | runId | category | providerId | day | month
+   * | tenant | conversationId`; the binding returns one group per
+   * distinct key tuple within the required `from`..`to` window.
+   */
+  aggregate(input: CostAggregateInput): Promise<CostAggregateResult>;
+}
+
+// -------- listRecords --------
+
+export interface CostListRecordsInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly filter: CostRecordFilter;
+  /**
+   * Narrow the list to a specific scope. Absent = no scope narrow
+   * (return every row in the tenant the caller can see — admin/audit
+   * default).
+   *
+   * Content-scoped semantics (this binding — cost records attribute
+   * to the project whose run produced them):
+   * - `{ kind: 'project', projectId }` — rows in that project.
+   * - `{ kind: 'org', orgId }` — rows in every project belonging to
+   *   that org.
+   * - `{ kind: 'tenant', tenantId }` — every row in the tenant.
+   *
+   * Content rows always belong to a project, so `inherit` has no
+   * effect here.
+   */
+  readonly scope?: Scope;
+  /**
+   * `false` = literal-at-this-scope only (admin/audit view).
+   * `true` (default) = inheritance walk (user-facing view).
+   * No-op for content-scoped bindings (rows only exist at
+   * project-level — there is no upward hierarchy to walk). Kept for
+   * uniformity: scope-aware bindings share one filter shape.
+   */
+  readonly inherit?: boolean;
+}
+
+export interface CostRecordFilter {
+  readonly runId?: string;
+  readonly agentId?: string;
+  readonly conversationId?: string;
+  /**
+   * Wire vocabulary for the resource dimension — maps to the runtime's
+   * `resourceKind` (`llm.inference`, `tool.invocation`, `storage.write`,
+   * `sandbox.exec`, ...). Exact-match; free-form string so deployments
+   * can extend without a schema change.
+   */
+  readonly category?: string;
+  readonly providerId?: string;
+  readonly from?: Date;
+  readonly to?: Date;
+}
+
+export interface CostRecordPage {
+  readonly data: readonly CostRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+// -------- getRecord --------
+
+export interface CostGetRecordInput {
+  readonly tenantId: TenantId;
+  readonly recordId: string;
+}
+
+// -------- aggregate --------
+
+/**
+ * Group dimensions the binding may aggregate over. `day` / `month` are
+ * time bucketing on `occurredAt` (UTC calendar day / month). Every call
+ * is tenant-scoped, so `tenant` always resolves to the caller's tenant
+ * id.
+ */
+export type CostGroupDimension =
+  | 'agentId'
+  | 'runId'
+  | 'category'
+  | 'providerId'
+  | 'day'
+  | 'month'
+  | 'tenant'
+  | 'conversationId';
+
+export const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[] = [
+  'agentId',
+  'runId',
+  'category',
+  'providerId',
+  'day',
+  'month',
+  'tenant',
+  'conversationId',
+];
+
+export interface CostAggregateInput {
+  readonly tenantId: TenantId;
+  readonly groupBy: readonly CostGroupDimension[];
+  readonly from: Date;
+  readonly to: Date;
+  readonly filter?: CostRecordFilter;
+  /**
+   * Narrow the aggregate to a specific scope. Same semantics as
+   * `CostListRecordsInput.scope` — content-scoped; an org scope covers
+   * the org's projects. Lets `/v1/cost/aggregate` accept the same
+   * `?scopeKind + ?scopeId` triplet as `/v1/cost/records`. Without
+   * this, an aggregate call after a scoped list would drop the scope
+   * silently. `inherit` is a documented no-op for this content-scoped
+   * binding.
+   */
+  readonly scope?: Scope;
+  /**
+   * `false` = literal-at-this-scope only. `true` (default) = inheritance
+   * walk. No-op for content-scoped bindings; passed through for wire
+   * shape uniformity.
+   */
+  readonly inherit?: boolean;
+}
+
+/**
+ * One row of the aggregate result. `key` maps every requested `groupBy`
+ * dimension to its value for this group — `null` when the underlying
+ * records had no value for that dimension (e.g. records with no
+ * `agentId` when grouping by `agentId`). Downstream consumers treat
+ * `null` as a distinct group ("unattributed").
+ */
+export interface CostAggregateGroup {
+  readonly key: Readonly<Record<string, string | null>>;
+  readonly count: number;
+  readonly totalUsd: number;
+}
+
+export interface CostAggregateResult {
+  readonly groups: readonly CostAggregateGroup[];
+  readonly totalUsd: number;
+  readonly totalRecords: number;
+  readonly timeRange: {
+    readonly from: Timestamp;
+    readonly to: Timestamp;
+  };
+}
+
+// -------- CostRecord (wire) --------
+
+/**
+ * Wire shape for a single cost record. Corresponds 1:1 to a usage
+ * record in the runtime's cost tracker, flattened for the wire
+ * (`resourceKind` renamed to `category`; `attributes.agentId`
+ * / `attributes.conversationId` lifted to top-level fields when
+ * present). The binding decides how to reshape the runtime row — this
+ * type just describes what the route hands back.
+ */
+export interface CostRecord {
+  readonly id: string;
+  readonly tenantId: TenantId;
+  readonly category: string;
+  readonly providerId?: string;
+  readonly runId?: string;
+  readonly agentId?: string;
+  readonly conversationId?: string;
+  readonly quantity: number;
+  readonly unit: string;
+  readonly costUsd?: number;
+  readonly occurredAt: Timestamp;
+  readonly metrics?: Readonly<Record<string, unknown>>;
+  readonly attributes?: Readonly<Record<string, unknown>>;
+}

package/src/deployment-binding.ts

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Cursor, SigningKeyId, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the deployment ledger — the audit anchor
+ * row written by `POST /v1/deployments`. Mirrors the
+ * caller-plugged pattern of `BlobStorageBinding` /
+ * `PolicyRegistryBinding`: the API package does NOT own deployment
+ * storage. Deployments plug their own store (a database, or in-memory for
+ * tests) through this interface.
+ *
+ * Semantics:
+ *   - A deployment is the append-only record of a signed image landing
+ *     at the API. Its `imageDigest` (extracted from `imageRef`) is the
+ *     idempotency key — re-registering the same digest returns the
+ *     existing record with no new `artifactVersion`.
+ *   - The full signature envelope (`signerKeyId`, `signerPublicKey`,
+ *     `signature`, canonical `indexHash`) is persisted so regulators
+ *     can re-verify offline against the immutable image bytes.
+ *   - Primitive counts (`tools` / `guardrails` / `agents` / `flows`)
+ *     are captured for at-a-glance rendering; the full manifest set
+ *     lives at `imageRef@sha256:…/app/index.json`.
+ *
+ * Every method is tenant-scoped: callers pass `tenantId` explicitly so
+ * multi-tenant deployments can partition storage without exposing the
+ * scoping inside the API package.
+ *
+ * Cursors are opaque — the binding chooses its encoding. The API layer
+ * only validates that a cursor round-trips as a string.
+ *
+ * ## Seam only
+ *
+ * This file defines the seam the `packages/api/src/routes/deployments.ts`
+ * route calls; no implementation is bundled.
+ */
+export interface DeploymentBinding {
+  /**
+   * Persist a signed deployment record. The API route checks the signer
+   * against the trust list (`SigningKeyBinding.isTrusted`), verifies the
+   * Ed25519 signature, verifies image pullability
+   * (`ImageRegistryBinding.head`), and validates every primitive in the
+   * index before calling — the binding receives a well-formed input.
+   *
+   * Idempotent per `imageDigest`: when the same digest is re-registered
+   * under the same tenant the binding MUST return
+   * `{ kind: 'already-registered', deployment }` with the existing row
+   * (existing `artifactVersion` — the issuer-supplied value the row
+   * originally pinned). Different digest → new row with the caller's
+   * newly-supplied `artifactVersion` persisted verbatim.
+   */
+  register(input: DeploymentRegisterInput): Promise<DeploymentRegisterOutcome>;
+  /**
+   * Fetch a deployment by its server-allocated id. `null` when unknown
+   * to the tenant. The route surfaces `null` as `404
+   * deployment-not-found`.
+   */
+  get(input: DeploymentGetInput): Promise<Deployment | null>;
+  /**
+   * Fetch a deployment by its `imageDigest` (the sha256 of the pinned
+   * OCI image). Used for the idempotency check on `register` and for
+   * cross-referencing image identity from the sandbox layer at
+   * dispatch. `null` when no record exists.
+   */
+  getByImageDigest(input: DeploymentGetByImageDigestInput): Promise<Deployment | null>;
+  /**
+   * Cursor-paginated list, sorted by `activatedAt` descending
+   * (binding-defined tie-break, e.g. `deploymentId` desc). Filters
+   * compose as AND.
+   */
+  list(input: DeploymentListInput): Promise<DeploymentPage>;
+}
+
+// -------------------- record --------------------
+
+/**
+ * Wire shape for a deployment record. Immutable once written — every
+ * field is set atomically at `register` time.
+ *
+ * `signerPublicKey` is retained alongside `signerKeyId` so offline audit
+ * can re-verify without hitting the tenant's trust list; the trust-list
+ * check happens at `register` time inside the route (via
+ * `SigningKeyBinding.isTrusted`).
+ */
+export interface Deployment {
+  readonly deploymentId: string;
+  readonly tenantId: TenantId;
+  /** Full digest-pinned image reference, e.g. `registry.example.com/acme/pack@sha256:…`. */
+  readonly imageRef: string;
+  /** `sha256` hex-encoded digest extracted from `imageRef` (idempotency key). */
+  readonly imageDigest: string;
+  /**
+   * Issuer-supplied `YYYYMMDD.N` — matches the value inside the signed
+   * envelope. Bindings persist it verbatim; the
+   * signature is only offline-verifiable if the same bytes round-trip.
+   */
+  readonly artifactVersion: string;
+  /** `sha256` of the canonicalised `index.json` extracted from the image. */
+  readonly indexHash: string;
+  /** Which key signed the deploy. Cross-checked against `SigningKeyBinding`. */
+  readonly signerKeyId: SigningKeyId;
+  /** Retained for offline audit. Base64 of the raw public-key bytes. */
+  readonly signerPublicKey: string;
+  /** Base64 of the Ed25519 signature over the canonicalised envelope. */
+  readonly signature: string;
+  /** Issuer-supplied timestamp inside the signed envelope. ISO-8601. */
+  readonly publishedAt: string;
+  /** Server-side ledger timestamp — when `register` returned OK. ISO-8601. */
+  readonly activatedAt: string;
+  /**
+   * Counts of primitives in the deployment's `index.json`. Not
+   * authoritative — the image is. Populated for cheap admin rendering.
+   */
+  readonly primitives: DeploymentPrimitiveCounts;
+  /**
+   * Exactly what the deployment shipped: each primitive's id and, for
+   * the versioned ones, its version. Versions are immutable, so this is
+   * enough to know which code a deployment made live.
+   */
+  readonly contents: DeploymentContents;
+}
+
+/** A primitive a deployment shipped. Guardrails have no version. */
+export interface DeployedPrimitive {
+  readonly id: string;
+  readonly version?: string;
+}
+
+export interface DeploymentContents {
+  readonly tools: readonly DeployedPrimitive[];
+  readonly guardrails: readonly DeployedPrimitive[];
+  readonly agents: readonly DeployedPrimitive[];
+  readonly flows: readonly DeployedPrimitive[];
+}
+
+export interface DeploymentPrimitiveCounts {
+  readonly tools: number;
+  readonly guardrails: number;
+  readonly agents: number;
+  readonly flows: number;
+}
+
+// -------------------- register --------------------
+
+/**
+ * Everything the ledger needs to persist a signed deployment. The route
+ * assembles this from the request body + verified sig envelope; the
+ * binding does not re-verify the signature (that's the route's job).
+ */
+export interface DeploymentRegisterInput {
+  readonly tenantId: TenantId;
+  readonly imageRef: string;
+  readonly imageDigest: string;
+  /**
+   * Issuer-supplied `YYYYMMDD.N`. Part of the canonical signed envelope
+   * — persisted verbatim so offline verification
+   * can reproduce the exact bytes.
+   */
+  readonly artifactVersion: string;
+  readonly indexHash: string;
+  readonly signerKeyId: SigningKeyId;
+  readonly signerPublicKey: string;
+  readonly signature: string;
+  readonly publishedAt: string;
+  readonly primitives: DeploymentPrimitiveCounts;
+  readonly contents: DeploymentContents;
+}
+
+export type DeploymentRegisterOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly deployment: Deployment;
+    }
+  | {
+      /**
+       * Same `imageDigest` was already registered for this tenant. The
+       * binding returns the existing row unchanged; the route surfaces
+       * as `200 OK` (idempotent replay), NOT `409`.
+       */
+      readonly kind: 'already-registered';
+      readonly deployment: Deployment;
+    }
+  | {
+      /** Any other write failure — persistence error, invalid input. */
+      readonly kind: 'error';
+      readonly code: string;
+      readonly message: string;
+    };
+
+// -------------------- get --------------------
+
+export interface DeploymentGetInput {
+  readonly tenantId: TenantId;
+  readonly deploymentId: string;
+}
+
+export interface DeploymentGetByImageDigestInput {
+  readonly tenantId: TenantId;
+  readonly imageDigest: string;
+}
+
+// -------------------- list --------------------
+
+export interface DeploymentListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /**
+   * Optional prefix filter on `Deployment.imageRef`. Useful for
+   * `registry.example.com/acme/support-pack@sha256:` matches within a
+   * multi-image tenant.
+   */
+  readonly imageRefPrefix?: string;
+  /**
+   * Restrict to a specific signing key. Useful for revocation audits —
+   * "which deploys did the compromised key sign?"
+   */
+  readonly signerKeyId?: SigningKeyId;
+}
+
+export interface DeploymentPage {
+  readonly data: readonly Deployment[];
+  readonly nextCursor?: Cursor;
+}

package/src/env-binding.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { Cursor, EnvName, Result } from '@kindgi/types';
+
+import type { ResolveContext } from './secrets-binding.js';
+
+export type { ResolveContext } from './secrets-binding.js';
+
+/**
+ * Caller-plugged env store — non-sensitive per-env values. Same
+ * `(scope, envName, name)` structural key as `SecretBinding`, same
+ * discriminated `Scope` primitive from `@kindgi/platform`.
+ * Emits `env-resolved` compliance-evidence events on every `resolve`
+ * — symmetric with secrets, gives operators the same debugging
+ * superpower ("what did this run see for its env at start?").
+ *
+ * What differs from `SecretBinding`:
+ *   - `value` returns on the wire (env is non-sensitive by
+ *     definition); no capability gate on read.
+ *   - Revision counter, not version-with-rotation-ceremony. Overwrite
+ *     bumps `revision`; there's no revoke, no hard-delete, no
+ *     rotation-workflow-with-async-completion.
+ *   - No encryption at rest.
+ *
+ * Env-safety: cross-env reads are refused. Same structural rule as
+ * secrets.
+ */
+export interface EnvBinding {
+  /** Cursor-paginated list. Returns `value` for every entry. */
+  list(input: EnvListInput): Promise<EnvListPage>;
+
+  /** Fetch a single entry. `null` when unknown. */
+  get(input: EnvGetInput): Promise<EnvRecord | null>;
+
+  /**
+   * Resolve at dispatch time. Same `ResolveContext` as secrets. Emits
+   * `env-resolved` compliance-evidence event on every call.
+   */
+  resolve(input: EnvResolveInput): Promise<Result<EnvResolveOutcome, EnvError>>;
+
+  /**
+   * Write / overwrite an env value. Every write bumps `revision`.
+   * `ifRevision` provides optimistic concurrency guard.
+   */
+  set(input: EnvSetInput): Promise<EnvSetOutcome>;
+
+  /**
+   * Idempotent delete. Returns `{ deleted: false }` on unknown key.
+   * No soft-delete — env is a plain overwrite-shaped store; delete
+   * means gone.
+   */
+  delete(input: EnvDeleteInput): Promise<EnvDeleteOutcome>;
+}
+
+export interface EnvRecord {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly value: string;
+  readonly revision: number;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly tags?: Readonly<Record<string, string>>;
+}
+
+export interface EnvListInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  readonly namePrefix?: string;
+  readonly tagFilter?: Readonly<Record<string, string>>;
+}
+
+export interface EnvListPage {
+  readonly data: readonly EnvRecord[];
+  readonly nextCursor?: Cursor;
+}
+
+export interface EnvGetInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+}
+
+export interface EnvResolveInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly resolveContext: ResolveContext;
+}
+
+export interface EnvResolveOutcome {
+  readonly name: string;
+  readonly value: string;
+  readonly revision: number;
+}
+
+export interface EnvSetInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+  readonly value: string;
+  readonly tags?: Readonly<Record<string, string>>;
+  readonly ifRevision?: number;
+  /**
+   * REQUIRED. Called inside the binding's write tx on FRESH insert
+   * (new env-var identity). Receives the new entry's id as the FGA
+   * subject id. Not invoked on revision-update (identity already exists).
+   * See `AgentPublishInput.enqueueTuples` for the design rationale.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export type EnvSetOutcome =
+  | { readonly kind: 'ok'; readonly record: EnvRecord }
+  | { readonly kind: 'revision-conflict'; readonly currentRevision: number }
+  | { readonly kind: 'error'; readonly code: string; readonly message: string };
+
+export interface EnvDeleteInput {
+  readonly scope: Scope;
+  readonly envName: EnvName;
+  readonly name: string;
+}
+
+export interface EnvDeleteOutcome {
+  readonly deleted: boolean;
+}
+
+export type EnvError =
+  | { readonly code: 'env-not-found'; readonly message: string; readonly name: string }
+  | {
+      readonly code: 'env-write-conflict';
+      readonly message: string;
+      readonly currentRevision: number;
+    }
+  | { readonly code: 'env-store-error'; readonly message: string; readonly cause?: unknown };