@intutic/shared-types 2.9.1 → 3.0.1

package/dist/decideRecord.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Decide rules in the policy snapshot: the `@format` record, the `@decide`
+ * record, and the id and reason of a rule's fallback line.
+ *
+ * A gate that cannot evaluate a decide rule must refuse what the rule covers,
+ * never skip it. So the snapshot writer emits, for each rule a gate is to
+ * enforce, two lines inside the digest:
+ *
+ * - an `@decide` record of five tab-separated columns (the tag, the fallback
+ *   line's id or `-`, the stamped rollout, the comma-joined tools, and base64
+ *   of the record's canonical JSON). Every 2.x rule parser needs six columns,
+ *   so it skips the record;
+ * - a fallback line, an ordinary `block` rule on the rule's tools whose id
+ *   starts `decide-fallback:`, which every gate since 2.0 enforces.
+ *
+ * A gate that reads decide rules skips a fallback line only when a record
+ * with that `fallbackId` decodes ({@link decodeDecideRecord}): a damaged
+ * record leaves its fallback line in force, which refuses. The `@format`
+ * record names the snapshot format, 2 once any decide line is written; a
+ * snapshot without one is byte-identical to a format 1 snapshot.
+ *
+ * Self-contained (no imports, no module state) so `@intutic/gate` can carry
+ * a byte-identical copy (`packages/gate-js/src/decideRecord.ts`) and the
+ * JavaScript hook gates can embed the decoder ({@link DECIDE_RECORD_JS_SOURCE}).
+ * The rule itself is checked by the caller's {@link DecideRuleCheck}, which
+ * runs `validateDecideRule` and `decideRuleHash` from `./decide.ts`. The
+ * Python gate's port is `intutic_clawde/gate/decide_record.py`; both run the
+ * `record` group of `fixtures/decide-vectors.json`.
+ *
+ * @module
+ */
+import type { DecideRule } from './decide.js';
+/** First column of the snapshot format record: `@format<TAB><integer>`. */
+export declare const SNAPSHOT_FORMAT_RECORD_TAG = "@format";
+/**
+ * The newest snapshot format a gate of this generation reads: 3, which adds
+ * the `@rule` records of the loops, graphs and gates release (`./gateRuleRecord.ts`). A gate reading a
+ * newer one reports `snapshot_format_newer` and enforces the fallback lines
+ * of the records it does not know.
+ */
+export declare const SNAPSHOT_FORMAT = 3;
+/**
+ * The format a snapshot carrying decide lines and no `@rule` record is
+ * written in, so such a snapshot stays byte-identical to one written before rule records existed. One
+ * with any `@rule` record is format 3 (`RULE_SNAPSHOT_FORMAT`).
+ */
+export declare const DECIDE_SNAPSHOT_FORMAT = 2;
+/** First column of a decide rule's record. */
+export declare const DECIDE_RECORD_TAG = "@decide";
+/** The id prefix of a decide rule's fallback line. */
+export declare const DECIDE_FALLBACK_PREFIX = "decide-fallback:";
+/** A record carries the first this many bytes of its SOP's body. */
+export declare const DECIDE_RULE_TEXT_MAX_BYTES = 4096;
+/** The longest SOP title a record carries, in code points. */
+export declare const DECIDE_SOP_TITLE_MAX_CHARS = 80;
+/** Why a rule's stamped rollout is what it is. Only `rule` can stamp `enforce`. */
+export type DecideStamp = 'rule' | 'local-disable' | 'server-shadow' | 'silent-log' | 'no-pins';
+/** A calibration a rule may enforce under: the model digest it was evaluated on, and what the evaluation fitted. */
+export interface DecidePin {
+    modelDigest: string;
+    temperature?: Record<string, number>;
+    band?: {
+        yes_at: number;
+        no_below: number;
+    };
+    combiner?: {
+        bias: number;
+        weights: Record<string, number>;
+    };
+    evalRunId: string;
+    source: 'local' | 'server';
+}
+/** One `@decide` record's payload. */
+export interface DecideRecord {
+    v: 1;
+    /** `<sopId>#<rule id>`. */
+    ref: string;
+    ruleHash: string;
+    /** The paired fallback line's id; null when the rule is stamped shadow and has none. */
+    fallbackId: string | null;
+    rollout: 'shadow' | 'enforce';
+    stampedBy: DecideStamp;
+    /** The rule as its `decide:` line carries it. */
+    ir: DecideRule;
+    sopTitle: string;
+    ruleText: string;
+    pins: DecidePin[];
+}
+/**
+ * Checks a record's rule: the rule's `ruleHash` when it is a valid decide
+ * rule, null when it is not. Callers pass `validateDecideRule` then
+ * `decideRuleHash`, with their own SHA-256.
+ */
+export type DecideRuleCheck = (ir: unknown) => string | null;
+/** `@format<TAB><format>`: 2 ({@link DECIDE_SNAPSHOT_FORMAT}) unless the writer passes 3 for a snapshot with `@rule` records. */
+export declare function encodeSnapshotFormatRecord(format?: number): string;
+/** The format a `@format` line names: a positive integer, or null for any other line or a damaged one. */
+export declare function decodeSnapshotFormatRecord(line: string): number | null;
+/** `ruleRef`: `<sopId>#<rule id>`. */
+export declare function decideRuleRef(sopId: string, ruleId: string): string;
+/** `fallbackId`: `decide-fallback:<rule id>@<first 12 hex of sha256(sopId)>`. `sha256Hex` hashes a string's UTF-8 bytes. */
+export declare function decideFallbackId(ruleId: string, sopId: string, sha256Hex: (text: string) => string): string;
+/** What an older gate says when a fallback line refuses. The writer scrubs and bounds it like any reason. */
+export declare function decideFallbackReason(ruleId: string, sopTitle: string): string;
+/** A SOP body as a record carries it: its first {@link DECIDE_RULE_TEXT_MAX_BYTES} bytes of UTF-8, never splitting a character. */
+export declare function decideRuleText(body: string): string;
+/** A pin as a record carries it, or null. Unknown fields refuse: a pin a reader cannot apply must not be read as a weaker one. */
+export declare function parseDecidePin(value: unknown): DecidePin | null;
+/** The record as one `.rules` line. */
+export declare function encodeDecideRecord(record: DecideRecord): string;
+/**
+ * Reads an `@decide` line back. Null, and so the fallback line stays in
+ * force, for any other line or when: it does not have five columns; the
+ * base64 or JSON is damaged; the payload has a field this reader does not
+ * know or lacks one; `check` finds the rule invalid or its hash differs from
+ * `ruleHash`; the stamp is inconsistent (only a rule stamped `enforce` by
+ * `rule` has a fallback line, and it is named for the rule); or columns 2 to
+ * 4 disagree with the payload.
+ */
+export declare function decodeDecideRecord(line: string, check: DecideRuleCheck): DecideRecord | null;
+/**
+ * The decoders above as JavaScript source, for the hook gates to embed. The
+ * gate defines `check` with the embedded `./decide.ts` source and its own
+ * SHA-256. A CommonJS build names an exported constant `exports.X` inside a
+ * function; the source defines each as a plain `X`, so that prefix is dropped.
+ */
+export declare const DECIDE_RECORD_JS_SOURCE: string;
+//# sourceMappingURL=decideRecord.d.ts.map

package/dist/decideRecord.d.ts.map

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

package/dist/decideRecord.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Decide rules in the policy snapshot: the `@format` record, the `@decide`
+ * record, and the id and reason of a rule's fallback line.
+ *
+ * A gate that cannot evaluate a decide rule must refuse what the rule covers,
+ * never skip it. So the snapshot writer emits, for each rule a gate is to
+ * enforce, two lines inside the digest:
+ *
+ * - an `@decide` record of five tab-separated columns (the tag, the fallback
+ *   line's id or `-`, the stamped rollout, the comma-joined tools, and base64
+ *   of the record's canonical JSON). Every 2.x rule parser needs six columns,
+ *   so it skips the record;
+ * - a fallback line, an ordinary `block` rule on the rule's tools whose id
+ *   starts `decide-fallback:`, which every gate since 2.0 enforces.
+ *
+ * A gate that reads decide rules skips a fallback line only when a record
+ * with that `fallbackId` decodes ({@link decodeDecideRecord}): a damaged
+ * record leaves its fallback line in force, which refuses. The `@format`
+ * record names the snapshot format, 2 once any decide line is written; a
+ * snapshot without one is byte-identical to a format 1 snapshot.
+ *
+ * Self-contained (no imports, no module state) so `@intutic/gate` can carry
+ * a byte-identical copy (`packages/gate-js/src/decideRecord.ts`) and the
+ * JavaScript hook gates can embed the decoder ({@link DECIDE_RECORD_JS_SOURCE}).
+ * The rule itself is checked by the caller's {@link DecideRuleCheck}, which
+ * runs `validateDecideRule` and `decideRuleHash` from `./decide.ts`. The
+ * Python gate's port is `intutic_clawde/gate/decide_record.py`; both run the
+ * `record` group of `fixtures/decide-vectors.json`.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECIDE_RECORD_JS_SOURCE = exports.DECIDE_SOP_TITLE_MAX_CHARS = exports.DECIDE_RULE_TEXT_MAX_BYTES = exports.DECIDE_FALLBACK_PREFIX = exports.DECIDE_RECORD_TAG = exports.DECIDE_SNAPSHOT_FORMAT = exports.SNAPSHOT_FORMAT = exports.SNAPSHOT_FORMAT_RECORD_TAG = void 0;
+exports.encodeSnapshotFormatRecord = encodeSnapshotFormatRecord;
+exports.decodeSnapshotFormatRecord = decodeSnapshotFormatRecord;
+exports.decideRuleRef = decideRuleRef;
+exports.decideFallbackId = decideFallbackId;
+exports.decideFallbackReason = decideFallbackReason;
+exports.decideRuleText = decideRuleText;
+exports.parseDecidePin = parseDecidePin;
+exports.encodeDecideRecord = encodeDecideRecord;
+exports.decodeDecideRecord = decodeDecideRecord;
+/** First column of the snapshot format record: `@format<TAB><integer>`. */
+exports.SNAPSHOT_FORMAT_RECORD_TAG = '@format';
+/**
+ * The newest snapshot format a gate of this generation reads: 3, which adds
+ * the `@rule` records of the loops, graphs and gates release (`./gateRuleRecord.ts`). A gate reading a
+ * newer one reports `snapshot_format_newer` and enforces the fallback lines
+ * of the records it does not know.
+ */
+exports.SNAPSHOT_FORMAT = 3;
+/**
+ * The format a snapshot carrying decide lines and no `@rule` record is
+ * written in, so such a snapshot stays byte-identical to one written before rule records existed. One
+ * with any `@rule` record is format 3 (`RULE_SNAPSHOT_FORMAT`).
+ */
+exports.DECIDE_SNAPSHOT_FORMAT = 2;
+/** First column of a decide rule's record. */
+exports.DECIDE_RECORD_TAG = '@decide';
+/** The id prefix of a decide rule's fallback line. */
+exports.DECIDE_FALLBACK_PREFIX = 'decide-fallback:';
+/** A record carries the first this many bytes of its SOP's body. */
+exports.DECIDE_RULE_TEXT_MAX_BYTES = 4096;
+/** The longest SOP title a record carries, in code points. */
+exports.DECIDE_SOP_TITLE_MAX_CHARS = 80;
+const DECIDE_STAMPS = ['rule', 'local-disable', 'server-shadow', 'silent-log', 'no-pins'];
+const DECIDE_RECORD_FIELDS = ['fallbackId', 'ir', 'pins', 'ref', 'rollout', 'ruleHash', 'ruleText', 'sopTitle', 'stampedBy', 'v'];
+const DECIDE_PIN_FIELDS = ['band', 'combiner', 'evalRunId', 'modelDigest', 'source', 'temperature'];
+/** `@format<TAB><format>`: 2 ({@link DECIDE_SNAPSHOT_FORMAT}) unless the writer passes 3 for a snapshot with `@rule` records. */
+function encodeSnapshotFormatRecord(format = exports.DECIDE_SNAPSHOT_FORMAT) {
+    return `${exports.SNAPSHOT_FORMAT_RECORD_TAG}\t${format}`;
+}
+/** The format a `@format` line names: a positive integer, or null for any other line or a damaged one. */
+function decodeSnapshotFormatRecord(line) {
+    const f = line.split('\t');
+    if (f.length !== 2 || f[0] !== exports.SNAPSHOT_FORMAT_RECORD_TAG || !/^[1-9][0-9]{0,5}$/.test(f[1]))
+        return null;
+    return Number(f[1]);
+}
+/** `ruleRef`: `<sopId>#<rule id>`. */
+function decideRuleRef(sopId, ruleId) {
+    return `${sopId}#${ruleId}`;
+}
+/** `fallbackId`: `decide-fallback:<rule id>@<first 12 hex of sha256(sopId)>`. `sha256Hex` hashes a string's UTF-8 bytes. */
+function decideFallbackId(ruleId, sopId, sha256Hex) {
+    return `${exports.DECIDE_FALLBACK_PREFIX}${ruleId}@${sha256Hex(sopId).slice(0, 12)}`;
+}
+/** What an older gate says when a fallback line refuses. The writer scrubs and bounds it like any reason. */
+function decideFallbackReason(ruleId, sopTitle) {
+    return `Decide rule ${ruleId} (${sopTitle}): upgrade to Intutic 3.0 to evaluate this rule`;
+}
+/** A SOP body as a record carries it: its first {@link DECIDE_RULE_TEXT_MAX_BYTES} bytes of UTF-8, never splitting a character. */
+function decideRuleText(body) {
+    let bytes = 0;
+    let end = 0;
+    for (const ch of body) {
+        const cp = ch.codePointAt(0);
+        const n = cp < 0x80 ? 1 : cp < 0x800 ? 2 : cp < 0x10000 ? 3 : 4;
+        if (bytes + n > exports.DECIDE_RULE_TEXT_MAX_BYTES)
+            break;
+        bytes += n;
+        end += ch.length;
+    }
+    return body.slice(0, end);
+}
+function decideIsObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function decideIsNumber(v) {
+    return typeof v === 'number' && isFinite(v);
+}
+/** Every own key is one of `allowed`. */
+function decideOnlyFields(obj, allowed) {
+    return Object.keys(obj).every((k) => allowed.indexOf(k) !== -1);
+}
+function decideNumberMap(v) {
+    return decideIsObject(v) && Object.keys(v).every((k) => decideIsNumber(v[k]));
+}
+/** JSON with keys sorted at every level and no whitespace, so a record is byte-stable. */
+function decideCanonicalRecordJson(v) {
+    if (Array.isArray(v))
+        return '[' + v.map(decideCanonicalRecordJson).join(',') + ']';
+    if (decideIsObject(v)) {
+        return '{' + Object.keys(v).sort().map((k) => JSON.stringify(k) + ':' + decideCanonicalRecordJson(v[k])).join(',') + '}';
+    }
+    return JSON.stringify(v);
+}
+function decideToBase64(text) {
+    let binary = '';
+    for (const byte of new TextEncoder().encode(text))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+/** Standard base64 back to UTF-8 text. Throws on anything but the canonical encoding of valid UTF-8. */
+function decideFromBase64(b64) {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)));
+    if (decideToBase64(text) !== b64)
+        throw new Error('not canonical base64');
+    return text;
+}
+/** A pin as a record carries it, or null. Unknown fields refuse: a pin a reader cannot apply must not be read as a weaker one. */
+function parseDecidePin(value) {
+    if (!decideIsObject(value) || !decideOnlyFields(value, DECIDE_PIN_FIELDS))
+        return null;
+    const { modelDigest, evalRunId, source, temperature, band, combiner } = value;
+    if (typeof modelDigest !== 'string' || modelDigest === '' || typeof evalRunId !== 'string' || evalRunId === '')
+        return null;
+    if (source !== 'local' && source !== 'server')
+        return null;
+    if (temperature !== undefined && !decideNumberMap(temperature))
+        return null;
+    if (band !== undefined) {
+        if (!decideIsObject(band) || !decideOnlyFields(band, ['yes_at', 'no_below']))
+            return null;
+        const { yes_at, no_below } = band;
+        if (!decideIsNumber(yes_at) || !decideIsNumber(no_below) || !(yes_at > 0.5 && yes_at < 1 && no_below > 0 && no_below < yes_at))
+            return null;
+    }
+    if (combiner !== undefined) {
+        if (!decideIsObject(combiner) || !decideOnlyFields(combiner, ['bias', 'weights']))
+            return null;
+        if (!decideIsNumber(combiner.bias) || !decideNumberMap(combiner.weights))
+            return null;
+    }
+    return value;
+}
+/** The record's tools column: the rule's tools, distinct and sorted, joined by commas. */
+function decideToolsColumn(ir) {
+    return (ir.tools ?? []).filter((t, i, all) => all.indexOf(t) === i).sort().join(',');
+}
+/** The record as one `.rules` line. */
+function encodeDecideRecord(record) {
+    return [
+        exports.DECIDE_RECORD_TAG,
+        record.fallbackId ?? '-',
+        record.rollout,
+        decideToolsColumn(record.ir),
+        decideToBase64(decideCanonicalRecordJson(record)),
+    ].join('\t');
+}
+/**
+ * Reads an `@decide` line back. Null, and so the fallback line stays in
+ * force, for any other line or when: it does not have five columns; the
+ * base64 or JSON is damaged; the payload has a field this reader does not
+ * know or lacks one; `check` finds the rule invalid or its hash differs from
+ * `ruleHash`; the stamp is inconsistent (only a rule stamped `enforce` by
+ * `rule` has a fallback line, and it is named for the rule); or columns 2 to
+ * 4 disagree with the payload.
+ */
+function decodeDecideRecord(line, check) {
+    const f = line.split('\t');
+    if (f.length !== 5 || f[0] !== exports.DECIDE_RECORD_TAG || !f[4])
+        return null;
+    let r;
+    try {
+        r = JSON.parse(decideFromBase64(f[4]));
+    }
+    catch {
+        return null;
+    }
+    if (!decideIsObject(r) || !decideOnlyFields(r, DECIDE_RECORD_FIELDS))
+        return null;
+    if (DECIDE_RECORD_FIELDS.some((k) => !Object.prototype.hasOwnProperty.call(r, k)))
+        return null;
+    const ir = r.ir;
+    if (r.v !== 1 || !decideIsObject(ir) || typeof ir.id !== 'string')
+        return null;
+    if (typeof r.ruleHash !== 'string' || !/^[0-9a-f]{64}$/.test(r.ruleHash) || check(ir) !== r.ruleHash)
+        return null;
+    if (typeof r.ref !== 'string' || r.ref.length <= ir.id.length + 1 || r.ref.slice(-(ir.id.length + 1)) !== '#' + ir.id)
+        return null;
+    if (r.rollout !== 'shadow' && r.rollout !== 'enforce')
+        return null;
+    if (typeof r.stampedBy !== 'string' || DECIDE_STAMPS.indexOf(r.stampedBy) === -1)
+        return null;
+    if (r.rollout === 'enforce') {
+        if (r.stampedBy !== 'rule' || typeof r.fallbackId !== 'string')
+            return null;
+        const head = exports.DECIDE_FALLBACK_PREFIX + ir.id + '@';
+        if (r.fallbackId.slice(0, head.length) !== head || !/^[0-9a-f]{12}$/.test(r.fallbackId.slice(head.length)))
+            return null;
+    }
+    else if (r.fallbackId !== null) {
+        return null;
+    }
+    if (typeof r.sopTitle !== 'string' || /[\t\r\n]/.test(r.sopTitle) || Array.from(r.sopTitle).length > exports.DECIDE_SOP_TITLE_MAX_CHARS)
+        return null;
+    if (typeof r.ruleText !== 'string' || new TextEncoder().encode(r.ruleText).length > exports.DECIDE_RULE_TEXT_MAX_BYTES)
+        return null;
+    if (!Array.isArray(r.pins) || r.pins.some((p) => parseDecidePin(p) === null))
+        return null;
+    const record = r;
+    if (f[1] !== (record.fallbackId ?? '-') || f[2] !== record.rollout || f[3] !== decideToolsColumn(record.ir))
+        return null;
+    return record;
+}
+/**
+ * The decoders above as JavaScript source, for the hook gates to embed. The
+ * gate defines `check` with the embedded `./decide.ts` source and its own
+ * SHA-256. A CommonJS build names an exported constant `exports.X` inside a
+ * function; the source defines each as a plain `X`, so that prefix is dropped.
+ */
+exports.DECIDE_RECORD_JS_SOURCE = [
+    `const SNAPSHOT_FORMAT_RECORD_TAG = ${JSON.stringify(exports.SNAPSHOT_FORMAT_RECORD_TAG)};`,
+    `const DECIDE_RECORD_TAG = ${JSON.stringify(exports.DECIDE_RECORD_TAG)};`,
+    `const DECIDE_FALLBACK_PREFIX = ${JSON.stringify(exports.DECIDE_FALLBACK_PREFIX)};`,
+    `const DECIDE_RULE_TEXT_MAX_BYTES = ${exports.DECIDE_RULE_TEXT_MAX_BYTES};`,
+    `const DECIDE_SOP_TITLE_MAX_CHARS = ${exports.DECIDE_SOP_TITLE_MAX_CHARS};`,
+    `const DECIDE_STAMPS = ${JSON.stringify(DECIDE_STAMPS)};`,
+    `const DECIDE_RECORD_FIELDS = ${JSON.stringify(DECIDE_RECORD_FIELDS)};`,
+    `const DECIDE_PIN_FIELDS = ${JSON.stringify(DECIDE_PIN_FIELDS)};`,
+    ...[
+        decodeSnapshotFormatRecord,
+        decideIsObject,
+        decideIsNumber,
+        decideOnlyFields,
+        decideNumberMap,
+        decideToBase64,
+        decideFromBase64,
+        parseDecidePin,
+        decideToolsColumn,
+        decodeDecideRecord,
+    ].map((fn) => fn.toString().replace(/\bexports\./g, '')),
+].join('\n');
+//# sourceMappingURL=decideRecord.js.map

