@fourier-labs/harbour-contracts 0.6.0 → 0.10.0

package/gen-ts/ai-trace-event-v2.ts

@@ -0,0 +1,35 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type AiTraceV2Digest = string;
+export type AiTraceV2Identifier = string;
+
+/**
+ * Additive metering projection linked to a readable v1 trace. It carries dimension-level reported or estimated usage without changing the v1 event.
+ */
+export interface AiTraceEventV2 {
+  schema: 'harbour.ai-trace-event/2.0';
+  traceId: string;
+  requestId: string;
+  policyDigest: AiTraceV2Digest;
+  outcome: 'succeeded' | 'blocked' | 'failed' | 'cancelled';
+  /**
+   * @maxItems 256
+   */
+  usageLineItems: UsageLineItem[];
+  totalCostMicroUsd: number;
+  reservationId?: string;
+  meteringStatus: 'settled' | 'reserved' | 'unknown' | 'repaired';
+  occurredAt: string;
+}
+export interface UsageLineItem {
+  attempt: number;
+  dimension: AiTraceV2Identifier;
+  direction: 'input' | 'output';
+  quantity: number;
+  unit: AiTraceV2Identifier;
+  priceRevisionDigest: AiTraceV2Digest;
+  scale: number;
+  costMicroUsd: number;
+  provenance: 'reported' | 'estimated';
+}

package/gen-ts/ai-trace-event.ts

@@ -0,0 +1,72 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Value-free asynchronous AI Gateway trace metadata. Raw prompts and responses never enter the queue; captured content is referenced only after successful encrypted storage.
+ */
+export type AiTraceEvent = {
+  schema: 'harbour.ai-trace-event/1.0';
+  traceId: string;
+  requestId: string;
+  tenantId: AiTraceIdentifier;
+  appId: AiTraceIdentifier;
+  environment: AiTraceIdentifier;
+  versionId: string;
+  callsiteFingerprint?: AiTraceDigest;
+  policyDigest: AiTraceDigest;
+  routeRevision?: string;
+  requestedModel?: string;
+  governedModelAlias?: string;
+  provider?: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+  providerModel?: string;
+  outcome: 'succeeded' | 'blocked' | 'failed' | 'cancelled';
+  usage?: AiTraceUsage;
+  priceRevision?: AiTraceIdentifier;
+  costMicroUsd: number;
+  latencyMs: number;
+  retryCount: number;
+  fallbackUsed: boolean;
+  reservationId?: string;
+  /**
+   * @minItems 0
+   * @maxItems 32
+   */
+  attempts: AiTraceAttempt[];
+  /**
+   * @maxItems 128
+   */
+  guardrailResults: AiTraceGuardrailResult[];
+  contentCaptureStatus: 'off' | 'captured' | 'capture_failed';
+  contentRef?: string;
+  retentionExpiresAt?: string;
+  occurredAt: string;
+};
+export type AiTraceIdentifier = string;
+export type AiTraceDigest = string;
+export type AiTraceAttempt = {
+  attempt: number;
+  provider: 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+  providerModel: string;
+  priceRevision: AiTraceIdentifier;
+  outcome: 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+  /**
+   * Provider-reported token usage, or null when the attempt did not succeed and the provider reported none. Null states that usage is UNKNOWN — estimates are never fabricated. A succeeded attempt always reports real usage.
+   */
+  usage: AiTraceUsage | null;
+  costMicroUsd: number;
+  latencyMs: number;
+  errorCode?: string;
+};
+
+export interface AiTraceUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+export interface AiTraceGuardrailResult {
+  ruleId: string;
+  detectorId: string;
+  detectorVersion: string;
+  phase: 'input' | 'output';
+  action: 'ALLOW' | 'OBSERVE' | 'REDACT' | 'BLOCK';
+  result: 'passed' | 'matched' | 'blocked' | 'redacted';
+}

package/gen-ts/ai-transform-event.ts

