@fourier-labs/harbour-contracts 0.3.1 → 0.5.0

package/dist/gen-ts/version-state-machine.js

@@ -0,0 +1,45 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export const States = {
+    QUEUED: "QUEUED",
+    ANALYZING: "ANALYZING",
+    TRANSFORMING: "TRANSFORMING",
+    VALIDATING: "VALIDATING",
+    BUILDING: "BUILDING",
+    VERIFYING: "VERIFYING",
+    GATING: "GATING",
+    LIVE: "LIVE",
+    AWAITINGPROMOTION: "AWAITING-PROMOTION",
+    PROMOTING: "PROMOTING",
+    FAILED: "FAILED",
+    STALE: "STALE",
+};
+export const Environments = {
+    Preview: "preview",
+    Prod: "prod",
+};
+const legalTransitions = {
+    "preview": {
+        "QUEUED": { "ANALYZING": true, "FAILED": true, "STALE": true },
+        "ANALYZING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+        "TRANSFORMING": { "VALIDATING": true, "FAILED": true, "STALE": true },
+        "VALIDATING": { "BUILDING": true, "TRANSFORMING": true, "FAILED": true, "STALE": true },
+        "BUILDING": { "VERIFYING": true, "FAILED": true, "STALE": true },
+        "VERIFYING": { "GATING": true, "FAILED": true, "STALE": true },
+        "GATING": { "LIVE": true, "FAILED": true, "STALE": true },
+        "LIVE": { "AWAITING-PROMOTION": true },
+        "AWAITING-PROMOTION": { "PROMOTING": true },
+        "PROMOTING": { "LIVE": true, "FAILED": true },
+    },
+    "prod": {
+        "QUEUED": { "PROMOTING": true, "FAILED": true },
+        "PROMOTING": { "LIVE": true, "FAILED": true },
+    },
+};
+const terminalStates = new Set(["FAILED", "STALE"]);
+/** True iff from→to is a legal edge for environment in the T1a state machine. */
+export function canTransition(environment, from, to) {
+    return Boolean(legalTransitions[environment]?.[from]?.[to]);
+}
+/** True iff the state is terminal (FAILED, STALE). */
+export function isTerminal(state) { return terminalStates.has(state); }

package/dist/gen-ts/version-state.js

@@ -0,0 +1,3 @@
+/* eslint-disable */
+// Code generated by tools/gen/gen.mjs from schema/*.json. DO NOT EDIT.
+export {};