package/dist/decideRecord.js.map

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

package/dist/decideSdk.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `decide(state, questions, opts)` for people building their own agents: ask
+ * a self-hosted model a few narrow questions about a state, and get each
+ * answer's probability, its three-valued reading through a band and, with a
+ * `when`, the outcome a decide rule would reach.
+ *
+ * The questions are written as a decide rule's `questions` and validated
+ * the same way, so wording that asks the model for approval is refused. Every
+ * call goes through the engine client and its host guard: a hosted decision
+ * API is refused before anything is sent, and there is no way to pass an
+ * engine object that skips the guard.
+ *
+ * Errors are {@link DecideEngineError}s and are thrown, so a caller cannot
+ * read an unavailable engine as an answer. The one exception is
+ * `too_large`: a state over the limit is never truncated, every answer is
+ * unknown, and with a `when` the outcome escalates.
+ *
+ * Self-contained but for the decide modules beside it, so `@intutic/gate` and
+ * `@intutic/clawde` carry byte-identical copies; each wraps it in a `decide()`
+ * that reads `~/.intutic/decide/engine.json` and the process environment. The
+ * Python port is `intutic_clawde/gate/decide_sdk.py`. All three run
+ * `fixtures/decide-sdk-vectors.json`.
+ *
+ * @module
+ */
+import { type ChoiceAtom, type DecideBand, type DecideQuestion, type Tri } from './decide.js';
+import { type DecideAdapter, type DecideEngineConfig } from './decideEngine.js';
+/** The budget when neither `budgetMs` nor `INTUTIC_DECIDE_BUDGET_MS` sets one. */
+export declare const DECIDE_SDK_DEFAULT_BUDGET_MS = 7300;
+/** The engine configuration's path under the home directory. */
+export declare const DECIDE_ENGINE_FILE_PATH: readonly [".intutic", "decide", "engine.json"];
+export interface DecideSdkOptions {
+    /** A `when` over the questions. With it, the result carries the rule's outcome. */
+    when?: string;
+    /** The band for every question without its own (default `{yes_at: 0.85, no_below: 0.15}`). */
+    band?: DecideBand;
+    /** What an unknown `when` does (default `ask`). */
+    escalate?: 'ask' | 'review' | 'refuse';
+    /** The engine's configuration. Without it, `engineFile` and `env` give it. */
+    engine?: DecideEngineConfig;
+    /** The parsed `engine.json`, or null when there is none. */
+    engineFile?: unknown;
+    /** The environment, which overrides `engineFile`. */
+    env?: Record<string, string | undefined>;
+    /** Milliseconds for the whole call (default `INTUTIC_DECIDE_BUDGET_MS`, else 7,300). */
+    budgetMs?: number;
+}
+export type DecideSdkAnswer = {
+    type: 'yes_no';
+    p: number | null;
+    value: Tri;
+} | {
+    type: 'choice';
+    perOrder: Array<Record<string, number>> | null;
+    /** Each option's atom `q == o`: the mean over the orders, their spread, and its value. */
+    options: Record<string, ChoiceAtom>;
+    /** The option whose atom is T, or null. At most one can be, because `yes_at` is above 0.5. */
+    choice: string | null;
+};
+export interface DecideSdkResult {
+    answers: Record<string, DecideSdkAnswer>;
+    /** `when`'s value, or null without a `when`. */
+    value: Tri | null;
+    outcome: 'allow' | 'refuse' | 'escalate' | null;
+    code: 'DECIDE_REFUSED' | 'DECIDE_ESCALATED' | null;
+    via: 'ask' | 'review' | null;
+    /** `too_large` when the state was over 16,384 bytes, a tool call's limit, and nothing was asked. */
+    error: 'too_large' | null;
+    model: string | null;
+    modelDigest: string | null;
+    digestStrength: 'strong' | 'weak' | null;
+    adapter: DecideAdapter;
+    latencyMs: number;
+}
+/**
+ * `engine.json`'s parsed content through `read`, or null when the file does
+ * not exist. A file that does not parse leaves the engine not configured.
+ */
+export declare function loadDecideEngineFile(read: (path: string) => string, path: string): unknown;
+/**
+ * Asks `questions` about `state`. Throws a `TypeError` for questions (or a
+ * `when`) a decide rule would refuse, and a {@link DecideEngineError} when
+ * the engine is not configured, its host is refused, or it cannot answer.
+ */
+export declare function decideQuestions(state: string, questions: Record<string, DecideQuestion>, opts?: DecideSdkOptions): Promise<DecideSdkResult>;
+//# sourceMappingURL=decideSdk.d.ts.map