@@ -0,0 +1,51 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type AiTransformIdentifier = string;
+export type AiTransformDigest = string;
+export type AiTransformPlanEntry = {
+  callSiteFingerprint: AiTransformDigest;
+  sourcePath: string;
+  expectedSourceFileSha256: AiTransformDigest;
+  strategy: 'deployment_injection' | 'deterministic_adapter';
+  configurationMappingId?: AiTransformIdentifier;
+  configurationMappingVersion?: string;
+  transformId?: AiTransformIdentifier;
+  transformVersion?: string;
+  /**
+   * @minItems 1
+   * @maxItems 32
+   */
+  allowedSyntaxKinds: AiTransformIdentifier[];
+  runtimeShimName?: string;
+  runtimeShimVersion?: string;
+  runtimeShimDigest?: AiTransformDigest;
+};
+
+/**
+ * Checksum-bound deterministic AI interception task input. Entries are the complete ordered PLAN interception plan so the task can verify the governance plan digest before applying its deterministic subset; source and patches are referenced, never embedded.
+ */
+export interface AiTransformEvent {
+  schema: 'harbour.ai-transform-event/1.0';
+  tenantId: AiTransformIdentifier;
+  appId: AiTransformIdentifier;
+  environment: AiTransformIdentifier;
+  versionId: string;
+  sourceRevision: string;
+  workspace: AiTransformWorkspace;
+  inventoryDigest: AiTransformDigest;
+  policyDigest: AiTransformDigest;
+  runtimeContractDigest: AiTransformDigest;
+  interceptionPlanDigest: AiTransformDigest;
+  /**
+   * @minItems 1
+   * @maxItems 1000
+   */
+  entries: AiTransformPlanEntry[];
+}
+export interface AiTransformWorkspace {
+  bucket: string;
+  key: string;
+  sha256: AiTransformDigest;
+  size: number;
+}

package/gen-ts/ai-transform-result.ts

@@ -0,0 +1,36 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type AiTransformResultDigest = string;
+export type AiTransformResultIdentifier = string;
+
+/**
+ * Bounded deterministic interception result; contains descriptors and digest evidence only.
+ */
+export interface AiTransformResult {
+  schema: 'harbour.ai-transform-result/1.0';
+  workspace: AiTransformResultWorkspace;
+  interceptionPlanDigest: AiTransformResultDigest;
+  transformerVersion: string;
+  /**
+   * @minItems 1
+   * @maxItems 1000
+   */
+  applied: AiTransformApplied[];
+}
+export interface AiTransformResultWorkspace {
+  bucket: string;
+  key: string;
+  sha256: AiTransformResultDigest;
+  size: number;
+}
+export interface AiTransformApplied {
+  callSiteFingerprint: AiTransformResultDigest;
+  transformId: AiTransformResultIdentifier;
+  transformVersion: string;
+  sourcePath: string;
+  beforeSha256: AiTransformResultDigest;
+  afterSha256: AiTransformResultDigest;
+  governedBoundaryFingerprint: AiTransformResultDigest;
+  runtimeShimDigest: AiTransformResultDigest;
+}

package/gen-ts/ai-verification-evidence.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type AiVerificationIdentifier = string;
+export type AiVerificationDigest = string;
+
+/**
+ * Bounded, value-free evidence submitted by deployment verification for one governed version.
+ */
+export interface AiVerificationEvidence {
+  schema: 'harbour.ai-verification-evidence/1.0';
+  tenantId: AiVerificationIdentifier;
+  appId: AiVerificationIdentifier;
+  environment: AiVerificationIdentifier;
+  versionId: string;
+  sourceRevision: string;
+  inventoryDigest: AiVerificationDigest;
+  interceptionPlanDigest: AiVerificationDigest;
+  runtimeContractDigest: AiVerificationDigest;
+  policyDigest: AiVerificationDigest;
+  runtimeBindingDigest?: AiVerificationDigest;
+  finalWorkspaceDigest: AiVerificationDigest;
+  /**
+   * @maxItems 1000
+   */
+  verifiedCallsiteFingerprints: AiVerificationDigest[];
+  /**
+   * @maxItems 1000
+   */
+  appliedTransforms: AiVerificationTransform[];
+  /**
+   * @minItems 1
+   * @maxItems 32
+   */
+  endpointChecks: AiVerificationEndpointCheck[];
+  providerCredentialsAbsent: true;
+  smokeTraceId: string;
+  evidenceDigest: AiVerificationDigest;
+  verifiedAt: string;
+}
+export interface AiVerificationTransform {
+  callSiteFingerprint: AiVerificationDigest;
+  governedBoundaryFingerprint: AiVerificationDigest;
+  transformId: AiVerificationIdentifier;
+  transformVersion: string;
+  beforeSha256: AiVerificationDigest;
+  afterSha256: AiVerificationDigest;
+  runtimeShimDigest: AiVerificationDigest;
+}
+export interface AiVerificationEndpointCheck {
+  name: AiVerificationIdentifier;
+  passed: true;
+  configurationMappingVersion: string;
+}