package/dist/resolver/index.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Harbour AI policy resolver — the ONE hardened five-layer merge, shipped with
+ * the contracts package so governance and the gateway resolve identically
+ * (completion-spec D-6). Extracted from
+ * `harbour-governance-control-plane/src/ai-governance.ts` (merge machinery)
+ * and `src/ai-platform-controls.ts` (platform baseline + classification
+ * floor) as PURE functions over the contracted snapshot types: no store, no
+ * service, no I/O, no crypto.
+ *
+ * Five-layer resolution per LLD §6.3 (lines 525-542): platform baseline →
+ * data-classification minimum → tenant published defaults → application
+ * published assignment → version runtime contract. Later layers narrow
+ * earlier ones; an application snapshot never replaces the tenant snapshot.
+ *
+ * The merge is TENANT-WINS by default. Three structural defenses carried over
+ * from the governance hardening rounds:
+ *
+ * - `narrowField` — ONE CONTROL, ONE GUARD. The clamp is the single statement
+ *   of each control and the rejection is DERIVED from it (a value the clamp
+ *   had to change is an attempted widening, which §6.3 line 540 requires to be
+ *   rejected rather than silently narrowed), so deleting the clamp always
+ *   changes an observable outcome and every control is mutation-testable.
+ * - `narrowEntry` closes the FIELD-level default: only fields on an explicit
+ *   per-family opt-in list may differ from the tenant entry; every other field
+ *   — including any field a future contract revision adds — is tenant-locked.
+ * - `mergeKeyedFamily` closes the ENTRY-level default: both directions of the
+ *   key set (a tenant key the application omits, and an application key the
+ *   tenant never published) must be stated per family; there is no permissive
+ *   fallthrough for an unenumerated key.
+ *
+ * The `Narrowed` brand is the registry's type-level counterpart: a family
+ * merge must RETURN a `Narrowed` value, and the brand is granted only by the
+ * narrowing combinators, so a passthrough `(tenant, application) =>
+ * application` fails to compile and a deliberate escape requires a visible
+ * cast.
+ */
+import type { AiPolicySnapshot, AiPolicyGuardrailRule } from "../gen-ts/ai-policy-snapshot.js";
+export type { AiPolicySnapshot, AiPolicyGuardrailRule, AiPolicyGuardrailParameters, AiPolicyRetention, AiPolicyRoute, AiPolicyRuleSet, } from "../gen-ts/ai-policy-snapshot.js";
+/** Version of the resolver ALGORITHM (merge rules + floor artifacts), not of
+ * the package. Consumers record it beside the composite policy digest so a
+ * behavioral divergence between two deployments is attributable to a resolver
+ * revision rather than guessed at. Bump on ANY change to the merge rules, the
+ * platform baseline, or the classification minimums. */
+export declare const RESOLVER_VERSION = "1.0.0";
+export type AiProviderType = "openai" | "anthropic" | "gemini" | "openrouter";
+export type AiCaptureMode = "OFF" | "BEST_EFFORT" | "REQUIRED";
+export type AiDataClassification = "Green" | "Yellow" | "Orange" | "Red";
+export type AiGuardrailAction = "ALLOW" | "OBSERVE" | "REDACT" | "BLOCK";
+export type AiGuardrailMinimum = {
+    ruleId: string;
+    detectorId: string;
+    detectorVersion: string;
+    phase: "input" | "output";
+    action: AiGuardrailAction;
+};
+/** One control set. Every allowlist is an upper bound on what later layers may
+ * permit, every numeric field is a ceiling, and `requiredGuardrails` is a
+ * floor that later layers may only strengthen. */
+export type AiControlSet = {
+    permittedProviderTypes: AiProviderType[];
+    requireApprovedModels: boolean;
+    maxCaptureMode: AiCaptureMode;
+    maxRetentionDays: number;
+    maxRequestBytes: number;
+    maxInputTokens: number;
+    maxOutputTokens: number;
+    maxRequestsPerMinute: number;
+    maxTokensPerMinute: number;
+    maxMonthlyBudgetMicroUsd: number;
+    permittedRequestFields: {
+        temperature: boolean;
+        maxOutputTokens: boolean;
+        responseFormat: boolean;
+        tools: boolean;
+    };
+    requiredGuardrails: AiGuardrailMinimum[];
+};
+export type AiPlatformBaselineArtifact = {
+    schema: "harbour.ai-platform-baseline/1.0";
+    artifactVersion: string;
+    controls: AiControlSet;
+};
+export type AiClassificationMappingArtifact = {
+    schema: "harbour.ai-classification-minimums/1.0";
+    artifactVersion: string;
+    /** LLD §6.3 line 538: applies until the security-assurance workflow stamps a
+     * classification and the tenant policy names its own default floor. */
+    defaultClassification: AiDataClassification;
+    classes: Record<AiDataClassification, AiControlSet>;
+};
+export declare const AI_PLATFORM_BASELINE: AiPlatformBaselineArtifact;
+/** LLD §17 item 11 (line 1225) leaves the per-class values to be agreed with
+ * the security-assurance workstream; these are the initial code-owned values
+ * and are versioned by `artifactVersion` plus `RESOLVER_VERSION`. */
+export declare const AI_CLASSIFICATION_MINIMUMS: AiClassificationMappingArtifact;
+export declare const CAPTURE_MODE_RANK: Record<AiCaptureMode, number>;
+/** Ascending strictness. Used to fail closed on the classification layer: an
+ * application-published snapshot may raise the class but never lower it. */
+export declare const CLASSIFICATION_RANK: Record<AiDataClassification, number>;
+export declare function strictestClassification(left: AiDataClassification, right: AiDataClassification): AiDataClassification;
+export declare const GUARDRAIL_ACTION_RANK: Record<AiGuardrailAction, number>;
+/** Element-wise most restrictive of two control sets. Used to fold the
+ * classification minimum into the platform baseline before any tenant or
+ * application layer is applied. */
+export declare function narrowControls(left: AiControlSet, right: AiControlSet): AiControlSet;
+/** Platform baseline folded with one classification's minimum control set:
+ * layers 1 and 2 of §6.3 as a single floor that later layers may only narrow. */
+export declare function classificationFloor(classification: AiDataClassification): AiControlSet;
+/** Every rejection carries a stable code and HTTP-shaped status so both
+ * resolver consumers surface identical errors for identical escapes. */
+export declare class AiPolicyResolutionError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** Stable codes for a later layer that tried to widen, not narrow, an earlier
+ * one (LLD §6.3 line 540). The audit acceptance criterion is rejection, never
+ * silent narrowing. */
+export declare const WIDENS_TENANT_ALLOWLIST = "configuration_widens_tenant_allowlist";
+export declare const RAISES_TENANT_CEILING = "configuration_raises_tenant_ceiling";
+export declare const WEAKENS_TENANT_GUARDRAIL = "configuration_weakens_tenant_guardrail";
+/** An application entry tried to change a field only the tenant may set. */
+export declare const OVERRIDES_TENANT_LOCKED = "configuration_overrides_tenant_locked_field";
+/** The merge output outgrew a `maxItems` bound of the snapshot contract. */
+export declare const EXCEEDS_CONTRACT_BOUNDS = "configuration_exceeds_contract_bounds";
+/** Canonical JSON with sorted object keys — the equality the tenant-locked
+ * comparisons are stated in, so key order can never disguise a difference. */
+export declare function canonicalJson(value: unknown): string;
+/** The snapshot fields that identify and seal a snapshot rather than state a
+ * control. Everything a snapshot carries that is NOT one of these is a policy
+ * family that resolution must merge.
+ *
+ * Stated as an EXCLUSION on purpose: with `Omit<>`, a new snapshot field is a
+ * member of `AiScopePolicySet` the moment it is declared, and
+ * `SCOPE_FAMILY_MERGES` below (a `Record` over `keyof AiScopePolicySet`) fails
+ * to compile until someone states its merge rules. A `Pick<>` here previously
+ * let a seventh family parse, store, and enter the snapshot digest while being
+ * silently dropped from the effective policy. */
+type AiPolicySnapshotIdentity = "schema" | "scope" | "revision" | "publishedAt" | "contentDigest" | "baselineDigest" | "classificationMinimum";
+/** The resource families a scope snapshot contributes to resolution. */
+export type AiScopePolicySet = Omit<AiPolicySnapshot, AiPolicySnapshotIdentity>;
+/** The merged control set every later layer narrowed but could not weaken. */
+export type AiEffectivePolicy = AiScopePolicySet & {
+    classification: AiDataClassification;
+};
+/** The assigned model aliases: which capabilities a deployment may use and
+ * which route serves each. Mirrors `AiRuntimeContract.modelAliases`. */
+export type AiModelAliasAssignment = {
+    generation?: string;
+    embeddings?: string;
+};
+declare const narrowedBrand: unique symbol;
+/** Granted only by the narrowing combinators (`mergeKeyedFamily`,
+ * `narrowEntry`); a family merge must return it, so a compliant-looking
+ * passthrough fails to compile. */
+export type Narrowed<T> = T & {
+    readonly [narrowedBrand]: true;
+};
+/** ONE CONTROL, ONE GUARD: the clamp is the single statement of the control
+ * and the rejection is derived from it, so deleting the clamp always changes
+ * an observable outcome and the control is mutation-testable. */
+export declare function narrowField<T>(tenant: T, application: T, clamp: (tenantValue: T, applicationValue: T) => T, code: string, describe: () => string): T;
+/** Merges one application entry over its tenant counterpart so that
+ * TENANT-WINS is the DEFAULT: only fields named in `narrowable` are replaced
+ * by the caller-computed `narrowed` values; every other field — including any
+ * field a future contract revision adds — must equal the tenant value or the
+ * entry is rejected. Spreading the application entry is never correct here. */
+export declare function narrowEntry<T extends object>(tenant: T, application: T, narrowable: readonly string[], narrowed: Partial<T>, describe: (field: string) => string): Narrowed<T>;
+/** What an application entry whose key the tenant never published means. The
+ * discriminant is required, so a family added by a later contract revision
+ * cannot inherit a permissive answer by omission. */
+export type AddedEntryRule<T> = {
+    decision: "reject";
+    code: string;
+    describe: (entry: T) => string;
+}
+/** `admit` returns the entry to merge in, or throws — an added entry may
+ * need more than one guard (an added guardrail must both restrict AND carry
+ * no parameters the tenant never bounded). */
+ | {
+    decision: "permit_when_restrictive";
+    admit: (entry: T) => T;
+};
+/** The complete, explicit merge contract of one key-addressed family. Both
+ * directions of the key set must be stated; leaving either implicit is exactly
+ * how the escape rounds arose. */
+export type KeyedMergeRules<T> = {
+    key: (entry: T) => string;
+    /** A tenant key the application does not repeat. `drop` for allowlists,
+     * where omission is the narrowing; `keep` for restriction sets and ceiling
+     * sets, where omission must not delete the tenant's control. */
+    omittedByApplication: "drop" | "keep";
+    added: AddedEntryRule<T>;
+    /** Applied when the keys match; every family delegates to `narrowEntry`. */
+    narrow: (tenant: T, application: T) => T;
+};
+/** The single path by which any key-addressed family merges: no per-family
+ * loop can quietly grow its own `if (!base)` branch. */
+export declare function mergeKeyedFamily<T>(tenant: readonly T[], application: readonly T[], rules: KeyedMergeRules<T>): Narrowed<T[]>;
+/** A grant can only flow down: an application may drop a capability, but may
+ * neither assign one the tenant did not assign nor repoint an assignment at
+ * another route. `{ ...tenant, ...application }` made the application the
+ * authority for both. */
+export declare function mergeModelAliases(tenant: AiModelAliasAssignment, application: AiModelAliasAssignment): AiModelAliasAssignment;
+/** `Record`-over-`keyof AiScopePolicySet` is the exhaustiveness mechanism:
+ * because `AiScopePolicySet` is an `Omit<>` of the snapshot rather than a
+ * `Pick<>`, a new snapshot family is a new key of this mapped type, and this
+ * declaration fails to compile until its merge rules are stated. */
+export type ScopeFamilyMerges = {
+    [K in keyof AiScopePolicySet]-?: (tenant: AiScopePolicySet[K], application: AiScopePolicySet[K]) => Narrowed<AiScopePolicySet[K]>;
+};
+export declare function scopeFamilies(): Array<keyof AiScopePolicySet>;
+/** The single-scope projection: the snapshot's policy families with the
+ * identity fields subtracted, re-checked against the contract bounds. */
+export declare function scopePolicySet(snapshot: AiPolicySnapshot): AiScopePolicySet;
+/** Layers 3 and 4 of §6.3: the application/environment snapshot narrows the
+ * tenant snapshot per family — intersection for allowlists, minimum for
+ * numeric ceilings, union for guardrail restrictions — and any attempt to
+ * widen is rejected. Driven off `SCOPE_FAMILY_MERGES` rather than written out,
+ * so there is no place left for a family to be answered by omission. */
+export declare function mergeScopeSnapshots(tenant: AiPolicySnapshot, application: AiPolicySnapshot): AiScopePolicySet;
+/** An application entry the merge admits — today only a restricting guardrail
+ * the tenant never published — is the one way the merge OUTPUT can be larger
+ * than either input, so the merged set and the effective set are both
+ * re-validated against every `maxItems` in
+ * `schema/ai-policy-snapshot.schema.json`. */
+export declare function assertContractBounds<T extends AiScopePolicySet>(set: T): T;
+/** The floor is not negotiable, so it clamps the merged tenant/application
+ * set instead of rejecting it: a stamped classification arrives after
+ * publication and must still bind. */
+export declare function applyControlFloor(merged: AiScopePolicySet, floor: AiControlSet, classification: AiDataClassification): AiEffectivePolicy;
+/** A platform-required rule's IDENTITY is non-negotiable and replaces whatever
+ * held the id (a snapshot could otherwise pre-occupy a required rule id with a
+ * NOOP detector of its own choosing); only `action` is negotiable, and only
+ * upward. `parameters` go with the displaced entry, because they tune that
+ * entry's detector rather than the platform's. */
+export declare function applyRequiredGuardrails(guardrails: AiPolicyGuardrailRule[], required: AiGuardrailMinimum[]): AiPolicyGuardrailRule[];
+/** The snapshot half of five-layer resolution, composed: classification from
+ * the published minimums (strictest wins; the platform default applies when no
+ * layer states one) optionally raised by a stamped classification, the
+ * tenant/application merge (a single present scope resolves alone), then the
+ * classification floor. Version controls (mode, gateway endpoint, alias
+ * grant) live on the published-configuration wrapper, which is not part of
+ * the snapshot contract — both consumers resolve them beside this call, using
+ * `mergeModelAliases` for the grant. */
+export declare function resolveEffectiveScopePolicy(input: {
+    tenant?: AiPolicySnapshot;
+    application?: AiPolicySnapshot;
+    /** The security-assurance stamp for the deployment version, when one
+     * exists. It can raise the class above what the snapshots publish, never
+     * lower it. */
+    stampedClassification?: AiDataClassification;
+}): {
+    classification: AiDataClassification;
+    effective: AiEffectivePolicy;
+};