@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/dist/cost-binding.d.ts

@@ -0,0 +1,175 @@
+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>;
+}
+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;
+}
+export interface CostGetRecordInput {
+    readonly tenantId: TenantId;
+    readonly recordId: string;
+}
+/**
+ * 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 declare const COST_GROUP_DIMENSIONS: readonly CostGroupDimension[];
+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;
+    };
+}
+/**
+ * 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>>;
+}
+//# sourceMappingURL=cost-binding.d.ts.map

package/dist/cost-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-binding.d.ts","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAClE;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACjE;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACpE;AAID,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,OAAO,GACP,UAAU,GACV,YAAY,GACZ,KAAK,GACL,OAAO,GACP,QAAQ,GACR,gBAAgB,CAAC;AAErB,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAS9D,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QACzB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;KACxB,CAAC;CACH;AAID;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD"}

package/dist/cost-binding.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export const COST_GROUP_DIMENSIONS = [
+    'agentId',
+    'runId',
+    'category',
+    'providerId',
+    'day',
+    'month',
+    'tenant',
+    'conversationId',
+];
+//# sourceMappingURL=cost-binding.js.map

package/dist/cost-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-binding.js","sourceRoot":"","sources":["../src/cost-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAiIjC,MAAM,CAAC,MAAM,qBAAqB,GAAkC;IAClE,SAAS;IACT,OAAO;IACP,UAAU;IACV,YAAY;IACZ,KAAK;IACL,OAAO;IACP,QAAQ;IACR,gBAAgB;CACjB,CAAC"}

package/dist/deployment-binding.d.ts

@@ -0,0 +1,201 @@
+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>;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+};
+export interface DeploymentGetInput {
+    readonly tenantId: TenantId;
+    readonly deploymentId: string;
+}
+export interface DeploymentGetByImageDigestInput {
+    readonly tenantId: TenantId;
+    readonly imageDigest: string;
+}
+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;
+}
+//# sourceMappingURL=deployment-binding.d.ts.map

package/dist/deployment-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-binding.d.ts","sourceRoot":"","sources":["../src/deployment-binding.ts"],"names":[],"mappings":"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"}

package/dist/deployment-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=deployment-binding.js.map

package/dist/deployment-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-binding.js","sourceRoot":"","sources":["../src/deployment-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/env-binding.d.ts

@@ -0,0 +1,132 @@
+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;
+};
+//# sourceMappingURL=env-binding.d.ts.map

package/dist/env-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-binding.d.ts","sourceRoot":"","sources":["../src/env-binding.ts"],"names":[],"mappings":"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"}

package/dist/env-binding.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=env-binding.js.map

package/dist/env-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-binding.js","sourceRoot":"","sources":["../src/env-binding.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error envelope + code→status mapping for the platform API.
+ *
+ * Spec: `docs/API-ROUTE-CONVENTIONS.md` §4. Every 4xx/5xx response
+ * carries `{ error: { code, message, details?, requestId } }`. Codes
+ * match domain error discriminants (`unresolved-tool`,
+ * `guardrail-violation`, etc.) so the SDK's `fromWire()` can pattern-
+ * match without inspecting HTTP status.
+ */
+export interface WireErrorBody {
+    readonly error: WireError;
+}
+export interface WireError {
+    readonly code: string;
+    readonly message: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    readonly requestId: string;
+}
+/**
+ * Maps a domain error `code` to the HTTP status the route layer should
+ * return. Codes not in this map fall through to `500` — the middleware
+ * treats that as a bug (unmapped code) rather than a plausible domain
+ * error. New codes MUST have a row here.
+ */
+export declare const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>>;
+/**
+ * Look up the HTTP status for a domain error code. Unmapped codes
+ * return `500` — the caller should log a warning; this indicates a
+ * mapping-table gap.
+ */
+export declare function statusFor(code: string): number;
+/** Build a wire error body from a domain error + requestId. */
+export declare function toWireError(err: {
+    readonly code: string;
+    readonly message: string;
+} & Readonly<Record<string, unknown>>, requestId: string): WireErrorBody;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAwOxD,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CACzB,GAAG,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5F,SAAS,EAAE,MAAM,GAChB,aAAa,CAaf"}