package/gen-ts/api-error-response.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Safe JSON error body returned by the Deploy and Status Lambdas for API-level 4xx and 5xx responses. It is distinct from the internal pipeline ErrorEnvelope, which requires a version and evidence reference.
+ */
+export interface ApiErrorResponse {
+  code: string;
+  message: string;
+  correlationId: string;
+  requestId?: string;
+  /**
+   * Present when a version was minted before the API-level failure.
+   */
+  versionId?: string;
+}

package/gen-ts/artifact-contract.ts

@@ -0,0 +1,81 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * The build output contract (LLD §3) — the provider-portability seam. Emitted by the build (`artifact.json`) and consumed by every deploy stage below build. Deploy stages read ONLY this document plus the blobs it references. Secret REFERENCES only — never values.
+ */
+export interface ArtifactContract {
+  contract_version: 1;
+  app_id: string;
+  commit: string;
+  /**
+   * sha256 of the canonical bundle; the immutable identity that promotion pins to (invariant §1.3.2).
+   */
+  artifact_digest: string;
+  backend: {
+    type: 'oci-image' | 'zip';
+    /**
+     * ECR uri@digest (oci-image) or S3 key (zip).
+     */
+    ref: string;
+    entrypoint: string;
+    runtime: string;
+  };
+  static: {
+    /**
+     * e.g. builds/<digest>/
+     */
+    path: string;
+    /**
+     * true when static assets carry no env-specific values (no static rebuild needed on promotion).
+     */
+    env_agnostic: boolean;
+  };
+  routes: {
+    path: string;
+    target: 'backend' | 'static';
+  }[];
+  env: {
+    /**
+     * Non-secret env vars, e.g. {"PORT":"8080"}.
+     */
+    vars: {
+      [k: string]: string;
+    };
+    /**
+     * Secrets Manager references only, e.g. harbour/<org>/<app>/<env>/STRIPE_KEY. Never values.
+     */
+    secret_refs: string[];
+  };
+  storage_bindings: {
+    kind: 'sql' | 'kv' | 'files';
+    /**
+     * Logical name, e.g. "default".
+     */
+    logical?: string;
+    /**
+     * e.g. aurora-sv2.
+     */
+    provider: string;
+  }[];
+  /**
+   * Post-MVP (migration tooling is post-MVP, LLD §4.6); MVP emits an empty array.
+   */
+  migrations: {
+    seq: number;
+    sha: string;
+    destructive: boolean;
+    path: string;
+  }[];
+  /**
+   * MVP emits an empty array.
+   */
+  scheduled_tasks: {}[];
+  transform_report: {
+    /**
+     * Transformed surfaces, e.g. ["secrets","storage.sql"].
+     */
+    surfaces: string[];
+    static_rebuild_required: boolean;
+  };
+}

package/gen-ts/binding-classification-digest-helper.ts

