@attestry/sdk 0.6.0

package/dist/resources/regulatory-changes.js.map

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

package/dist/resources/safe-input-read.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Read a single field off a consumer-supplied input object, converting
+ * a throwing getter's exception into the SDK's documented `TypeError`
+ * input contract.
+ *
+ * The caller MUST have already confirmed `obj` is a non-null object
+ * (every resource does the top-level `typeof input === "object"` guard
+ * first). The read is a plain index access, so it walks the prototype
+ * chain identically to the bare `obj.key` it replaces — callers that
+ * need own-property semantics still gate on `Object.hasOwn` (the
+ * module-load snapshot) exactly as before; this helper only adds the
+ * throwing-getter → `TypeError` conversion.
+ *
+ * @param obj     The consumer-supplied input object (already confirmed non-null).
+ * @param key     The field name to read.
+ * @param context The calling method (e.g. `"abacPolicies.create"`) — prefixes the thrown message.
+ * @returns       The field value (`undefined` if absent — same as a bare read).
+ * @throws {TypeError} If the field's getter throws — the getter's error is preserved on `.cause`.
+ */
+export declare function readInputField(obj: object, key: string, context: string): unknown;
+//# sourceMappingURL=safe-input-read.d.ts.map

package/dist/resources/safe-input-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-input-read.d.ts","sourceRoot":"","sources":["../../src/resources/safe-input-read.ts"],"names":[],"mappings":"AAwBA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GACd,OAAO,CAcT"}

package/dist/resources/safe-input-read.js

@@ -0,0 +1,57 @@
+// ─── Defensive input-field read ─────────────────────────────────────────────
+//
+// Shared by every SDK resource that validates a consumer-supplied
+// input object by reading fields off it.
+//
+// **The gap this closes** (session-22 hostile review #1 — the SDK-wide
+// MEDIUM-1 getter-throws contract gap, deferred from session 21):
+// every resource's input validation reads fields with a bare property
+// access — `(input as { name?: unknown }).name` or `input.systemId`.
+// A consumer (or a hostile dependency that polluted a prototype) can
+// install a THROWING accessor on the input object —
+// `{ get name() { throw new Error("boom") } }` — and the bare read
+// surfaces that arbitrary exception verbatim. Every resource's JSDoc
+// promises a synchronous `TypeError` for malformed input; a throwing
+// getter breaks that documented cross-SDK contract by leaking a
+// non-`TypeError` (or a `TypeError` the SDK never authored) to the
+// caller.
+//
+// `readInputField` wraps the read in a try/catch and re-throws a
+// getter's exception as a `TypeError` — preserving the original error
+// on `.cause` (the `errors.ts` cause-assignment pattern) — so the
+// synchronous-`TypeError` input contract holds SDK-wide regardless of
+// what the input object's accessors do.
+/**
+ * Read a single field off a consumer-supplied input object, converting
+ * a throwing getter's exception into the SDK's documented `TypeError`
+ * input contract.
+ *
+ * The caller MUST have already confirmed `obj` is a non-null object
+ * (every resource does the top-level `typeof input === "object"` guard
+ * first). The read is a plain index access, so it walks the prototype
+ * chain identically to the bare `obj.key` it replaces — callers that
+ * need own-property semantics still gate on `Object.hasOwn` (the
+ * module-load snapshot) exactly as before; this helper only adds the
+ * throwing-getter → `TypeError` conversion.
+ *
+ * @param obj     The consumer-supplied input object (already confirmed non-null).
+ * @param key     The field name to read.
+ * @param context The calling method (e.g. `"abacPolicies.create"`) — prefixes the thrown message.
+ * @returns       The field value (`undefined` if absent — same as a bare read).
+ * @throws {TypeError} If the field's getter throws — the getter's error is preserved on `.cause`.
+ */
+export function readInputField(obj, key, context) {
+    try {
+        return obj[key];
+    }
+    catch (cause) {
+        const err = new TypeError(`${context}: could not read input field \`${key}\` — its getter threw`);
+        // Preserve the native ES2022 cause chain — mirror of the
+        // `AttestryError` cause-assignment pattern in `errors.ts` (assigned
+        // post-construction rather than via the 2-arg `Error` constructor,
+        // for compile-target portability).
+        err.cause = cause;
+        throw err;
+    }
+}
+//# sourceMappingURL=safe-input-read.js.map