package/dist/decideSdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decideSdk.d.ts","sourceRoot":"","sources":["../src/decideSdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAQL,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,cAAc,EAEnB,KAAK,GAAG,EACT,MAAM,aAAa,CAAA;AACpB,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EAExB,MAAM,mBAAmB,CAAA;AAE1B,kFAAkF;AAClF,eAAO,MAAM,4BAA4B,OAAQ,CAAA;AACjD,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,gDAAiD,CAAA;AAErF,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8FAA8F;IAC9F,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACtC,8EAA8E;IAC9E,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,GAAG,CAAA;CAAE,GAChD;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,CAAA;IAC9C,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACnC,8FAA8F;IAC9F,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB,CAAA;AAEL,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACxC,gDAAgD;IAChD,KAAK,EAAE,GAAG,GAAG,IAAI,CAAA;IACjB,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,IAAI,CAAA;IAC/C,IAAI,EAAE,gBAAgB,GAAG,kBAAkB,GAAG,IAAI,CAAA;IAClD,GAAG,EAAE,KAAK,GAAG,QAAQ,GAAG,IAAI,CAAA;IAC5B,oGAAoG;IACpG,KAAK,EAAE,WAAW,GAAG,IAAI,CAAA;IACzB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,cAAc,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAAA;IACxC,OAAO,EAAE,aAAa,CAAA;IACtB,SAAS,EAAE,MAAM,CAAA;CAClB;AA2BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAa1F;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,EACzC,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA0D1B"}