@@ -0,0 +1,44 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+import { createHash } from 'node:crypto';
+import type { BindingClassificationSubject } from './binding-classification-subject.js';
+
+const domain = 'harbour.binding-classification-subject/1.0';
+const token = (value: string): string => Buffer.byteLength(value, 'utf8') + ':' + value;
+const record = (tag: string, values: string[]): string => tag + values.map(token).join('');
+
+/** Exact source-revision digest preimage shared by the producer and DCP. */
+export function sourceRevisionPreimage(sourceRef: string, sourceRevision: string): string { return [record('D', ['harbour.source-revision/1.0']), record('S', [sourceRef, sourceRevision])].join('\n'); }
+
+export function computeSourceRevisionDigest(sourceRef: string, sourceRevision: string): string { return 'sha256:' + createHash('sha256').update(sourceRevisionPreimage(sourceRef, sourceRevision), 'utf8').digest('hex'); }
+
+/** Rejects an unknown or provider-mismatched requested AI mapping. JSON Schema owns field presence and bounds. */
+export function assertBindingClassificationMappings(input: BindingClassificationSubject): void {
+  if (input.sourceRevisionDigest !== computeSourceRevisionDigest(input.sourceRef, input.sourceRevision)) throw new Error('sourceRevisionDigest mismatch');
+  for (const [name, entry] of Object.entries(input.classifications)) {
+    if (entry.kind !== 'provider_credential') continue;
+    const mapping = entry.requestedAiMappingId ? input.requestedAiMappings[entry.requestedAiMappingId] : undefined;
+    if (!mapping) throw new Error('unknown requestedAiMappingId for ' + name);
+    if (mapping.providerId !== entry.providerId) throw new Error('providerId mismatch for ' + name);
+  }
+}
+
+/** Proves the subject classifies every declared binding exactly once and no undeclared name. */
+export function assertBindingClassificationCoverage(input: BindingClassificationSubject, bindingNames: readonly string[]): void {
+  const expected = [...bindingNames].sort();
+  if (new Set(expected).size !== expected.length) throw new Error('duplicate declared binding name');
+  const actual = Object.keys(input.classifications).sort();
+  if (expected.length !== actual.length || expected.some((name, index) => name !== actual[index])) throw new Error('binding classification coverage mismatch');
+}
+
+/** Exact UTF-8 length-prefixed preimage. Maps are sorted by key; classificationDigest is excluded. */
+export function bindingClassificationPreimage(input: BindingClassificationSubject): string {
+  assertBindingClassificationMappings(input);
+  const rows = [record('D', [domain]), record('H', [input.schema, input.status, input.tenantId, input.appId, input.environment, input.sourceRef, input.sourceRevision, input.sourceRevisionDigest, input.classifierRevision])];
+  for (const name of Object.keys(input.classifications).sort()) { const entry = input.classifications[name]!; rows.push(record('C', [name, entry.kind, entry.confidence, entry.providerId ?? '', entry.category ?? '', entry.requestedAiMappingId ?? ''])); }
+  for (const mappingId of Object.keys(input.requestedAiMappings).sort()) { const mapping = input.requestedAiMappings[mappingId]!; rows.push(record('M', [mappingId, mapping.mappingVersion, mapping.providerId])); }
+  return rows.join('\n');
+}
+
+export function computeBindingClassificationDigest(input: BindingClassificationSubject): string { return 'sha256:' + createHash('sha256').update(bindingClassificationPreimage(input), 'utf8').digest('hex'); }

package/gen-ts/binding-classification-subject.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export type BindingClassificationIdentifier = string;
+/**
+ * Provider-neutral, normalized and credential-free source repository reference. Current GitHub HTTPS references and future SCM adapters use the same safe hierarchical grammar; userinfo, ports, percent encoding, query strings and fragments are unrepresentable.
+ */
+export type BindingClassificationSourceRef = string;
+/**
+ * Provider-neutral exact revision identifier expressed as algorithm:value. Current Git adapters use git-sha1:<40 lowercase hex>; another SCM or Git hash algorithm does not require a shape change.
+ */
+export type BindingClassificationSourceRevision = string;
+export type BindingClassificationDigest = string;
+export type BindingClassificationEntry = {
+  kind: 'configuration' | 'secret' | 'provider_credential';
+  confidence: 'high' | 'low';
+  providerId?: BindingClassificationProviderId;
+  category?: BindingClassificationCredentialCategory;
+  requestedAiMappingId?: BindingClassificationIdentifier;
+};
+export type BindingClassificationProviderId = 'openai' | 'anthropic' | 'gemini' | 'openrouter';
+/**
+ * Closed current credential category. Add a reviewed contract version before supporting another credential mechanism.
+ */
+export type BindingClassificationCredentialCategory = 'api_key';
+
+/**
+ * Complete, immutable and value-free classification of the exact declared environment-binding names for one provider-neutral normalized source revision before DCP allocates a version. The caller never guesses a versionId. DCP validates this subject, allocates the sole versionId and chains classificationDigest into separately persisted SanitizedBindingEvidence; it must never relabel this source-bound evidence.
+ */
+export interface BindingClassificationSubject {
+  schema: 'harbour.binding-classification-subject/1.0';
+  /**
+   * Partial or unavailable classification cannot be represented as an admissible subject.
+   */
+  status: 'COMPLETE';
+  tenantId: BindingClassificationIdentifier;
+  appId: BindingClassificationIdentifier;
+  environment: 'preview' | 'prod';
+  sourceRef: BindingClassificationSourceRef;
+  sourceRevision: BindingClassificationSourceRevision;
+  sourceRevisionDigest: BindingClassificationDigest;
+  classifierRevision: string;
+  /**
+   * Exact classification set keyed by every declared environment-binding name. Object keys make missing duplication tricks and two classifications for one name unrepresentable. Literal values and secret references are intentionally unrepresentable. DCP additionally requires these keys to equal the names in the request's environmentBindings before allocation.
+   */
+  classifications: {
+    [k: string]: BindingClassificationEntry;
+  };
+  /**
+   * Exact set keyed by requested AI mapping ID of supported mappings intended to own provider-client credentials for this source revision. This is pre-PLAN request evidence, not a claim that enforcement already exists. Provider-credential classifications reference one of these exact mapping IDs.
+   */
+  requestedAiMappings: {
+    [k: string]: BindingClassificationAiMapping;
+  };
+  classificationDigest: BindingClassificationDigest;
+}
+export interface BindingClassificationAiMapping {
+  mappingVersion: string;
+  providerId: BindingClassificationProviderId;
+}