package/dist/resources/safe-input-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-input-read.js","sourceRoot":"","sources":["../../src/resources/safe-input-read.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,kEAAkE;AAClE,yCAAyC;AACzC,EAAE;AACF,uEAAuE;AACvE,kEAAkE;AAClE,sEAAsE;AACtE,qEAAqE;AACrE,qEAAqE;AACrE,oDAAoD;AACpD,mEAAmE;AACnE,qEAAqE;AACrE,qEAAqE;AACrE,gEAAgE;AAChE,mEAAmE;AACnE,UAAU;AACV,EAAE;AACF,iEAAiE;AACjE,sEAAsE;AACtE,kEAAkE;AAClE,sEAAsE;AACtE,wCAAwC;AAExC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAW,EACX,GAAW,EACX,OAAe;IAEf,IAAI,CAAC;QACH,OAAQ,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,IAAI,SAAS,CACvB,GAAG,OAAO,kCAAkC,GAAG,uBAAuB,CACvE,CAAC;QACF,yDAAyD;QACzD,oEAAoE;QACpE,mEAAmE;QACnE,mCAAmC;QAClC,GAAmC,CAAC,KAAK,GAAG,KAAK,CAAC;QACnD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/dist/resources/ship-gate.d.ts

@@ -0,0 +1,475 @@
+import type { AttestryClient } from "../client.js";
+import type { RequestOptions } from "../types.js";
+/**
+ * Stable enum-like reason codes returned in the `reason` field. CI
+ * clients key off these strings to render PR comments / build logs.
+ * Mirror of the kernel's `ShipGateReasonCode` at
+ * `src/lib/workflow/ship-gates.ts:65-68`. **Closed-enum at the type
+ * level; runtime validation is `typeof === "string"` only** (faithful
+ * courier — gate.evaluate carry-forward). If a future kernel emits
+ * a new reason code before the SDK is bumped, the value round-trips
+ * at runtime. Drift-pinned via the wire-shape build-round pin.
+ */
+export type ShipGateReasonCode = "awaiting_approvers" | "rejected" | "timed_out";
+/**
+ * State of the ship-gate row. Mirror of the kernel's `ShipGateState`
+ * at `src/lib/workflow/ship-gates.ts:59`. **Closed-enum at the type
+ * level; runtime validation is `typeof === "string"` only** (faithful
+ * courier).
+ */
+export type ShipGateState = "gated" | "released" | "rejected" | "timed_out";
+/**
+ * Input shape for `shipGate.check`. Source-of-truth at kernel
+ * `src/app/api/v1/ship-gate/check/route.ts:41-44` (Zod schema).
+ *
+ * **`systemId`** — REQUIRED RFC 4122 hyphenated UUID. The SDK
+ * pre-validates the format synchronously (`TypeError` for malformed
+ * input — D2). The SDK's runtime check always runs regardless of
+ * TypeScript types — `as any` casts do NOT bypass it. The kernel-side
+ * Zod validation (422 fallback) only fires for kernel rule changes
+ * the SDK hasn't synced to.
+ *
+ * **`attestationId`** — REQUIRED non-empty string of length 1-256.
+ * Identifies the specific build / attestation under consideration
+ * (e.g., a git SHA, a CI build number, an attestation hash). The
+ * kernel uses this together with `systemId` as the lookup key for
+ * the `ship_gates` table's UNIQUE `(org_id, system_id, attestation_id)`
+ * constraint — calling `check()` with the same tuple repeatedly is
+ * idempotent in the no-gate / released cases (no side effect beyond
+ * the audit-log entry) and reads the same gated/terminal verdict in
+ * the gated case (post-reconciliation). The SDK pre-validates length
+ * bounds against `MAX_ATTESTATION_ID_LENGTH = 256` (the kernel
+ * constant at `src/lib/workflow/ship-gates.ts:106`).
+ */
+export interface ShipGateInput {
+    /**
+     * UUID of the system to check. RFC 4122 hyphenated form
+     * (8-4-4-4-12 hex, case-insensitive). Required.
+     */
+    systemId: string;
+    /**
+     * Build / attestation identifier (free-text 1-256 chars). Required.
+     * Forms a unique tuple with `systemId` for the `ship_gates` lookup
+     * — repeated calls on the same `(systemId, attestationId)` pair
+     * are idempotent (no side effect beyond the audit-log entry).
+     */
+    attestationId: string;
+}
+/**
+ * Response shape returned by `shipGate.check`. **UNION of 4 emit
+ * shapes** keyed by the gate's existence + state:
+ *
+ *   - **Shape A — no gate exists** (`gated: false` ONLY, 1 field):
+ *     The default-permissive short-circuit — no `ship_gates` row
+ *     for this `(systemId, attestationId)` tuple. The gate is
+ *     opt-in; consumers who never create a gate never block a build.
+ *     `state`, `executionId`, `chainId`, `reason`, and
+ *     `approvers_pending` are ALL absent (own-property false).
+ *     Source: kernel `ship-gates.ts:543-545`.
+ *   - **Shape B — released** (4 fields): `{ gated: false, state:
+ *     "released", executionId, chainId }`. The approval chain
+ *     approved the deployment. `reason` and `approvers_pending` are
+ *     absent. Source: kernel `ship-gates.ts:275-282`.
+ *   - **Shape C — rejected or timed_out** (6 fields): `{ gated: true,
+ *     reason: "rejected" | "timed_out", approvers_pending: [], state:
+ *     "rejected" | "timed_out", executionId, chainId }`. The approval
+ *     chain went terminal in a build-blocking state. `approvers_pending`
+ *     is always `[]` (nobody is pending on a closed chain). Source:
+ *     kernel `ship-gates.ts:283-302`.
+ *   - **Shape D — gated awaiting approvers** (6 fields): `{ gated:
+ *     true, reason: "awaiting_approvers", approvers_pending: [<UUIDs>],
+ *     state: "gated", executionId, chainId }`. The approval chain is
+ *     in-flight; `approvers_pending` lists the userIds still owed a
+ *     decision (pool-order, post-decided filtering — see kernel
+ *     `computeApproversPending` at `ship-gates.ts:169-205`). Source:
+ *     kernel `ship-gates.ts:303-311`.
+ *
+ * **Discriminator pattern**: use `result.gated === true` (closed-enum
+ * boolean) to detect "build must block". Use `result.state` (when
+ * own-property present) to differentiate Shapes B / C / D. **Do NOT
+ * use `result.reason === undefined`** as a discriminator — a hostile
+ * dep polluting `Object.prototype.reason` makes the `=== undefined`
+ * check return false (reads the polluted value via prototype walk),
+ * silently misclassifying Shape A / B as Shape C / D. `gated` has
+ * an UNCONDITIONAL own-property check in the validator (every code
+ * path reads `obj.gated` first); branching on it is pollution-safe.
+ *
+ * **`approvers_pending` is SNAKE_CASE on the wire** — asymmetric with
+ * the rest of the SDK's camelCase response surface. The kernel
+ * emits the literal field name `approvers_pending` (mirror of master
+ * plan spec contract). Consumers must use the snake_case spelling.
+ */
+export interface ShipGateCheckResponse {
+    /**
+     * `true` iff CI/CD must block the build. ALWAYS-PRESENT anchor
+     * field. Closed-enum boolean — pollution-safe discriminator for
+     * "build must block" decisions.
+     */
+    gated: boolean;
+    /**
+     * Stable reason code. **PRESENT ONLY when `gated: true`** (Shapes
+     * C + D). Closed-enum at the type level (`"awaiting_approvers" |
+     * "rejected" | "timed_out"`); runtime is open (faithful courier —
+     * validator checks `typeof === "string"` only). Drift-pinned via
+     * the wire-shape build-round pin.
+     *
+     * **Discriminator safety**: do NOT use `result.reason === undefined`
+     * for Shape A/B vs C/D detection (prototype walk reads polluted
+     * values under `Object.prototype.reason` pollution). Branch on
+     * `result.gated === true` (the only pollution-safe consumer-side
+     * discriminator).
+     */
+    reason?: ShipGateReasonCode;
+    /**
+     * UserIds still owed a decision (pool-order). **PRESENT ONLY when
+     * `gated: true`** (Shapes C + D). On Shape C (rejected /
+     * timed_out): always `[]` (nobody is pending on a closed chain).
+     * On Shape D (awaiting_approvers): the list of pending userIds
+     * computed by `computeApproversPending` (serial-mode preserves
+     * pool order from currentStep onward; parallel-mode returns ALL
+     * non-decided pool members; escalation user appended IFF
+     * `lastEscalatedAt` is set).
+     *
+     * **SNAKE_CASE wire field name** — asymmetric with the rest of
+     * the SDK's camelCase response surface. The kernel emits the
+     * literal field name `approvers_pending` (master plan spec
+     * contract). Consumers must use the snake_case spelling to read
+     * the field.
+     *
+     * **Discriminator safety**: do NOT use
+     * `result.approvers_pending === undefined` (prototype walk under
+     * `Object.prototype.approvers_pending` pollution returns the
+     * polluted value). Branch on `result.gated === true` first.
+     */
+    approvers_pending?: string[];
+    /**
+     * Diagnostic — gate's resolved state after reconciliation.
+     * **PRESENT in Shapes B + C + D, ABSENT in Shape A** (no gate
+     * exists). Closed-enum at the type level (`"gated" | "released" |
+     * "rejected" | "timed_out"`); runtime is open (faithful courier).
+     *
+     * **Discriminator safety**: do NOT use `result.state === undefined`
+     * for Shape A vs B detection (prototype walk under
+     * `Object.prototype.state` pollution returns the polluted value).
+     * Branch on `result.gated === true` first; for Shape A vs B
+     * specifically, neither `result.state === undefined` NOR
+     * `Object.hasOwn(result, "state")` is fully pollution-safe on the
+     * CONSUMER side (the live `Object.hasOwn` can itself be overridden;
+     * only the SDK's module-load snapshot guards its internal
+     * validator). For consumer-side defense, prefer
+     * `result.gated === false` (anchor field is always own-present and
+     * pollution-safe) AND treat the no-state branch as Shape A.
+     */
+    state?: ShipGateState;
+    /**
+     * Diagnostic — UUID of the approval-chain execution backing the
+     * gate. **PRESENT in Shapes B + C + D, ABSENT in Shape A**. The
+     * kernel column is `uuid` (PostgreSQL `uuid` type, source of truth);
+     * the SDK does not re-validate UUID format at runtime — faithful
+     * courier for the kernel's column constraint.
+     *
+     * **Discriminator safety**: same as `state` — branch on
+     * `result.gated` first; `executionId === undefined` is NOT a
+     * pollution-safe discriminator.
+     */
+    executionId?: string;
+    /**
+     * Diagnostic — UUID of the approval-chain template backing the
+     * execution. **PRESENT in Shapes B + C + D, ABSENT in Shape A**.
+     * Same `uuid`-column source-of-truth posture as `executionId`.
+     *
+     * **Discriminator safety**: same as `state` — branch on
+     * `result.gated` first; `chainId === undefined` is NOT a
+     * pollution-safe discriminator.
+     */
+    chainId?: string;
+}
+/**
+ * `shipGate` resource — sibling to `IncidentsResource`,
+ * `DecisionsResource`, `ChatResource`, `AuditLogResource`,
+ * `RegulatoryChangesResource`, `ComplianceCheckResource`,
+ * `CheckResource`, `GateResource`, `BatchResource`. Today wraps a
+ * single endpoint (`check`); the class is the landing pad for future
+ * ship-gate methods if the kernel adds them (resource-class-per-
+ * kernel-resource convention, invariant #43).
+ */
+export declare class ShipGateResource {
+    private readonly client;
+    constructor(client: AttestryClient);
+    /**
+     * Check whether a CI/CD build is gated by an in-flight approval
+     * chain. Returns a four-shape verdict keyed by the gate's
+     * existence + state. Designed for pipeline integration (GitHub
+     * Actions / GitLab CI / Buildkite).
+     *
+     * **Four emit shapes** — the response shape varies by the gate's
+     * existence + state:
+     *   - **Shape A — no gate exists**: `{ gated: false }` (1 field —
+     *     default-permissive, opt-in gate semantics).
+     *   - **Shape B — released**: `{ gated: false, state: "released",
+     *     executionId, chainId }` (4 fields).
+     *   - **Shape C — rejected / timed_out**: `{ gated: true, reason:
+     *     "rejected" | "timed_out", approvers_pending: [], state, ... }`
+     *     (6 fields; `approvers_pending` always `[]` on closed chain).
+     *   - **Shape D — gated awaiting approvers**: `{ gated: true,
+     *     reason: "awaiting_approvers", approvers_pending: [<UUIDs>],
+     *     state: "gated", ... }` (6 fields; `approvers_pending` lists
+     *     pending userIds).
+     *
+     * **`approvers_pending` is SNAKE_CASE on the wire** — the kernel
+     * emits the literal field name `approvers_pending` (asymmetric
+     * with the rest of the SDK's camelCase response surface). The SDK
+     * preserves this verbatim; consumers must use the snake_case
+     * spelling.
+     *
+     * **Multi-permission UNION auth scope**: kernel uses
+     * `requireApiKeyWithPermission(req, READ_SYSTEMS, READ_ASSESSMENTS)`
+     * which is OR semantics (`Array.some()` at
+     * `permissions.ts:53-55`). A key with EITHER permission (or
+     * `ADMIN`, or null/empty permissions for backwards-compat)
+     * succeeds. **HTTP 401** for no/invalid API key, **HTTP 403** for
+     * an authenticated key that has NEITHER required permission. Pin
+     * BOTH branches separately. Carry-forward invariant #45.
+     * **NOTE — argument order is READ_SYSTEMS FIRST** (asymmetric
+     * with `check.run` and `gate.evaluate` which list READ_ASSESSMENTS
+     * first); `Array.some()` is order-insensitive, but drift-pinned
+     * exact-arglist in the spec-diff round catches a kernel-side
+     * rename or reordering.
+     *
+     * **Discriminator pattern**: branch on `result.gated === true`
+     * (closed-enum boolean) to detect "build must block". The SDK's
+     * P2 validator guarantees `gated` is ALWAYS an own-property of
+     * the returned object — that's the only consumer-side discriminator
+     * that is genuinely pollution-safe (no prototype-walk hazard).
+     *
+     * **Do NOT use `result.reason === undefined`** as a discriminator
+     * — a hostile dep polluting `Object.prototype.reason` makes the
+     * `=== undefined` check return false (reads via prototype walk),
+     * silently misclassifying Shape A / B as Shape C / D.
+     *
+     * **Consumer-side `Object.hasOwn(result, "state")` is NOT a fully
+     * safe alternative** — it relies on the LIVE global `Object.hasOwn`,
+     * which is itself subject to override by a hostile dep
+     * (`Object.hasOwn = () => true`). The SDK's own response-side
+     * validator uses a module-load snapshot of `Object.hasOwn` (taken
+     * at SDK import time, before consumer-graph deps load) so the
+     * SDK-internal validation is hardened; consumer code calling the
+     * live `Object.hasOwn` after the SDK resolves is not. For
+     * consumer-side defense-in-depth, branch on `result.gated` first
+     * (the safe boolean), and only inspect `result.state` after.
+     *
+     * **Reconciliation-on-read inside transaction** — when the linked
+     * `approval_chain_executions` row has gone terminal but the
+     * `ship_gates` row still says `gated`, the kernel's `checkShipGate`
+     * advances the gate to the corresponding terminal state inside
+     * `SELECT … FOR UPDATE` (`ship-gates.ts:567-584`). The SDK does
+     * NOT observe the reconciliation step — only the post-reconciliation
+     * shape. A consumer calling `check()` twice in quick succession
+     * on a chain that just completed sees the gated-state shape on
+     * call 1 (if reconciliation hadn't fired yet) and the terminal
+     * shape on call 2. Faithful courier; documented kernel behavior.
+     *
+     * **`writeAuditLog` side effect** — every `shipGate.check(...)`
+     * call writes one audit-log entry with `action: "ship_gate.checked"`
+     * and `resourceType: "ship_gate"` (route.ts:73-87; both strings
+     * drift-pinned). SIEM / observability consumers keying off either
+     * field for filter setup should depend on both staying stable.
+     * Properties of the write:
+     *   - Org-scoped, hash-chained (per `writeAuditLog`).
+     *   - **Time-blocking** but error-tolerant: the kernel uses
+     *     `await writeAuditLog(...)`, which awaits two DB ops (SELECT
+     *     previous-hash + INSERT new entry). The check response
+     *     latency INCLUDES the audit-log write time — a slow audit-log
+     *     DB will delay every `shipGate.check()` response. Error
+     *     semantics ARE non-blocking: `writeAuditLog` wraps its body
+     *     in a try/catch that swallows + logs errors, so a write
+     *     FAILURE does NOT fail the check request.
+     *   - NOT counted against `decisionsPerMonth` quota (read-shaped).
+     * Invariant #53 carry-forward (matches `gate.evaluate`'s pattern).
+     *
+     * **Kernel-side 15-second timeout** (`maxDuration = 15` at
+     * `route.ts:24`). **Same as `gate.evaluate`'s 15s; tighter than
+     * `auditLog.verifyChain`'s 30s.** The SDK does NOT enforce a
+     * client-side timeout (consumers manage via `options.signal`),
+     * but the kernel's function-runtime cap bounds the request
+     * latency on the server side. CI pipeline timeouts should budget
+     * relative to this cap.
+     *
+     * **Documented kernel-side cascade-gap surfaces — TWO distinct
+     * paths**:
+     *   1. **Execution-missing → HTTP 404** (named-error path). The
+     *      kernel maps `ShipGateExecutionNotFoundError` to 404 at
+     *      route.ts:97-99. Thrown by `checkShipGate` only when the
+     *      inner `executionRows.length === 0` defensive branch fires
+     *      (`ship-gates.ts:559-564`).
+     *   2. **Chain-missing → HTTP 500 (scrubbed)** (plain-Error path).
+     *      A SEPARATE defensive branch at `ship-gates.ts:610-617`
+     *      throws a PLAIN `Error` (NOT a named class) when a
+     *      ship_gate → execution → chain reference is broken on the
+     *      LAST hop. The route's catch block has only three
+     *      `instanceof` arms (`AuthError`, `BodyParseError`,
+     *      `ShipGateExecutionNotFoundError`); a plain `Error` falls
+     *      through to `internalErrorResponse → 500` with the scrubbed
+     *      message "An internal error occurred. Please try again
+     *      later." The caller cannot distinguish this cascade-gap
+     *      from any other internal error via the HTTP status alone.
+     * Both branches are unreachable in normal operation (RESTRICT FK
+     * + filter-by-orgId); both documented as "only reachable via
+     * direct DB intervention or a cascade-behavior gap." Faithful
+     * courier: the SDK surfaces whichever status the kernel chose
+     * (404 vs 500), but SIEM consumers running cascade-gap-404
+     * filters should know the second branch hides as 500.
+     *
+     * Errors — **happy-path precedence ordering** is rate-limit → auth
+     * → Zod body validation → DB lookup → successResponse. A request
+     * with multiple happy-path problems surfaces ONLY the highest-
+     * precedence one. **The 500-catchall is a SEPARATE DIMENSION** —
+     * any throwable not matched by the named `instanceof` arms (see
+     * the 500 bullet below) falls to 500, regardless of where in the
+     * happy-path it fired. So e.g. a Zod-library crash during body
+     * parsing surfaces as 500 (NOT 422).
+     *   - `AttestryAPIError` (status 429) — rate limit FIRES FIRST
+     *     (auto-retried by default — invariant #18; per-IP rate-limit
+     *     key `v1-ship-gate-check:${ip}` against the standard
+     *     `apiLimiter`).
+     *   - `AttestryAPIError` (status 401) — no API key OR invalid key.
+     *     Fires AFTER rate-limit but BEFORE input validation.
+     *   - `AttestryAPIError` (status 403) — authenticated key has
+     *     NEITHER `READ_SYSTEMS` nor `READ_ASSESSMENTS`. Single test
+     *     case — the union-auth pattern collapses three intuition-
+     *     suggesting cases to one.
+     *   - `AttestryAPIError` (status 422) — Zod schema rejection
+     *     (kernel's `BodyParseError` surface — `parseBody(request,
+     *     checkSchema)` failed). **Fires BEFORE the cascade-gap 404
+     *     lookup**. `apiErr.details` carries the full kernel error
+     *     body verbatim (the transport does NOT strip the
+     *     `{success:false, ...}` envelope on error responses — only
+     *     the `{success:true, data}` envelope on success). The wire
+     *     shape is: `{success: false, error: "Validation failed.",
+     *     details: Array<{path: string; message: string}>}` — `error`
+     *     is the literal string "Validation failed." (with trailing
+     *     period), `details` is an array (NOT a keyed map) of `{path,
+     *     message}` pairs derived from Zod's `result.error.errors`.
+     *     **The SDK pre-validates both closed-spec rules** (UUID
+     *     format on systemId, length 1-256 on attestationId) AND the
+     *     runtime checks always run regardless of TypeScript types —
+     *     `as any` casts do NOT bypass them. So 422 reaches consumers
+     *     ONLY via kernel rule changes the SDK hasn't synced to.
+     *     Invariant #51.
+     *   - `AttestryAPIError` (status 404) — cascade-gap rare path:
+     *     kernel threw `ShipGateExecutionNotFoundError` because a
+     *     `ship_gates` row references an `executionId` whose row is
+     *     missing in `approval_chain_executions`. Documented as "only
+     *     reachable via direct DB intervention".
+     *   - `AttestryAPIError` (status 500) — internal kernel error
+     *     (scrubbed message via `internalErrorResponse`). **The 500
+     *     surface is orthogonal to the precedence list above**: ANY
+     *     throwable not matched by the three named `instanceof` arms
+     *     (`AuthError` 401/403, `BodyParseError` 422,
+     *     `ShipGateExecutionNotFoundError` 404) — INCLUDING throwables
+     *     that fire DURING any of the happy-path steps — falls to
+     *     500. **Includes the chain-missing cascade-gap** (the second
+     *     defensive branch in `checkShipGate` at `ship-gates.ts:
+     *     610-617` throws a plain `Error` that hides as 500, NOT as a
+     *     named 404 surface).
+     *   - `AttestryError` ("request aborted by caller") — caller-
+     *     supplied `options.signal` fired (pre-aborted or mid-flight).
+     *   - `AttestryError` (P2 hardening) — kernel response failed
+     *     SDK-side shape validation (not an object, wrong type on
+     *     `gated`, wrong type on any optional own-property field).
+     *   - `AttestryAPIError` (P3 hardening) — kernel response had a
+     *     wrong Content-Type (transport-level guard before body
+     *     parsing).
+     *   - `TypeError` (synchronous, no fetch issued) — input failed
+     *     SDK-side validation (null / array / non-object input,
+     *     missing systemId, invalid UUID format, missing attestationId,
+     *     non-string attestationId, attestationId length out of
+     *     range [1, 256]).
+     *
+     * **Notably ABSENT**:
+     *   - **No 400** — all input validation is Zod (422).
+     *   - **No 402** — read-shaped, doesn't count against
+     *     decisionsPerMonth quota (despite the audit-log side effect).
+     *   - **No 413** — body size limit not explicit.
+     *
+     * **SDK-side validation** (synchronous `TypeError`, no fetch
+     * issued):
+     *   - `input` itself: required; must be a non-null, non-array
+     *     object.
+     *   - `input.systemId`: required own-property (Object.hasOwn
+     *     defends against prototype pollution lying about presence —
+     *     generalization of invariant #48); must be a non-empty
+     *     string; must match the RFC 4122 hyphenated UUID format
+     *     (D2 — SDK pre-validates closed-spec rule). No
+     *     lone-surrogate URIError defense (POST body uses
+     *     JSON.stringify).
+     *   - `input.attestationId`: required own-property; must be a
+     *     non-empty string; length 1-256 (matches kernel constant
+     *     `MAX_ATTESTATION_ID_LENGTH = 256` at
+     *     `src/lib/workflow/ship-gates.ts:106`).
+     *
+     * **Response-shape validation** (P2 hardening — symmetric defense
+     * on response side per the module-load `objectHasOwn` snapshot;
+     * mirror of `gate.ts` / `audit-log.ts` patterns):
+     *   - Rejects with `AttestryError` if the kernel response isn't
+     *     a non-null, non-array object.
+     *   - Rejects if `gated` isn't a boolean (ALWAYS-present anchor
+     *     field — the validator's `gated` branch is UNCONDITIONAL).
+     *   - Rejects if `reason` (when own-present) isn't a string.
+     *   - Rejects if `approvers_pending` (when own-present) isn't an
+     *     array.
+     *   - Rejects if `state` (when own-present) isn't a string.
+     *   - Rejects if `executionId` / `chainId` (when own-present)
+     *     aren't strings.
+     *   - Each response field read goes through the module-load
+     *     `objectHasOwn` snapshot — defends against
+     *     `Object.prototype.<field>` pollution masking a missing field.
+     *   - Per-element shape on `approvers_pending` (each element must
+     *     be a string) is validated when the field is own-present.
+     *
+     * **Transport-shape validation** (P3 hardening):
+     *   - Rejects with `AttestryAPIError` if the kernel responds with
+     *     a non-`application/json` Content-Type.
+     *
+     * @example Basic ship-gate check (typical CI usage)
+     * ```ts
+     * const verdict = await client.shipGate.check({
+     *   systemId: "11111111-1111-1111-1111-111111111111",
+     *   attestationId: "build-1234",
+     * });
+     * if (verdict.gated) {
+     *   // Shape C or D — build must block.
+     *   if (verdict.reason === "awaiting_approvers") {
+     *     // Shape D — list pending approvers in PR comment.
+     *     console.error(
+     *       `Awaiting approval from ${verdict.approvers_pending?.join(", ")}`,
+     *     );
+     *   } else {
+     *     // Shape C — rejected or timed_out.
+     *     console.error(`Build blocked: ${verdict.reason}`);
+     *   }
+     *   process.exit(1);
+     * }
+     * // Shape A (no gate) or Shape B (released) — build proceeds.
+     * console.log("OK to deploy.");
+     * ```
+     *
+     * @example Discriminate Shape A vs Shape B (no-gate vs released)
+     * ```ts
+     * const verdict = await client.shipGate.check({
+     *   systemId: "11111111-1111-1111-1111-111111111111",
+     *   attestationId: "build-1234",
+     * });
+     * if (!verdict.gated) {
+     *   if (verdict.state === "released") {
+     *     console.log(`Approved (execution: ${verdict.executionId})`);
+     *   } else {
+     *     // No state field → Shape A (no gate exists).
+     *     console.log("No gate configured for this build.");
+     *   }
+     * }
+     * ```
+     */
+    check(input: ShipGateInput, options?: RequestOptions): Promise<ShipGateCheckResponse>;
+}
+//# sourceMappingURL=ship-gate.d.ts.map

package/dist/resources/ship-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ship-gate.d.ts","sourceRoot":"","sources":["../../src/resources/ship-gate.ts"],"names":[],"mappings":"AAsMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgClD;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAC1B,oBAAoB,GACpB,UAAU,GACV,WAAW,CAAC;AAEhB;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,GAAG,WAAW,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiRG;IACH,KAAK,CACH,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,qBAAqB,CAAC;CAmGlC"}