@harperfast/harper 5.3.0-beta.3 → 5.3.0-beta.4

package/resources/models/types.ts

@@ -11,8 +11,19 @@ export interface Models {
 	embed(input: string | string[], opts?: EmbedOpts): Promise<Float32Array[]>;
 	generate(input: GenerateInput, opts?: GenerateOpts): Promise<GenerateResult>;
 	generateStream(input: GenerateInput, opts?: GenerateOpts): AsyncIterable<GenerateChunk>;
+	/** Choose from a closed, schema-defined set and return the distribution over it. See #2779. */
+	decide<T = unknown>(
+		state: DecideInput,
+		schema: DecisionSchema,
+		opts: RecordedDecideOpts
+	): Promise<RecordedDecision<T>>;
+	decide<T = unknown>(state: DecideInput, schema: DecisionSchema, opts?: DecideOpts): Promise<Decision<T>>;
+	/** The durable record of a decision made with `persist: true`, with its recorded outcome, or undefined. See #2840. */
+	getDecision<T = unknown>(id: string): Promise<DecisionRecord<T> | undefined>;
+	/** Record what actually happened for a decision: its truth, the action taken, or both. See #2840. */
+	recordOutcome<T = unknown>(id: string, outcome: OutcomeReport): Promise<DecisionRecord<T>>;
 	/** Register a custom backend under a logical id, selectable via `opts.model`. See #1325. */
-	registerBackend(kind: 'embedding' | 'generative', id: string, backend: ModelBackend): void;
+	registerBackend(kind: ModelKind, id: string, backend: ModelBackend): void;
 	/** Build a `ModelBackend` from a spec; pair with `registerBackend`. See #1325. */
 	defineBackend(spec: DefineBackendSpec): ModelBackend;
 	/** Replace the model selection policy with a custom router. See #1326. */
@@ -25,22 +36,62 @@ export interface ModelBackend {
 	embed?(input: string | string[], opts: BackendOpts<EmbedOpts>): Promise<ModelCallResult<Float32Array[]>>;
 	generate?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): Promise<ModelCallResult<GenerateResult>>;
 	generateStream?(input: GenerateInput, opts: BackendOpts<GenerateOpts>): AsyncIterable<GenerateChunk>;
+	decide?(
+		state: DecideInput,
+		schema: DecisionSchema,
+		opts: BackendOpts<DecideOpts>
+	): Promise<ModelCallResult<DecisionOutput<unknown>>>;
+	/**
+	 * Score every entry of `choices` as the answer to `input` from the model's own likelihoods
+	 * (#2838): one finite, unnormalized log-likelihood per choice, in order. A call the backend
+	 * cannot score (too many choices for its alternatives list, a model that rejects
+	 * log-probabilities, a response with no scored label) throws `ChoiceScoringUnsupportedError`
+	 * so the caller can fall back; any other error is a failure.
+	 */
+	scoreChoices?(
+		input: GenerateInput,
+		choices: readonly string[],
+		opts: BackendOpts<ScoreChoicesOpts>
+	): Promise<ModelCallResult<ChoiceScores>>;
 }
 
+/** Registry kinds a backend is mapped under; a `decision` backend implements `decide` (#2779). */
+export type ModelKind = 'embedding' | 'generative' | 'decision';
+
 export interface ModelCapabilities {
 	embed: boolean;
 	generate: boolean;
 	stream: boolean;
 	tools: boolean;
 	adapters: boolean;
+	/** Implements `decide`. Optional so pre-#2779 backends stay source-compatible; absent reads as false. */
+	decide?: boolean;
+	/** `decide` probabilities are calibrated as returned. Absent reads as false. */
+	calibrated?: boolean;
+	/** Implements `scoreChoices`. Absent reads as false. */
+	scoreChoices?: boolean;
+	/** `decide` returns a no-match score for leaves that opt in with `noMatch: true` (#2846). Absent reads as false. */
+	noMatch?: boolean;
+	/** That no-match score is calibrated as returned. Absent reads as false. */
+	calibratedNoMatch?: boolean;
+	/**
+	 * `generate` sends `responseFormat: { schema }` to the provider as a decoding constraint rather
+	 * than a hint. Says what Harper sends, not what a remote endpoint honors. Absent reads as false.
+	 */
+	structuredOutput?: boolean;
+	/**
+	 * The most choices one `scoreChoices` call accepts. Absent means no stated limit. A limit, not a
+	 * capability: it cannot be required, and a call above it is declined without a request.
+	 */
+	maxScoredChoices?: number;
 }
 