package/gen-ts/contract-release.ts

@@ -0,0 +1,10 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+export const ContractRepositoryVersion = "0.10.0.0" as const;
+export const ContractPublishVersion = "0.10.0" as const;
+export const ContractPublishTag = "v0.10.0" as const;
+export const ContractSchemasDigest = "sha256:e22fd6329b9064a3d653dbc6bc3ee0c2033ee6d8d279f06532a355c9285aa7fe" as const;
+export const ContractAiFixturesDigest = "sha256:8355039f14457087d36aee52ae1a0a93096bf12f34bd8af0d948c605b6dff226" as const;
+export const ContractGeneratedGoDigest = "sha256:d1a57e9b7b414bc239af4dd897c444bfac08e3bfbb24426d525faad6878d6a26" as const;
+export const ContractGeneratedTypeScriptDigest = "sha256:e455c76468808b1191a3d2d774786bb18dc435785d9fa31a559f6b93f3e160c9" as const;

package/gen-ts/data-dependency.ts

@@ -0,0 +1,46 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * database = a SQL/warehouse connection; api = an HTTP(S) service; app_owned_external = infrastructure the app owns outside Harbour.
+ */
+export type DataDependencyKind = 'database' | 'api' | 'app_owned_external';
+/**
+ * matched = resolved to a registered source; out_of_scope = resolved but not requestable; unknown = unresolvable; inventory = registered but unused; app_owned_external = app-owned, outside Harbour's remit.
+ */
+export type DataDependencyClassification = 'matched' | 'out_of_scope' | 'unknown' | 'inventory' | 'app_owned_external';
+/**
+ * declared = stated by the builder; detected = found by analysis.
+ */
+export type DataDependencyOrigin = 'declared' | 'detected';
+
+/**
+ * A single external data dependency of an app, either declared by the builder or detected during analysis. Classification records how the dependency resolved against the tenant's registered data-source inventory; matchedSourceId is present only when classification is matched.
+ */
+export interface DataDependency {
+  kind: DataDependencyKind;
+  identifiers: DataDependencyIdentifiers;
+  classification: DataDependencyClassification;
+  /**
+   * sourceId of the registered data source this dependency matched; present only when classification is matched.
+   */
+  matchedSourceId?: string;
+  origin: DataDependencyOrigin;
+}
+/**
+ * Evidence identifying the dependency; used to match it against the registered source inventory.
+ */
+export interface DataDependencyIdentifiers {
+  /**
+   * Hostnames the dependency was observed or declared against.
+   */
+  hosts: string[];
+  /**
+   * Client driver/library that surfaced the dependency (e.g. pg, snowflake-sdk).
+   */
+  driver?: string;
+  /**
+   * Environment-variable names the app reads to configure this dependency.
+   */
+  envNames: string[];
+}

package/gen-ts/data-grant.ts