package/dist/decideSdk.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * `decide(state, questions, opts)` for people building their own agents: ask
+ * a self-hosted model a few narrow questions about a state, and get each
+ * answer's probability, its three-valued reading through a band and, with a
+ * `when`, the outcome a decide rule would reach.
+ *
+ * The questions are written as a decide rule's `questions` and validated
+ * the same way, so wording that asks the model for approval is refused. Every
+ * call goes through the engine client and its host guard: a hosted decision
+ * API is refused before anything is sent, and there is no way to pass an
+ * engine object that skips the guard.
+ *
+ * Errors are {@link DecideEngineError}s and are thrown, so a caller cannot
+ * read an unavailable engine as an answer. The one exception is
+ * `too_large`: a state over the limit is never truncated, every answer is
+ * unknown, and with a `when` the outcome escalates.
+ *
+ * Self-contained but for the decide modules beside it, so `@intutic/gate` and
+ * `@intutic/clawde` carry byte-identical copies; each wraps it in a `decide()`
+ * that reads `~/.intutic/decide/engine.json` and the process environment. The
+ * Python port is `intutic_clawde/gate/decide_sdk.py`. All three run
+ * `fixtures/decide-sdk-vectors.json`.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DECIDE_ENGINE_FILE_PATH = exports.DECIDE_SDK_DEFAULT_BUDGET_MS = void 0;
+exports.loadDecideEngineFile = loadDecideEngineFile;
+exports.decideQuestions = decideQuestions;
+const decide_js_1 = require("./decide.js");
+const decideEngine_js_1 = require("./decideEngine.js");
+/** The budget when neither `budgetMs` nor `INTUTIC_DECIDE_BUDGET_MS` sets one. */
+exports.DECIDE_SDK_DEFAULT_BUDGET_MS = 7_300;
+/** The engine configuration's path under the home directory. */
+exports.DECIDE_ENGINE_FILE_PATH = ['.intutic', 'decide', 'engine.json'];
+/**
+ * The rule the questions are checked as: an `on: response` rule whose `when`
+ * is the caller's, or one naming every question once.
+ */
+function sdkRule(questions, opts) {
+    const when = opts.when ??
+        Object.keys(questions)
+            .sort()
+            .map((n) => (questions[n]?.type === 'choice' ? `${n} == ${decide_js_1.NONE_OF_THESE}` : n))
+            .join(' OR ');
+    const rule = { id: 'sdk', on: 'response', questions, when };
+    if (opts.band !== undefined)
+        rule.band = opts.band;
+    if (opts.escalate !== undefined)
+        rule.escalate = opts.escalate;
+    return rule;
+}
+function budgetFrom(opts, env) {
+    if (opts.budgetMs !== undefined)
+        return opts.budgetMs;
+    const raw = env.INTUTIC_DECIDE_BUDGET_MS?.trim();
+    if (!raw)
+        return exports.DECIDE_SDK_DEFAULT_BUDGET_MS;
+    if (!/^[0-9]+$/.test(raw))
+        throw new decideEngine_js_1.DecideEngineError('not_configured', 'INTUTIC_DECIDE_BUDGET_MS must be a whole number');
+    return Number(raw);
+}
+/**
+ * `engine.json`'s parsed content through `read`, or null when the file does
+ * not exist. A file that does not parse leaves the engine not configured.
+ */
+function loadDecideEngineFile(read, path) {
+    let text;
+    try {
+        text = read(path);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw new decideEngine_js_1.DecideEngineError('not_configured', `${path} cannot be read`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new decideEngine_js_1.DecideEngineError('not_configured', `${path} is not JSON`);
+    }
+}
+/**
+ * Asks `questions` about `state`. Throws a `TypeError` for questions (or a
+ * `when`) a decide rule would refuse, and a {@link DecideEngineError} when
+ * the engine is not configured, its host is refused, or it cannot answer.
+ */
+async function decideQuestions(state, questions, opts = {}) {
+    if (typeof state !== 'string')
+        throw new TypeError('decide: state must be a string');
+    const v = (0, decide_js_1.validateDecideRule)(sdkRule(questions, opts));
+    if (!v.ok)
+        throw new TypeError(v.reason);
+    const rule = v.rule;
+    const env = opts.env ?? {};
+    const cfg = opts.engine ?? (0, decideEngine_js_1.resolveDecideEngineConfig)(opts.engineFile ?? null, env);
+    const budgetMs = budgetFrom(opts, env);
+    const engine = (0, decideEngine_js_1.createDecideEngine)(cfg);
+    const names = Object.keys(rule.questions).sort();
+    const calls = names.map((name) => {
+        const q = rule.questions[name];
+        return q.type === 'choice' ? { name, type: 'choice', ask: q.ask, options: (0, decide_js_1.decideOptions)(q) } : { name, type: 'yes_no', ask: q.ask };
+    });
+    const started = Date.now();
+    let res = null;
+    // A caller's state is held to the tool-call limit: the engine takes larger
+    // ones, up to an `on: response` state's limit, from the state builders only.
+    if (new TextEncoder().encode(state).length <= decideEngine_js_1.DECIDE_MAX_STATE_BYTES) {
+        try {
+            res = await engine.ask(state, calls, started + budgetMs);
+        }
+        catch (err) {
+            if (!(err instanceof decideEngine_js_1.DecideEngineError) || err.code !== 'too_large')
+                throw err;
+        }
+    }
+    const inputs = {};
+    const answers = {};
+    for (const name of names) {
+        const q = rule.questions[name];
+        const a = res?.answers[name];
+        const band = (0, decide_js_1.decideQuestionBand)(rule, name);
+        inputs[name] = { p: a?.p, perOrder: a?.perOrder };
+        if (q.type === 'yes_no') {
+            const p = typeof a?.p === 'number' ? a.p : null;
+            answers[name] = { type: 'yes_no', p, value: p === null ? 'U' : (0, decide_js_1.bandValue)(p, band) };
+        }
+        else {
+            const options = (0, decide_js_1.choiceAtoms)((0, decide_js_1.decideOptions)(q), a?.perOrder ?? [], band);
+            const choice = Object.keys(options).find((o) => options[o].value === 'T') ?? null;
+            answers[name] = { type: 'choice', perOrder: a?.perOrder ?? null, options, choice };
+        }
+    }
+    const ruled = opts.when === undefined ? null : (0, decide_js_1.decideRuleOutcome)(rule, v.expr, inputs);
+    return {
+        answers,
+        value: ruled?.value ?? null,
+        outcome: ruled?.outcome ?? null,
+        code: ruled?.code ?? null,
+        via: ruled?.via ?? null,
+        error: res ? null : 'too_large',
+        model: res?.model ?? null,
+        modelDigest: res?.modelDigest ?? null,
+        digestStrength: res?.digestStrength ?? null,
+        adapter: cfg.adapter,
+        latencyMs: res?.latencyMs ?? Date.now() - started,
+    };
+}
+//# sourceMappingURL=decideSdk.js.map