-/** A capability a call can require of its backend (a key of `ModelCapabilities`). */
-export type Capability = keyof ModelCapabilities;
+/** A capability a call can require of its backend (a boolean key of `ModelCapabilities`). */
+export type Capability = Exclude<keyof ModelCapabilities, 'maxScoredChoices'>;
 
 /** What the router is asked to resolve for a single call. See #1326. */
 export interface RouteRequest {
-	kind: 'embedding' | 'generative';
+	kind: ModelKind;
 	/** Logical name from `opts.model` (a role or a concrete backend id); defaults to `'default'`. */
 	logicalName: string;
 	/** Capabilities the chosen backend must satisfy — explicit `opts.requires` plus any auto-derived (e.g. tools present in the input). */
@@ -74,10 +125,22 @@ export interface DefineBackendSpec {
 	embed?: ModelBackend['embed'];
 	generate?: ModelBackend['generate'];
 	generateStream?: ModelBackend['generateStream'];
+	decide?: ModelBackend['decide'];
+	scoreChoices?: ModelBackend['scoreChoices'];
 	/** Backend supports tool calls in `generate` / `generateStream`. Default `false`. */
 	tools?: boolean;
 	/** Backend supports per-call LoRA / adapter selection. Default `false`. */
 	adapters?: boolean;
+	/** `decide` probabilities are calibrated as returned. Default `false`. */
+	calibrated?: boolean;
+	/** `decide` returns a no-match score for opted-in leaves. Default `false`. */
+	noMatch?: boolean;
+	/** That no-match score is calibrated as returned. Default `false`. */
+	calibratedNoMatch?: boolean;
+	/** `generate` sends `responseFormat: { schema }` as a decoding constraint. Default `false`. */
+	structuredOutput?: boolean;
+	/** The most choices one `scoreChoices` call accepts, a positive integer. Default: no limit. */
+	maxScoredChoices?: number;
 }
 
 export type EmbedOpts = {
@@ -89,6 +152,170 @@ export type EmbedOpts = {
 	signal?: AbortSignal;
 };
 
+/** Text, or JSON-serializable program state, for `decide`. */
+export type DecideInput = string | object;
+
+/**
+ * One leaf of a decision schema: a closed set every backend family can score. `enum` holds
+ * 2..255 distinct values of one type; an integer range spans at most 255 values; booleans order
+ * as `[false, true]` for tie-breaking.
+ */
+export type DecisionLeaf = { description?: string; noMatch?: boolean } & (
+	| { enum: readonly string[] | readonly number[] | readonly boolean[] }
+	| { type: 'boolean' }
+	| { type: 'integer'; minimum: number; maximum: number }
+);
+
+/** A decision schema: one leaf, or one level of named leaves. Deeper nesting is deliberately unsupported. */
+export type DecisionSchema =
+	DecisionLeaf | { type: 'object'; description?: string; properties: Record<string, DecisionLeaf> };
+
+export type DecideOpts = {
+	model?: string;
+	/** Capabilities the chosen backend must satisfy, e.g. `['calibrated']`; the router filters candidates (#1326). */
+	requires?: Capability[];
+	/** Task framing beyond the schema's own descriptions. */
+	instructions?: string;
+	signal?: AbortSignal;
+	/**
+	 * `true` commits a durable record of the decision to `hdb_model_decisions` before returning, so its
+	 * outcome can be recorded later; the result then carries its `id`. Default `false`: nothing is stored
+	 * beyond the per-call analytics row, as with `embed` and `generate`.
+	 */
+	persist?: boolean;
+};
+
+/** Options that record the decision, so the result is a `RecordedDecision` with an `id`. */
+export type RecordedDecideOpts = DecideOpts & { persist: true };
+
+export interface DecisionOutcome {
+	value: unknown;
+	probability: number;
+}
+
+/**
+ * What a `decision` backend returns for one call. For a leaf schema `distribution` is required
+ * and complete (one entry per allowed value, summing to one); for an object schema `fields`
+ * carries one such entry per property. The facade derives `value` and `probability`, so a
+ * backend may omit them; a `value` it does supply must be a most-probable outcome, and on a
+ * tie it leads the distribution.
+ */
+export interface DecisionOutput<T = unknown> {
+	value?: T;
+	probability?: number;
+	distribution?: DecisionOutcome[];
+	fields?: Record<string, DecisionOutput<unknown>>;
+	/** For a leaf that opted in: the score in [0, 1] that the input matches none of the allowed values. */
+	noMatch?: number;
+	calibrated?: boolean;
+	/**
+	 * Opaque identity of the configuration that produced the scores (sampling, scoring method,
+	 * prompt revision), stored with the decision so calibration is keyed per configuration (#2841).
+	 */
+	signature?: string;
+}
+
+/**
+ * Result of `models.decide`. For a leaf schema `value` is the first entry of `distribution`,
+ * which is sorted descending with ties in schema order unless the backend chose one of the tied
+ * values; `probability` is its entry. For an object schema
+ * `value` is assembled from each field's marginal argmax — a combination no single sample may
+ * have produced — and the marginals live in `fields`.
+ */
+export interface Decision<T = unknown> {
+	/** Present only when the call passed `persist: true`: the cluster-unique id of the decision's record in `hdb_model_decisions`, committed before the decision is returned; pass it to `recordOutcome` (#2840). */
+	id?: string;
+	value: T;
+	probability?: number;
+	distribution?: DecisionOutcome[];
+	fields?: Record<string, FieldDecision>;
+	/** Leaf schemas that opted in: the score that the input matches none of the allowed values (#2846). */
+	noMatch?: number;
+	/** Whether the probabilities come from a calibrated source, as the backend reports it. */
+	calibrated: boolean;
+	usage?: TokenUsage;
+}
+
+/** A decision made with `persist: true`: its `id` is always present. */
+export type RecordedDecision<T = unknown> = Decision<T> & { id: string };
+
+/** One field's marginal in an object-schema `Decision`. */
+export interface FieldDecision {
+	value: unknown;
+	probability: number;
+	distribution: DecisionOutcome[];
+	/** Fields that opted in: the no-match score. */
+	noMatch?: number;
+}
+
+export type ScoreChoicesOpts = {
+	model?: string;
+	/** Capabilities the chosen backend must satisfy, beyond `scoreChoices` itself; the router filters candidates (#1326). */
+	requires?: Capability[];
+	signal?: AbortSignal;
+};
+
+/** Unnormalized; the caller normalizes. */
+export interface ChoiceScores {
+	logLikelihoods: number[];
+}
+
+/** What turned out to be true for a decision: an allowed value, none of them, or not known. Tagged, so no label is a sentinel. */
+export type OutcomeTruth = { kind: 'value'; value: unknown } | { kind: 'noMatch' } | { kind: 'unknown' };
+
+/** What the application did with a decision: acted on a value, routed it as no-match, abstained by policy, or not known. */
+export type OutcomeAction =
+	{ kind: 'value'; value: unknown } | { kind: 'noMatch' } | { kind: 'abstained' } | { kind: 'unknown' };
+
+/** The facts reported for one leaf: either, or both. Each is stored on its own, so reports never overwrite each other. */
+export interface LeafOutcomeReport {
+	truth?: OutcomeTruth;
+	action?: OutcomeAction;
+}
+
+/** A `recordOutcome` report: leaf facts for a leaf schema, or per-field facts for an object schema. */
+export type OutcomeReport = LeafOutcomeReport | { fields: Record<string, LeafOutcomeReport> };
+
+export interface RecordedLeafOutcome extends LeafOutcomeReport {
+	truthAt?: number;
+	actionAt?: number;
+}
+
+export type RecordedOutcome = RecordedLeafOutcome | { fields: Record<string, RecordedLeafOutcome> };
+
+/**
+ * The durable record of one decision (#2840): what was asked, what was answered, who answered,
+ * and what was recorded afterwards. Written once by `decide`; only `outcome` grows.
+ */
+export interface DecisionRecord<T = unknown> {
+	id: string;
+	/** The `hdb_model_calls` row of the call that produced it; correlation only. */
+	callId: number;
+	at: number;
+	/** When the record and its facts expire; a fact never extends it. */
+	expiresAt: number;
+	tenant?: string;
+	app?: string;
+	backend: string;
+	model: string;
+	signature?: string;
+	/** Identity of the `models` config block in force when the decision was made. */
+	configHash?: string;
+	/** sha256 of the per-call `instructions`, when any were given. */
+	instructionsHash?: string;
+	/** The schema's allowed values, without descriptions. */
+	schema: DecisionSchema;
+	/** Identity of the full schema, descriptions included. */
+	schemaHash: string;
+	value: T;
+	probability?: number;
+	distribution?: DecisionOutcome[];
+	fields?: Record<string, FieldDecision>;
+	noMatch?: number;
+	calibrated: boolean;
+	outcome: RecordedOutcome;
+}
+
 export type GenerateOpts = {
 	model?: string;
 	/** Capabilities the chosen backend must satisfy (e.g. `['tools']`); the router selects/filters candidates accordingly. Tools present in the input are auto-required. (#1326) */

package/security/DESIGN.md

@@ -2,7 +2,7 @@
 
 Authentication tokens, OIDC exchange and TLS material.
 
-**Read this when:** touching `tokenAuthentication.ts`, `impersonation.ts`, `authn/oidc/` or `keys.ts`.
+**Read this when:** touching `tokenAuthentication.ts`, `impersonation.ts`, `authn/oidc/`, `keys.ts` or `certificateVerification/`.
 
 Index of every design note: [DESIGN.md](../DESIGN.md).
 
@@ -33,7 +33,7 @@ Four constraints that look like choices but are not:
 
    Naming `sql` in a scope grants the SQL interface, not unrestricted DML through it: a write statement additionally requires its matching data operation (`insert`/`update`/`delete`) in scope. That is what keeps `read_only` — which expands to include `sql` — from admitting a DELETE, given that `verifyPermsAST` returns early for a super_user before any table check runs.
 
-`hdb_oidc_token_use` (created lazily via `table()`, not the system schema) records spent tokens keyed on a SHA-256 of the token itself, with `expiresAt` past the token's own expiry. Hashed rather than stored, so the table never holds a credential; keyed on the token's **signed input** (`header.payload`) rather than `jti` because not every issuer emits one (Azure uses `uti`). Not on the whole token string: the signature segment is covered by nothing, and base64url decoding ignores the surplus low bits of its final character, so 16 distinct spellings of an RS256 signature decode to the same bytes, all verify, and all hash differently — one leaked token would buy 16 exchanges. ES\* malleability (`s → n−s`) is a second such vector. The signed input is exactly what the issuer asserted, so every variant collapses to one fingerprint. The get-then-put is not atomic and does not claim to be: a concurrent replay is not a privilege escalation, since whoever holds the token could obtain one operation token anyway.
+`hdb_oidc_token_use` (declared on every node at every start by `tokenUseTable.ts`, so a node that never exchanges still removes the rows replicated to it — see dataLayer/DESIGN.md, "System table bootstrap") records spent tokens keyed on a SHA-256 of the token itself, each expiring (record metadata, replicated with the row) past the token's own expiry. Hashed rather than stored, so the table never holds a credential; keyed on the token's **signed input** (`header.payload`) rather than `jti` because not every issuer emits one (Azure uses `uti`). Not on the whole token string: the signature segment is covered by nothing, and base64url decoding ignores the surplus low bits of its final character, so 16 distinct spellings of an RS256 signature decode to the same bytes, all verify, and all hash differently — one leaked token would buy 16 exchanges. ES\* malleability (`s → n−s`) is a second such vector. The signed input is exactly what the issuer asserted, so every variant collapses to one fingerprint. The get-then-put is not atomic and does not claim to be: a concurrent replay is not a privilege escalation, since whoever holds the token could obtain one operation token anyway.
 
 ## Scoped tokens and synthetic-role identity (`security/tokenAuthentication.ts`, `security/impersonation.ts`)
 
@@ -150,6 +150,26 @@ the latch back on a synchronous throw or a rejected callback promise (equality-g
 rejection cannot unlatch a newer reload) — the latch means "last successfully applied", so the
 periodic poll can heal a lost `hdb_certificate` write instead of deduplicating it forever.
 
+## Client-certificate revocation checking keeps three tables (`security/certificateVerification/`)
+
+`verificationTables.ts` declares them, and every writable start and the verification path apply the same
+declarations (dataLayer/DESIGN.md, "System table bootstrap"). A row's expiry is record metadata; a table's
+`expiration` is only the fallback for a row written without one.
+
+- A verdict (`hdb_certificate_cache`) expires `cacheTtl` after its check because `CertificateVerificationSource`
+  sets `context.expiresAt`: a caching table decides staleness by the stored expiry, and a source fill stores
+  `sourceContext.expiresAt`, never a field the source returns. `createCacheKey` hashes a key version, so a
+  verdict cached before verdicts carried an expiry, which has none and would read as fresh forever, is never
+  read again.
+- A revocation (`hdb_revoked_certificates`) lives until `crl_next_update + gracePeriod`, the window
+  `performCRLCheck` honors while it decides by `crl_next_update`. Expiring it at `nextUpdate` made that branch
+  unreachable and reported a revoked certificate on an overdue CRL as good.
+- A CRL's revocations replace the previous set all or nothing, in a transaction of their own rather than the
+  verdict fill's `performCRLCheck` runs in, so other checks see a complete set once it commits. The check that
+  downloaded the CRL decides from the CRL itself: by the time it could read the table, another worker may have
+  replaced the set with a different generation of that CRL. A check answered by a cached CRL reads the table
+  outside the verdict fill's transaction, whose LMDB snapshot misses rows committed after it.
+
 ## A component-facing export needs BOTH `index.ts` and `getHarperExports` (`security/jsLoader.ts`, `index.ts`)
 
 Adding `export { x } from './…'` to `index.ts` publishes `x` on the `harper` **package** but does not

package/security/authn/oidc/tokenExchange.ts

@@ -10,7 +10,6 @@
 import jwt from 'jsonwebtoken';
 import Joi from 'joi';
 import { createHash } from 'node:crypto';
-import { table, type Table } from '../../../resources/databases.ts';
 import { ClientError } from '../../../utility/errors/hdbError.ts';
 import { validateBySchema } from '../../../validation/validationWrapper.ts';
 import { loggerWithTag } from '../../../utility/logging/logger.ts';
@@ -24,6 +23,7 @@ import { matchTrustPolicyClaims } from './claims.ts';
 import { normalizeIssuer } from './jwks.ts';
 import { profileForIssuer, type IdentityProviderProfile } from './providers/index.ts';
 import { loadEnabledPolicies } from './trustPolicyOperations.ts';
+import { declareTokenUseTable } from './tokenUseTable.ts';
 import type { OidcTrustPolicy, TokenClaims } from './types.ts';
 
 const logger = loggerWithTag('oidc-trust');
@@ -41,8 +41,6 @@ const REPLAY_RECORD_PADDING_MS = 120_000;
 /** Real identity tokens are ~1-2 KB; this bounds what we are willing to even parse. */
 const MAX_TOKEN_LENGTH = 8192;
 
-const TOKEN_USE_TABLE = 'hdb_oidc_token_use';
-
 /**
  * Spent identity tokens, keyed by the fingerprint below and expiring with the token, so the table
  * stays proportional to in-flight tokens rather than to deploy history and never holds a credential.
@@ -52,8 +50,6 @@ const TOKEN_USE_TABLE = 'hdb_oidc_token_use';
  * not a privilege escalation: whoever holds the token could obtain one operation token regardless.
  * What it stops is the realistic case, a token that leaks after a legitimate run and is reused
  * inside its window.
- *
- * table() also registers into `databases.system`, so the lookup finds it after the first call.
  */
 let tokenUseTable: any;
 
@@ -63,29 +59,7 @@ export function clearTokenUseTableCache(): void {
 }
 
 function getTokenUseTable(): any {
-	// Memoized per process, but `table()` is NOT skipped merely because the table already exists.
-	// The systemSchema stub and the 5.3.0 directive declare only the primary key — the `expiresAt`
-	// TTL is not expressible through CreateTableObject — so this call is what actually installs the
-	// TTL, layered on top of the bootstrap. Short-circuiting on existence would mean a table that
-	// arrived any other way (bootstrap, replication, restore, a manual create_table) never gets it,
-	// and replay records would then accumulate in a system table forever. hdb_certificate_cache
-	// does the same two-step for the same reason.
-	tokenUseTable ??= table<Table>({
-		table: TOKEN_USE_TABLE,
-		database: 'system',
-		// `audit: true` explicitly, NOT the default (which follows logging.auditLog). Auditing is the
-		// replication change feed (databases.ts: "auditing must be enabled for replication"), and
-		// replay records MUST replicate so a token spent on one node cannot be re-spent on another
-		// inside its window. Without this, an operator with logging.auditLog:false would silently lose
-		// cross-node replay protection. Its sibling hdb_oidc_trust is audited for the same reason.
-		audit: true,
-		attributes: [
-			{ name: 'id', isPrimaryKey: true },
-			{ name: 'policy_id' },
-			{ name: 'used_at' },
-			{ name: 'expiresAt', expiresAt: true, indexed: true },
-		],
-	});
+	tokenUseTable ??= declareTokenUseTable();
 	return tokenUseTable;
 }
 
@@ -216,12 +190,10 @@ async function recordTokenUse(fingerprint: string, claims: TokenClaims, policyId
 	const useTable = getTokenUseTable();
 	if (await useTable.get(fingerprint)) rejectToken(`token ${fingerprint.slice(0, 12)} has already been exchanged`);
 
-	await useTable.put({
-		id: fingerprint,
-		policy_id: policyId,
-		used_at: Date.now(),
-		expiresAt: (claims.exp as number) * 1000 + REPLAY_RECORD_PADDING_MS,
-	});
+	await useTable.put(
+		{ id: fingerprint, policy_id: policyId, used_at: Date.now() },
+		{ expiresAt: (claims.exp as number) * 1000 + REPLAY_RECORD_PADDING_MS }
+	);
 }
 
 /**

package/security/authn/oidc/tokenUseTable.ts

@@ -0,0 +1,27 @@
+/**
+ * Every node must declare system.hdb_oidc_token_use in this shape whether or not it ever performs an
+ * exchange: passive cluster members receive every replicated replay row, and only an `expiration` stored
+ * in the node's own catalog arms the cleanup scan that removes them. See dataLayer/DESIGN.md, "System
+ * table bootstrap".
+ */
+
+import { table, type Table } from '../../../resources/databases.ts';
+import { SYSTEM_SCHEMA_NAME, SYSTEM_TABLE_NAMES } from '../../../utility/hdbTerms.ts';
+
+export const TOKEN_USE_TABLE = SYSTEM_TABLE_NAMES.OIDC_TOKEN_USE_TABLE_NAME;
+
+/** Bounds only a row written without an expiry of its own; each replay record carries its token's. */
+const FALLBACK_EXPIRATION_SECONDS = 86_400;
+
+export function declareTokenUseTable(): Table {
+	return table<Table>({
+		table: TOKEN_USE_TABLE,
+		database: SYSTEM_SCHEMA_NAME,
+		// Explicit rather than the logging.auditLog default: auditing is the replication change feed, and a
+		// token spent on one node must be refused on the others.
+		audit: true,
+		schemaDefined: true,
+		expiration: FALLBACK_EXPIRATION_SECONDS,
+		attributes: [{ name: 'id', isPrimaryKey: true }, { name: 'policy_id' }, { name: 'used_at' }],
+	});
+}

package/security/certificateVerification/certificateVerificationSource.ts

@@ -69,15 +69,14 @@ export class CertificateVerificationSource extends Resource {
 			throw new Error(`Unsupported verification method: ${method} for ID: ${id}`);
 		}
 
-		// Handle result consistently
-		const expiresAt = Date.now() + methodConfig.cacheTtl;
+		// without a cacheTtl, the table's expiration applies rather than none
+		if (Number.isFinite(methodConfig.cacheTtl)) context.expiresAt = Date.now() + methodConfig.cacheTtl;
 
 		return {
 			certificate_id: id,
 			status: result.status,
 			reason: result.reason,
 			checked_at: Date.now(),
-			expiresAt,
 			method,
 		};
 	}