@@ -0,0 +1,71 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Access mode. MVP is read-only; write is a deliberate future schema change.
+ */
+export type DataGrantMode = 'read';
+/**
+ * MVP: one minted service principal per grant. Per-end-user passthrough is a future schema change.
+ */
+export type DataGrantIdentityModel = 'service';
+/**
+ * Grant lifecycle state. Legal edges live in x-transitions; GRANTED and DENIED are terminal.
+ */
+export type DataGrantStatus = 'REQUESTED' | 'GRANTED' | 'DENIED';
+
+/**
+ * An app's approved (or requested) read scope against a registered data source. MVP is deliberately narrow: mode is read-only and identityModel is service (one minted principal per grant, no per-end-user identity passthrough). Grant status is a tiny state machine — legal edges live in x-transitions and codegen turns them into shared CanTransitionDataGrantStatus / IsTerminalDataGrantStatus helpers so control-plane and consumers agree on legality.
+ */
+export interface DataGrant {
+  /**
+   * App the grant belongs to.
+   */
+  appId: string;
+  /**
+   * Registered data source the grant targets (data-source.schema.json).
+   */
+  sourceId: string;
+  /**
+   * Requested/granted selectors; every selector must fall inside the source's allowedScope.
+   *
+   * @minItems 1
+   */
+  scope: string[];
+  mode: DataGrantMode;
+  identityModel: DataGrantIdentityModel;
+  status: DataGrantStatus;
+  /**
+   * secretref URI of the minted per-grant credential; present once GRANTED.
+   */
+  credentialRef?: string;
+  /**
+   * Name of the scoped principal minted on the source for this grant; present once GRANTED.
+   */
+  mintedPrincipal?: string;
+  /**
+   * Operation (e.g. deployment analysis) that raised the request, for audit correlation.
+   */
+  requestedByOperationId?: string;
+  /**
+   * Admin identity that resolved the request; present once GRANTED or DENIED.
+   */
+  approvedBy?: string;
+  /**
+   * RFC 3339 instant the request was resolved; present once GRANTED or DENIED.
+   */
+  approvedAt?: string;
+}
+
+const legalDataGrantStatusTransitions: Record<string, Record<string, true>> = {
+  "REQUESTED": { "GRANTED": true, "DENIED": true },
+};
+const terminalDataGrantStatusStates = new Set<string>(["GRANTED", "DENIED"]);
+
+/** True iff from→to is a legal DataGrantStatus edge (schema x-transitions). */
+export function canTransitionDataGrantStatus(from: string, to: string): boolean {
+  return Boolean(legalDataGrantStatusTransitions[from]?.[to]);
+}
+
+/** True iff the DataGrantStatus is terminal (GRANTED, DENIED). */
+export function isTerminalDataGrantStatus(state: string): boolean { return terminalDataGrantStatusStates.has(state); }

package/gen-ts/data-source.ts

@@ -0,0 +1,78 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+
+/**
+ * Closed connector set for the Data-Access MVP.
+ */
+export type DataSourceConnector = 'postgres' | 'redshift' | 'bigquery' | 'databricks';
+/**
+ * byo = admin brought existing infrastructure; harbour_managed = Harbour provisioned it.
+ */
+export type DataSourceProvisioningMode = 'byo' | 'harbour_managed';
+/**
+ * DISABLED sources reject new grants and suspend existing access.
+ */
+export type DataSourceStatus = 'ACTIVE' | 'DISABLED';
+
+/**
+ * An admin-registered external data source (Data-Access MVP). The credential the platform holds for the source never crosses this boundary — credentialRef is a secretref URI resolved internally. allowedScope is the admin-declared selector allowlist grants are checked against; observedScope is what discovery actually saw and is informational only.
+ */
+export interface DataSource {
+  /**
+   * Owning tenant (org) identifier.
+   */
+  tenantId: string;
+  /**
+   * Tenant-unique data-source identifier.
+   */
+  sourceId: string;
+  connector: DataSourceConnector;
+  /**
+   * Human-readable name shown to admins and builders.
+   */
+  displayName: string;
+  endpoint: DataSourceEndpoint;
+  /**
+   * secretref URI naming the platform-held credential for this source. The referenced value never crosses this boundary.
+   */
+  credentialRef: string;
+  provisioningMode: DataSourceProvisioningMode;
+  /**
+   * Admin-declared selector allowlist (e.g. schema.table patterns) that grant scopes are validated against.
+   */
+  allowedScope: string[];
+  /**
+   * Selectors discovery actually observed on the source. Informational; never widens allowedScope.
+   */
+  observedScope?: string[];
+  /**
+   * Whether builders may request grants against this source.
+   */
+  requestableByBuilders: boolean;
+  status: DataSourceStatus;
+}
+/**
+ * Connector endpoint coordinates. host is always present; database vs project/workspace depends on the connector family.
+ */
+export interface DataSourceEndpoint {
+  /**
+   * Network host (or warehouse endpoint) of the source.
+   */
+  host: string;
+  /**
+   * TCP port; absent where the connector implies it.
+   */
+  port?: number;
+  /**
+   * Database name (postgres/redshift-style connectors).
+   */
+  database?: string;
+  /**
+   * Project identifier (bigquery-style connectors).
+   */
+  project?: string;
+  /**
+   * Workspace identifier (databricks-style connectors).
+   */
+  workspace?: string;
+}