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

package/dist/resources/models/decisionStore.js

@@ -0,0 +1,350 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionStore = exports.DecisionPersistenceError = exports.OutcomeReportError = exports.DecisionNotFoundError = exports.OUTCOME_ATTRIBUTES = exports.DECISION_ATTRIBUTES = exports.DECISION_RETENTION_MS = exports.OUTCOMES_TABLE = exports.DECISIONS_TABLE = void 0;
+exports.getDecisionTables = getDecisionTables;
+exports.resetDecisionTables = resetDecisionTables;
+exports.declareDecisionTablesAtBoot = declareDecisionTablesAtBoot;
+exports.getDecisionStore = getDecisionStore;
+exports.newDecisionId = newDecisionId;
+exports.setModelsConfigHash = setModelsConfigHash;
+exports.getModelsConfigHash = getModelsConfigHash;
+const node_crypto_1 = require("node:crypto");
+const databases_ts_1 = require("../databases.js");
+const transaction_ts_1 = require("../transaction.js");
+const hdbError_ts_1 = require("../../utility/errors/hdbError.js");
+const harper_logger_ts_1 = __importDefault(require("../../utility/logging/harper_logger.js"));
+const decision_ts_1 = require("./decision.js");
+const log = harper_logger_ts_1.default.forComponent('models').conditional;
+exports.DECISIONS_TABLE = 'hdb_model_decisions';
+exports.OUTCOMES_TABLE = 'hdb_model_outcomes';
+/** Facts copy the decision's instant, so a report never extends a decision's life. */
+exports.DECISION_RETENTION_MS = 365 * 24 * 60 * 60 * 1000;
+/**
+ * The catalog stub (`systemSchema.json` and the upgrade directive) declares only the primary key;
+ * these declarations add the attributes and the indexed `expiresAt` TTL. Writes go through the
+ * Resource API, which maintains the index, so `indexed` holds here, unlike in `hdb_model_calls`.
+ */
+exports.DECISION_ATTRIBUTES = [
+    { name: 'id', isPrimaryKey: true },
+    { name: 'callId', type: 'number' },
+    { name: 'at', type: 'number' },
+    { name: 'expiresAt', expiresAt: true, indexed: true },
+    { name: 'tenant', type: 'string' },
+    { name: 'app', type: 'string' },
+    { name: 'backend', type: 'string' },
+    { name: 'model', type: 'string' },
+    { name: 'signature', type: 'string' },
+    { name: 'configHash', type: 'string' },
+    { name: 'instructionsHash', type: 'string' },
+    { name: 'schema' },
+    { name: 'schemaHash', type: 'string' },
+    { name: 'value' },
+    { name: 'probability', type: 'number' },
+    { name: 'distribution' },
+    { name: 'fields' },
+    { name: 'noMatch', type: 'number' },
+    { name: 'calibrated', type: 'boolean' },
+];
+exports.OUTCOME_ATTRIBUTES = [
+    { name: 'id', isPrimaryKey: true },
+    { name: 'decisionId', type: 'string' },
+    { name: 'fact', type: 'string' },
+    { name: 'field', type: 'string' },
+    { name: 'state' },
+    { name: 'at', type: 'number' },
+    { name: 'expiresAt', expiresAt: true, indexed: true },
+];
+let tables;
+/**
+ * Declares both tables and memoizes the handles. A read-only node cannot write the catalog, so it
+ * takes whatever the catalog already holds and declares nothing; a table not there yet reads as empty.
+ */
+function getDecisionTables(readOnly = (0, databases_ts_1.isReadOnlyMode)()) {
+    if (tables)
+        return tables;
+    const resolve = (name, attributes) => {
+        const handle = readOnly
+            ? (0, databases_ts_1.getDatabases)().system?.[name]
+            : (0, databases_ts_1.table)({
+                table: name,
+                database: 'system',
+                // Declared positively, as the scheduler does: a scoped `replication.databases` must not
+                // exclude these, or an outcome recorded on one node never reaches the others.
+                replicate: true,
+                // auditing is the replication feed; must match systemSchema.json
+                audit: true,
+                attributes,
+            });
+        if (handle)
+            handle.loadAsInstance = false;
+        return handle;
+    };
+    const resolved = {
+        decisions: resolve(exports.DECISIONS_TABLE, exports.DECISION_ATTRIBUTES),
+        outcomes: resolve(exports.OUTCOMES_TABLE, exports.OUTCOME_ATTRIBUTES),
+    };
+    if (resolved.decisions && resolved.outcomes)
+        tables = resolved;
+    return resolved;
+}
+function resetDecisionTables() {
+    tables = undefined;
+}
+/**
+ * Declared at boot on every writable node so the TTL index exists where decisions are never made.
+ * A failure is logged, not thrown: the first `decide` declares again and reports its own error.
+ */
+function declareDecisionTablesAtBoot() {
+    if ((0, databases_ts_1.isReadOnlyMode)())
+        return;
+    try {
+        getDecisionTables();
+    }
+    catch (err) {
+        log.warn?.(`Decision tables could not be declared at boot: ${err?.message ?? err}`);
+    }
+}
+class DecisionNotFoundError extends hdbError_ts_1.ClientError {
+    constructor(id) {
+        super(`No decision '${id}' on this node: it may not exist, may have expired, or may not have replicated here yet`, 404);
+        this.name = 'DecisionNotFoundError';
+    }
+}
+exports.DecisionNotFoundError = DecisionNotFoundError;
+class OutcomeReportError extends hdbError_ts_1.ClientError {
+    constructor(message) {
+        super(`Invalid outcome report: ${message}`, 400);
+        this.name = 'OutcomeReportError';
+    }
+}
+exports.OutcomeReportError = OutcomeReportError;
+class DecisionPersistenceError extends hdbError_ts_1.ServerError {
+    constructor(message, statusCode = 500) {
+        super(message, statusCode);
+        this.name = 'DecisionPersistenceError';
+    }
+}
+exports.DecisionPersistenceError = DecisionPersistenceError;
+/**
+ * Durable decisions and their recorded facts. Every operation runs in a transaction of its own
+ * (`transaction` with a context object that is not the ALS store), so a decision made inside an
+ * application transaction survives that transaction's abort, and the commit is awaited before the
+ * id is returned to the caller.
+ */
+class DecisionStore {
+    #getTables;
+    #isReadOnly;
+    constructor(opts = {}) {
+        this.#getTables = opts.getTables ?? getDecisionTables;
+        this.#isReadOnly = opts.isReadOnly ?? databases_ts_1.isReadOnlyMode;
+    }
+    assertWritable(what) {
+        if (this.#isReadOnly())
+            throw new DecisionPersistenceError(`${what} cannot be recorded on a read-only node`, 503);
+    }
+    async persist(row) {
+        const { decisions } = this.#getTables();
+        await (0, transaction_ts_1.transaction)(freshContext(), () => decisions.put(row));
+    }
+    async get(id, tenant) {
+        return storageFaultsAs('Decision could not be read', () => (0, transaction_ts_1.transaction)(freshContext(), async () => {
+            const found = await this.#read(id, tenant);
+            return found && { ...found.row, outcome: assembleOutcome(found.row.schema, found.facts) };
+        }));
+    }
+    async recordOutcome(id, report, tenant) {
+        this.assertWritable('Outcomes');
+        return storageFaultsAs('Outcome could not be recorded', () => (0, transaction_ts_1.transaction)(freshContext(), async () => {
+            const { outcomes } = this.#getTables();
+            const found = await this.#read(id, tenant);
+            if (!found)
+                throw new DecisionNotFoundError(id);
+            const { row, facts } = found;
+            const at = Date.now();
+            for (const reported of validateReport(row.schema, report)) {
+                const index = factIndex(row.schema, reported.fact, reported.field);
+                const existing = facts[index];
+                if (existing && (0, decision_ts_1.canonicalJson)(existing.state) === (0, decision_ts_1.canonicalJson)(reported.state))
+                    continue;
+                const written = {
+                    id: factKey(id, reported.fact, reported.field),
+                    decisionId: id,
+                    fact: reported.fact,
+                    field: reported.field,
+                    state: reported.state,
+                    at,
+                    expiresAt: row.expiresAt,
+                };
+                await outcomes.put(written);
+                facts[index] = written;
+            }
+            return { ...row, outcome: assembleOutcome(row.schema, facts) };
+        }));
+    }
+    async #read(id, tenant) {
+        const { decisions, outcomes } = this.#getTables();
+        if (!decisions || !outcomes)
+            return undefined;
+        const row = await decisions.get(id);
+        if (!row || !visibleTo(row, tenant))
+            return undefined;
+        const facts = await Promise.all(factKeys(row.id, row.schema).map((key) => outcomes.get(key)));
+        return { row, facts };
+    }
+}
+exports.DecisionStore = DecisionStore;
+let store;
+function getDecisionStore() {
+    if (!store)
+        store = new DecisionStore();
+    return store;
+}
+function newDecisionId() {
+    return (0, node_crypto_1.randomUUID)();
+}
+/** A context of its own, so the transaction is separate, carrying the caller's user for the audit entry. */
+function freshContext() {
+    const user = transaction_ts_1.contextStorage.getStore()?.user;
+    return (user ? { user } : {});
+}
+function visibleTo(row, tenant) {
+    return tenant == null || row.tenant == null || row.tenant === tenant;
+}
+function factKey(id, fact, field) {
+    return field == null ? `${id}/${fact}` : `${id}/${fact}/${field}`;
+}
+/** Truth then action, per property in schema order for object schemas; `factIndex` follows the same order. */
+function factKeys(id, schema) {
+    if (!(0, decision_ts_1.isObjectSchema)(schema))
+        return [factKey(id, 'truth'), factKey(id, 'action')];
+    return Object.keys(schema.properties).flatMap((field) => [factKey(id, 'truth', field), factKey(id, 'action', field)]);
+}
+function factIndex(schema, fact, field) {
+    const offset = fact === 'truth' ? 0 : 1;
+    if (!(0, decision_ts_1.isObjectSchema)(schema))
+        return offset;
+    return Object.keys(schema.properties).indexOf(field) * 2 + offset;
+}
+function assembleOutcome(schema, facts) {
+    if (!(0, decision_ts_1.isObjectSchema)(schema))
+        return leafOutcome(facts);
+    const fields = {};
+    const names = Object.keys(schema.properties);
+    for (let i = 0; i < names.length; i++)
+        fields[names[i]] = leafOutcome(facts.slice(i * 2, i * 2 + 2));
+    return { fields };
+}
+function leafOutcome(facts) {
+    const outcome = {};
+    for (const fact of facts) {
+        if (!fact)
+            continue;
+        if (fact.fact === 'truth') {
+            outcome.truth = fact.state;
+            outcome.truthAt = fact.at;
+        }
+        else {
+            outcome.action = fact.state;
+            outcome.actionAt = fact.at;
+        }
+    }
+    return outcome;
+}
+const TRUTH_KINDS = ['value', 'noMatch', 'unknown'];
+const ACTION_KINDS = ['value', 'noMatch', 'abstained', 'unknown'];
+/** Checks a report against the stored schema. Messages name fields, never reported values. */
+function validateReport(schema, report) {
+    if (!report || typeof report !== 'object' || Array.isArray(report))
+        throw new OutcomeReportError('the report must be an object');
+    const facts = [];
+    if ((0, decision_ts_1.isObjectSchema)(schema)) {
+        if ('truth' in report || 'action' in report)
+            throw new OutcomeReportError('an object schema takes { fields: { <name>: { truth?, action? } } }');
+        const fields = report.fields;
+        if (!fields || typeof fields !== 'object' || Array.isArray(fields))
+            throw new OutcomeReportError('an object schema needs a fields map');
+        for (const [name, leafReport] of Object.entries(fields)) {
+            if (!Object.hasOwn(schema.properties, name))
+                throw new OutcomeReportError(`unknown field '${name}'`);
+            facts.push(...leafFacts(schema.properties[name], leafReport, name));
+        }
+    }
+    else {
+        if ('fields' in report)
+            throw new OutcomeReportError('a leaf schema takes { truth?, action? }');
+        facts.push(...leafFacts(schema, report, undefined));
+    }
+    if (facts.length === 0)
+        throw new OutcomeReportError('the report carries no fact');
+    return facts;
+}
+function leafFacts(leaf, report, field) {
+    const label = field === undefined ? 'the report' : `field '${field}'`;
+    if (!report || typeof report !== 'object' || Array.isArray(report))
+        throw new OutcomeReportError(`${label} must be an object`);
+    const facts = [];
+    if (report.truth !== undefined)
+        facts.push({ fact: 'truth', field, state: checkState(leaf, report.truth, TRUTH_KINDS, `${label}: truth`) });
+    if (report.action !== undefined)
+        facts.push({ fact: 'action', field, state: checkState(leaf, report.action, ACTION_KINDS, `${label}: action`) });
+    return facts;
+}
+function checkState(leaf, state, kinds, label) {
+    if (!state || typeof state !== 'object' || Array.isArray(state))
+        throw new OutcomeReportError(`${label} must be a tagged state`);
+    const { kind, value } = state;
+    if (typeof kind !== 'string' || !kinds.includes(kind))
+        throw new OutcomeReportError(`${label} has an unknown kind; expected one of ${kinds.join(', ')}`);
+    if (kind === 'value') {
+        if (!(0, decision_ts_1.isAllowedValue)(leaf, value))
+            throw new OutcomeReportError(`${label} is not an allowed value`);
+        return { kind, value };
+    }
+    return { kind };
+}
+let modelsConfigHash;
+/**
+ * Identity of the model configuration actually installed, recorded on each decision so a reload
+ * that changes the model behind an unchanged logical name still separates the decisions it produced.
+ * Credential-looking keys are dropped before hashing.
+ */
+function setModelsConfigHash(installed) {
+    modelsConfigHash = installed
+        ? (0, node_crypto_1.createHash)('sha256')
+            .update((0, decision_ts_1.canonicalJson)(withoutCredentials(installed)))
+            .digest('hex')
+        : undefined;
+}
+function getModelsConfigHash() {
+    return modelsConfigHash;
+}
+const CREDENTIAL_KEY = /^(apiKey|accessKeyId|authorization|.*secret.*|.*password.*|.*credential.*|.*key|.*token)$/i;
+function withoutCredentials(value) {
+    if (Array.isArray(value))
+        return value.map(withoutCredentials);
+    if (!value || typeof value !== 'object')
+        return value;
+    const kept = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (!CREDENTIAL_KEY.test(key))
+            kept[key] = withoutCredentials(entry);
+    }
+    return kept;
+}
+/** A fault from the storage layer can name a data path; only its class and a fixed message may reach a response body. */
+async function storageFaultsAs(message, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (err instanceof hdbError_ts_1.ClientError || err instanceof DecisionPersistenceError)
+            throw err;
+        const error = new DecisionPersistenceError(message);
+        error.cause = err;
+        throw error;
+    }
+}
+//# sourceMappingURL=decisionStore.js.map

package/dist/resources/models/decisionStore.js.map

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

package/dist/resources/models/embedHook.d.ts

@@ -1,9 +1,3 @@
-/**
- * `@embed` directive write-time hook. `createDefaultEmbedder` builds the embedder
- * a table registers for an `@embed` attribute; `buildEmbedBefore` produces the
- * pre-commit callback that runs registered embedders and writes their vectors onto
- * the record before it commits.
- */
 export type EmbedConfig = {
     source: string;
     model: string;
@@ -12,13 +6,77 @@ export type EmbedAttribute = {
     name: string;
     embed: EmbedConfig;
 };
-export type Embedder = (record: any) => Promise<number[] | Float32Array | null | undefined>;
+/** The signal aborts when a sibling hook of the same write fails; a hook that honors it lets the write fail promptly. */
+export type WriteHookContext = {
+    signal: AbortSignal;
+};
+export type Embedder = (record: any, hook?: WriteHookContext) => Promise<number[] | Float32Array | null | undefined>;
+/** A pre-commit callback of one write; `signal` is the write's, aborted when another hook of the write fails. */
+export type WriteHook = (signal?: AbortSignal) => Promise<void>;
 type EmbedFn = (input: string | string[], opts: {
     model?: string;
     inputType?: 'document' | 'query';
+    signal?: AbortSignal;
 }) => Promise<Float32Array[]>;
 /** Test seam: override the embed function. Pass `undefined` to reset to `Models.embed`. */
 export declare function __setEmbedFnForTest(fn: EmbedFn | undefined): void;
+/**
+ * Whether a write-time model hook runs for this write at all. Skip when the write already
+ * carries the derived attributes: a cluster-replication receiver (isNotification), REST
+ * x-replicate-from:none, or audit-log replay. Proactive source-subscribe pushes also set
+ * isNotification and so skip. One predicate for `@embed` and `@decide` so their trigger rules
+ * cannot drift.
+ */
+export declare function writeHookApplies(record: any, context: any, options: any): boolean;
+/**
+ * How a hook treats one source field of the write payload: absent leaves the derived
+ * attributes alone (a PATCH that omits the source), null clears them, a CRDT op payload
+ * (`{__op__, value}`) is not a meaningful input and is skipped, and a value is derived from.
+ */
+export type SourceState = 'absent' | 'null' | 'op' | 'value';
+export declare function sourceState(record: any, sourceKey: string | undefined): SourceState;
+/**
+ * Run the jobs of one write. The first failure aborts the others, and every job settles before
+ * that failure is reported: a rejected write neither waits on a sibling that honors the signal
+ * nor keeps being mutated by one that has not finished. A job that ignores the signal is
+ * awaited regardless, so the model calls behind the built-in hooks forward it.
+ */
+export declare function runWriteJobs(jobs: Array<(signal: AbortSignal) => Promise<void>>, signal?: AbortSignal): Promise<void>;
+export declare function combineWriteHooks(a: WriteHook | undefined, b: WriteHook | undefined): WriteHook | undefined;
+/**
+ * Backend errors can carry URLs / key tails; log raw, return a sanitized error to throw. Only
+ * safe identifiers are included (an identifier-shaped error class name, a finite upstream HTTP
+ * status) so the failure is diagnosable without hunting through server logs (#1593).
+ * `upstreamStatus` is the provider's status — NOT ServerError's statusCode, which is Harper's
+ * own response status and would misleadingly read 500 here.
+ */
+export declare function sanitizedHookError(actor: string, product: string, attributeName: string, err: unknown, log?: boolean): Error;
+type DerivedAttribute = {
+    name: string;
+    type?: string;
+    nullable?: boolean;
+    isPrimaryKey?: boolean;
+    computed?: unknown;
+    embed?: {
+        source: string;
+    };
+    decide?: {
+        source: string;
+        confidence?: string;
+        decision?: string;
+        schema?: unknown;
+    };
+};
+/**
+ * Every derived field (an `@embed` target, a `@decide` target or confidence) has exactly one
+ * writer, and no directive derives from another directive's output: the hooks run concurrently
+ * within one write, so the stored pair would otherwise depend on scheduling. A source and a
+ * confidence field must be declared; a decided field and its confidence field are nullable,
+ * neither the primary key nor computed, the decided field's type matches its leaf and the leaf
+ * is a valid decision schema; and none of those fields may be named after an `Object.prototype`
+ * key, because `sourceState` tests presence with `in`. Run on the complete attribute list.
+ */
+export declare function assertDerivedFieldOwnership(attributes: DerivedAttribute[]): void;
 export declare function createDefaultEmbedder(embedConfig: EmbedConfig): Embedder;
 /**
  * Build the pre-commit callback that runs embedders for every `@embed` attribute whose
@@ -29,5 +87,5 @@ export declare function createDefaultEmbedder(embedConfig: EmbedConfig): Embedde
  * Source-field semantics: embed only when the source field is in the payload. A PATCH that
  * omits it leaves the existing vector untouched; an explicit `source: null` clears the vector.
  */
-export declare function buildEmbedBefore(record: any, context: any, options: any, embedAttributes: EmbedAttribute[] | undefined, userEmbedders: Record<string, Embedder>): (() => Promise<void>) | undefined;
+export declare function buildEmbedBefore(record: any, context: any, options: any, embedAttributes: EmbedAttribute[] | undefined, userEmbedders: Record<string, Embedder>): WriteHook | undefined;
 export {};