@gobing-ai/ts-decision-fm 0.5.3

package/dist/fm-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fm-process.d.ts","sourceRoot":"","sources":["../src/fm-process.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,uBAAuB,CAAC;AAE5E,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,oCAAoC,CAAC;AAE5E,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9E;AAED,qHAAqH;AACrH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,YAAY,CAAC;CAC7B,GAAG,MAAM,EAAE,CAYX;AAED,kFAAkF;AAClF,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAaD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlG;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACnC,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAMD;;;;GAIG;AACH,wBAAsB,YAAY,CAC9B,QAAQ,EAAE,eAAe,EACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,EACd,gBAAgB,EAAE,MAAM,GACzB,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBrE;AAED,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAShH"}

package/dist/fm-process.js

@@ -0,0 +1,137 @@
+/**
+ * The one-shot `fm` process bridge (task 0084 R4, R5, R7, R8; design § Errors).
+ * Argv builders plus run/error mapping. Spawned exclusively through the
+ * injected ts-runtime {@link ProcessExecutor} — never `node:child_process`.
+ * Prompt and instructions travel as positional arguments because
+ * `ProcessExecutor.run` has no stdin input; fm's argv limit is far above the
+ * token budget, and the pre-flight `count-tokens` check keeps it bounded.
+ */
+import { DecisionBackendError, DecisionConfigError, DecisionRequestError, DecisionTimeoutError, } from '@gobing-ai/ts-ai-runner';
+/** Subcommand + flag order verified against the design's live observations. */
+export function countTokensArgv(instructions, prompt) {
+    return ['count-tokens', '-q', '-i', instructions, prompt];
+}
+/** Builds the `fm respond` argv: schema flag, `-i` instructions, positional prompt, optional `-g`/`--guardrails`. */
+export function respondArgv(options) {
+    return [
+        'respond',
+        '--no-stream',
+        '--schema',
+        options.schemaPath,
+        '-i',
+        options.instructions,
+        ...(options.guardrails !== undefined ? ['--guardrails', options.guardrails] : []),
+        ...(options.greedy ? ['-g'] : []),
+        options.prompt,
+    ];
+}
+/** Bare `fm available` always exits 0 — only `--model system` is a real probe. */
+export function availableArgv() {
+    return ['available', '--model', 'system'];
+}
+/** The executor reports a failed spawn (ENOENT, …) as an `error` outcome. */
+function isSpawnFailure(result) {
+    return result.outcome === 'error' && result.exitCode === null;
+}
+/** fm's own text, preferring stderr, for carrying into error messages. */
+function fmText(result) {
+    const text = (result.stderr.trim().length > 0 ? result.stderr : result.stdout).trim();
+    return text.length > 0 ? text : '(no output)';
+}
+/**
+ * R8 prerequisite probe: `fm available --model system`. A spawn failure maps to
+ * `DecisionConfigError` "fm not found"; a non-zero exit carries fm's printed
+ * reason (e.g. `modelNotReady`). An exit 0 caches availability in the driver.
+ */
+export async function probeFmAvailability(executor, fmPath) {
+    const result = await executor.run({ command: fmPath, args: availableArgv() });
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        throw new DecisionConfigError(`fm system model unavailable: ${fmText(result)}`, 'fm-system-model');
+    }
+}
+/**
+ * R4 pre-flight: `fm count-tokens -q -i <instructions> <prompt>` prints a bare
+ * integer. Non-zero exit or unparseable output is a `DecisionBackendError` —
+ * the budget comparison itself happens in the driver.
+ */
+export async function countPromptTokens(executor, fmPath, instructions, prompt) {
+    const result = await executor.run({ command: fmPath, args: countTokensArgv(instructions, prompt) });
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        throw new DecisionBackendError(`fm count-tokens failed (exit ${result.exitCode}): ${fmText(result)}`, undefined);
+    }
+    const tokens = Number.parseInt(result.stdout.trim(), 10);
+    if (!Number.isFinite(tokens)) {
+        throw new DecisionBackendError(`fm count-tokens did not print a token count: ${result.stdout.trim() || '(empty)'}`, undefined);
+    }
+    return tokens;
+}
+/** Stable substrings of fm's failure text (design § Errors discrimination). */
+const CONTEXT_SIZE_MARKER = "exceeded the model's context size";
+const GUARDRAILS_MARKER = 'safety guardrails were triggered';
+/**
+ * One `fm respond` sample: run with the per-sample timeout, map every failure
+ * row of the error table, return stdout on success (parsing happens in
+ * {@link parseFmRespond}).
+ */
+export async function runFmRespond(executor, fmPath, args, requestTimeoutMs) {
+    const result = await executor.run({ command: fmPath, args, timeout: requestTimeoutMs });
+    if (result.outcome === 'timeout') {
+        throw new DecisionTimeoutError(`fm respond exceeded requestTimeoutMs (${requestTimeoutMs}): ${fmPath} ${args.join(' ')}`, requestTimeoutMs);
+    }
+    if (isSpawnFailure(result)) {
+        throw new DecisionConfigError(`fm not found: '${fmPath}' could not be spawned`, 'fmPath');
+    }
+    if (result.exitCode !== 0) {
+        const text = fmText(result);
+        if (text.includes(CONTEXT_SIZE_MARKER)) {
+            throw new DecisionRequestError(`fm prompt exceeded the model context size: ${text}`, undefined, undefined);
+        }
+        if (text.includes(GUARDRAILS_MARKER)) {
+            // Typed failure, never an answer, and the ask is not retried.
+            throw new DecisionBackendError(`fm safety guardrails were triggered: ${text}`, undefined);
+        }
+        throw new DecisionBackendError(`fm respond failed (exit ${result.exitCode}): ${text}`, undefined);
+    }
+    return result.stdout;
+}
+/**
+ * Parse one sample's stdout as the schema-conformant JSON object. fm prints one
+ * JSON object per call, but the key order varies — callers read by key, never
+ * by position. Non-JSON or non-object output is a `DecisionBackendError`.
+ */
+export function parseFmRespond(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (cause) {
+        throw new DecisionBackendError(`fm respond printed non-JSON output: ${stdout.trim() || '(empty)'}`, undefined, {
+            cause,
+        });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new DecisionBackendError(`fm respond printed non-object JSON: ${stdout.trim()}`, undefined);
+    }
+    const record = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new DecisionBackendError(`fm respond printed a non-string value for '${key}'`, undefined);
+        }
+        record[key] = value;
+    }
+    return record;
+}
+/** A parsed value outside the declared enum is a schema violation, never an answer (R7). */
+export function requireEnumValue(parsed, key, allowed) {
+    const value = parsed[key];
+    if (value === undefined || !allowed.includes(value)) {
+        throw new DecisionBackendError(`fm sample for '${key}' violates the schema enum: ${value === undefined ? '(missing)' : `'${value}'`}`, undefined);
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @gobing-ai/ts-decision-fm — Apple on-device Foundation Model decision backend
+ * driving the macOS `fm` CLI over a one-shot process bridge (ADR-029).
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner`;
+ * probabilities are empirical sample frequencies (ADR-030).
+ */
+export { createFmDriver, type FmDecisionDriver, type FmDriverOptions } from './driver';
+export { entropyConfidence, estimateChoice, estimateNoul, estimateScore } from './estimate';
+export { availableArgv, countPromptTokens, countTokensArgv, type FmGuardrails, parseFmRespond, probeFmAvailability, requireEnumValue, respondArgv, runFmRespond, } from './fm-process';
+export { buildFmSchema, buildPrompt, declaredOptions, FM_INSTRUCTIONS, type FmSchema, formatDesc } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AACvF,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EACH,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,YAAY,EACjB,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,WAAW,EACX,YAAY,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,eAAe,EAAE,eAAe,EAAE,KAAK,QAAQ,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @gobing-ai/ts-decision-fm — Apple on-device Foundation Model decision backend
+ * driving the macOS `fm` CLI over a one-shot process bridge (ADR-029).
+ * Implements the {@link DecisionDriver} interface for `@gobing-ai/ts-ai-runner`;
+ * probabilities are empirical sample frequencies (ADR-030).
+ */
+export { createFmDriver } from './driver.js';
+export { entropyConfidence, estimateChoice, estimateNoul, estimateScore } from './estimate.js';
+export { availableArgv, countPromptTokens, countTokensArgv, parseFmRespond, probeFmAvailability, requireEnumValue, respondArgv, runFmRespond, } from './fm-process.js';
+export { buildFmSchema, buildPrompt, declaredOptions, FM_INSTRUCTIONS, formatDesc } from './schema.js';

package/dist/schema.d.ts

@@ -0,0 +1,43 @@
+/**
+ * fm request construction (task 0084 R3, design § Request construction):
+ * the JSON schema passed to `fm respond --schema` and the instruction/prompt
+ * texts passed via `-i` and as the final positional argument.
+ *
+ * The schema always carries `x-order` — a hand-written object schema without it
+ * is rejected by `fm` ("The data couldn't be read because it is missing").
+ * Score levels are string enums so every question uses the same constrained
+ * string path; the driver converts them back to numbers.
+ */
+import type { DecisionState, Desc, Question } from '@gobing-ai/ts-ai-runner';
+/**
+ * Fixed `-i` instructions. It never asks for confidence, certainty or a
+ * probability — self-reported confidence would be fabricated calibration,
+ * which the decision contract forbids (ADR-030).
+ */
+export declare const FM_INSTRUCTIONS: string;
+/** The JSON schema object handed to `fm respond --schema` (R3). */
+export interface FmSchema {
+    type: 'object';
+    title: string;
+    'x-order': string[];
+    required: string[];
+    additionalProperties: false;
+    properties: Record<string, {
+        type: 'string';
+        enum: string[];
+    }>;
+}
+/** Build the fm schema over the whole question map: one call answers every key. */
+export declare function buildFmSchema(questions: Record<string, Question>): FmSchema;
+/** Format a {@link Desc} into prompt text: strings verbatim, structured values JSON, absence empty. */
+export declare function formatDesc(desc: Desc | undefined): string;
+/** The declared option values of a question, in declaration order (estimation + validation share this). */
+export declare function declaredOptions(question: Question): string[];
+/**
+ * Render the positional prompt: the state as text (JSON when structured), then
+ * one block per question key with the prompt `Desc` and its options with
+ * descriptions — choice label keys, score level indices with the rubric text,
+ * noul `yes`/`no` with any outcome descriptions.
+ */
+export declare function buildPrompt(state: DecisionState, questions: Record<string, Question>): string;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,eAAe,QAGyB,CAAC;AAEtD,mEAAmE;AACnE,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oBAAoB,EAAE,KAAK,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,QAAQ,CAwB3E;AAED,uGAAuG;AACvG,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,CAIzD;AAED,2GAA2G;AAC3G,wBAAgB,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,EAAE,CAS5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,CAkC7F"}

package/dist/schema.js

@@ -0,0 +1,104 @@
+/**
+ * fm request construction (task 0084 R3, design § Request construction):
+ * the JSON schema passed to `fm respond --schema` and the instruction/prompt
+ * texts passed via `-i` and as the final positional argument.
+ *
+ * The schema always carries `x-order` — a hand-written object schema without it
+ * is rejected by `fm` ("The data couldn't be read because it is missing").
+ * Score levels are string enums so every question uses the same constrained
+ * string path; the driver converts them back to numbers.
+ */
+/**
+ * Fixed `-i` instructions. It never asks for confidence, certainty or a
+ * probability — self-reported confidence would be fabricated calibration,
+ * which the decision contract forbids (ADR-030).
+ */
+export const FM_INSTRUCTIONS = 'You are a decision engine. Answer every question below using only the supplied state. ' +
+    'For each question choose exactly one of the listed options. ' +
+    'Reply with the JSON object the schema requires.';
+/** Build the fm schema over the whole question map: one call answers every key. */
+export function buildFmSchema(questions) {
+    const properties = {};
+    for (const [key, question] of Object.entries(questions)) {
+        switch (question.kind) {
+            case 'choice':
+                properties[key] = { type: 'string', enum: Object.keys(question.labels) };
+                break;
+            case 'score':
+                properties[key] = { type: 'string', enum: question.rubric.map((_, level) => String(level)) };
+                break;
+            case 'noul':
+                properties[key] = { type: 'string', enum: ['yes', 'no'] };
+                break;
+        }
+    }
+    const keys = Object.keys(questions);
+    return {
+        type: 'object',
+        title: 'Decision',
+        'x-order': keys,
+        required: keys,
+        additionalProperties: false,
+        properties,
+    };
+}
+/** Format a {@link Desc} into prompt text: strings verbatim, structured values JSON, absence empty. */
+export function formatDesc(desc) {
+    if (typeof desc === 'string')
+        return desc;
+    if (desc === null || desc === undefined)
+        return '';
+    return JSON.stringify(desc);
+}
+/** The declared option values of a question, in declaration order (estimation + validation share this). */
+export function declaredOptions(question) {
+    switch (question.kind) {
+        case 'choice':
+            return Object.keys(question.labels);
+        case 'score':
+            return question.rubric.map((_, level) => String(level));
+        case 'noul':
+            return ['yes', 'no'];
+    }
+}
+/**
+ * Render the positional prompt: the state as text (JSON when structured), then
+ * one block per question key with the prompt `Desc` and its options with
+ * descriptions — choice label keys, score level indices with the rubric text,
+ * noul `yes`/`no` with any outcome descriptions.
+ */
+export function buildPrompt(state, questions) {
+    const parts = [];
+    const stateText = typeof state === 'string' ? state : state === null || state === undefined ? '' : JSON.stringify(state);
+    if (stateText.length > 0)
+        parts.push(stateText);
+    for (const [key, question] of Object.entries(questions)) {
+        const lines = [];
+        const prompt = formatDesc(question.prompt);
+        lines.push(`Question "${key}":${prompt.length > 0 ? ` ${prompt}` : ''}`);
+        lines.push('Options:');
+        switch (question.kind) {
+            case 'choice':
+                for (const [label, desc] of Object.entries(question.labels)) {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${label}: ${d}` : `- ${label}`);
+                }
+                break;
+            case 'score':
+                question.rubric.forEach((desc, level) => {
+                    const d = formatDesc(desc);
+                    lines.push(d.length > 0 ? `- ${level}: ${d}` : `- ${level}`);
+                });
+                break;
+            case 'noul': {
+                for (const outcome of ['yes', 'no']) {
+                    const d = formatDesc(question[outcome]);
+                    lines.push(d.length > 0 ? `- ${outcome}: ${d}` : `- ${outcome}`);
+                }
+                break;
+            }
+        }
+        parts.push(lines.join('\n'));
+    }
+    return parts.join('\n\n');
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+    "name": "@gobing-ai/ts-decision-fm",
+    "version": "0.5.3",
+    "description": "@gobing-ai/ts-decision-fm — Apple on-device Foundation Model decision backend driving the macOS `fm` CLI over a one-shot process bridge.",
+    "keywords": [
+        "typescript",
+        "ai",
+        "decision",
+        "fm",
+        "foundation-models",
+        "apple",
+        "local"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gobing-ai/ts-libs.git",
+        "directory": "packages/decision-fm"
+    },
+    "author": "Robin Min <minlongbing@gmail.com>",
+    "contributors": [
+        "Robin Min <minlongbing@gmail.com>"
+    ],
+    "type": "module",
+    "private": false,
+    "sideEffects": false,
+    "license": "Apache-2.0",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "LICENSE",
+        "NOTICE"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && bun ../../scripts/builder.ts fix-dist-esm-extensions dist",
+        "test": "NODE_ENV=test bun test --coverage --coverage-dir=.coverage --reporter=dots",
+        "test:full": "NODE_ENV=test bun test --update-snapshots --coverage --coverage-dir=.coverage",
+        "typecheck": "tsc --noEmit",
+        "lint": "biome check . && bun run typecheck",
+        "format": "biome check . --write",
+        "check": "bun run lint && bun run test",
+        "prepublishOnly": "bun run build",
+        "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-decision-fm-v<version> && git push --tags' && exit 1"
+    },
+    "dependencies": {
+        "@gobing-ai/ts-ai-runner": "workspace:*",
+        "@gobing-ai/ts-runtime": "workspace:*"
+    },
+    "devDependencies": {
+        "@types/bun": "1.3.14"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/src/driver.ts

@@ -0,0 +1,206 @@
+/**
+ * The Apple `fm` decision driver (task 0084 R2, R8, R9; design § Main export).
+ * Satisfies the same {@link DecisionDriver} contract as the other backends over
+ * one-shot `fm` processes: one schema per ask answers the whole question map,
+ * probabilities come from k sample frequencies (ADR-030), and every failure
+ * surfaces through the decision error taxonomy — never as an answer.
+ */
+
+import {
+    type Answer,
+    DecisionConfigError,
+    type DecisionDriver,
+    DecisionRequestError,
+    type DecisionState,
+    type Question,
+} from '@gobing-ai/ts-ai-runner';
+import {
+    createNodeFileSystem,
+    getProcessEnv,
+    joinPath,
+    nodeBunFactory,
+    type ProcessExecutor,
+} from '@gobing-ai/ts-runtime';
+import { estimateChoice, estimateNoul, estimateScore } from './estimate';
+import {
+    countPromptTokens,
+    type FmGuardrails,
+    parseFmRespond,
+    probeFmAvailability,
+    requireEnumValue,
+    respondArgv,
+    runFmRespond,
+} from './fm-process';
+import { buildFmSchema, buildPrompt, declaredOptions, FM_INSTRUCTIONS } from './schema';
+
+/** Configuration options for {@link createFmDriver}. */
+export interface FmDriverOptions {
+    /** Samples per ask. Default: 5. Ignored when `deterministic` is true. */
+    samples?: number;
+    /** One greedy sample (`fm respond -g`); probabilities are one-hot. Default: false. */
+    deterministic?: boolean;
+    /** Prompt-token budget checked with `fm count-tokens` before sampling. Default: 6_000. */
+    maxPromptTokens?: number;
+    /** Budget for one `fm respond` process. Default: 30_000. */
+    requestTimeoutMs?: number;
+    /** `--guardrails` level. Default: omitted (fm's `default`). */
+    guardrails?: FmGuardrails;
+    /** Executable. Default: 'fm'. */
+    fmPath?: string;
+    /** Injected process seam. Default: ts-runtime's ProcessExecutor. */
+    executor?: ProcessExecutor;
+    /** Host platform, injectable so tests pin the host. Default: `process.platform` (as laya-mlx). */
+    platform?: string;
+    /** Host architecture. Default: `process.arch`. */
+    arch?: string;
+}
+
+/** The fm driver: a {@link DecisionDriver} with a declared estimator (ADR-030). */
+export interface FmDecisionDriver extends DecisionDriver {
+    readonly name: 'fm-local';
+    /** Declared estimator — how every probability this driver returns was produced. */
+    readonly estimator: { readonly kind: 'sample-frequency'; readonly samples: number; readonly greedy: boolean };
+}
+
+/**
+ * Build the `fm-local` decision driver. Host platform/architecture is checked
+ * here, at construction, without spawning (R8); the `fm` availability probe
+ * runs once, on the first `ask`, and is cached for the driver's lifetime.
+ */
+export function createFmDriver(options: FmDriverOptions = {}): FmDecisionDriver {
+    const {
+        samples = 5,
+        deterministic = false,
+        maxPromptTokens = 6_000,
+        requestTimeoutMs = 30_000,
+        guardrails,
+        fmPath = 'fm',
+        executor = nodeBunFactory.createProcessExecutor(),
+        platform = process.platform,
+        arch = process.arch,
+    } = options;
+
+    if (!Number.isInteger(samples) || samples < 1) {
+        throw new DecisionRequestError(`samples must be a positive integer; got ${samples}`, undefined, undefined);
+    }
+    const k = deterministic ? 1 : samples;
+
+    if (platform !== 'darwin' || arch !== 'arm64') {
+        throw new DecisionConfigError(
+            `decision-fm requires macOS on Apple Silicon (darwin arm64); current platform is '${platform} ${arch}'`,
+            'PLATFORM',
+        );
+    }
+
+    const fs = createNodeFileSystem();
+    let availabilityVerified = false;
+
+    async function ensureFmAvailable(): Promise<void> {
+        if (availabilityVerified) return;
+        await probeFmAvailability(executor, fmPath);
+        availabilityVerified = true;
+    }
+
+    return {
+        name: 'fm-local',
+        estimator: { kind: 'sample-frequency', samples: k, greedy: deterministic },
+
+        async ask({
+            state,
+            questions,
+            model,
+        }: {
+            state: DecisionState;
+            questions: Record<string, Question>;
+            model?: string;
+        }): Promise<Record<string, Answer>> {
+            // R9: only the on-device system model exists (design: fm CLI facts).
+            if (model !== undefined && model !== 'system') {
+                throw new DecisionRequestError(
+                    `fm-local supports only the 'system' model (or undefined); got '${model}'`,
+                    undefined,
+                    undefined,
+                );
+            }
+            const entries = Object.entries(questions);
+            if (entries.length === 0) {
+                throw new DecisionRequestError('expected a nonempty question map', undefined, undefined);
+            }
+            for (const [key, question] of entries) {
+                const optionCount =
+                    question.kind === 'choice'
+                        ? Object.keys(question.labels).length
+                        : question.kind === 'score'
+                          ? question.rubric.length
+                          : 2; // noul is binary by type
+                if (optionCount < 2) {
+                    throw new DecisionRequestError(
+                        `question '${key}' has fewer than two options (${optionCount})`,
+                        undefined,
+                        undefined,
+                    );
+                }
+            }
+
+            // R8: prerequisite probe before the first sample; cached per driver.
+            await ensureFmAvailable();
+
+            const instructions = FM_INSTRUCTIONS;
+            const prompt = buildPrompt(state, questions);
+
+            // R4: pre-flight budget — over budget rejects before any `fm respond`.
+            const tokens = await countPromptTokens(executor, fmPath, instructions, prompt);
+            if (tokens > maxPromptTokens) {
+                throw new DecisionRequestError(
+                    `prompt is ${tokens} tokens, above the maxPromptTokens budget of ${maxPromptTokens}`,
+                    undefined,
+                    undefined,
+                );
+            }
+
+            // R3: one schema per ask over the whole question map, in a uniquely
+            // named temp file, deleted in `finally` on success and failure.
+            const schemaPath = joinPath(getProcessEnv().TMPDIR ?? '/tmp', `fm-schema-${crypto.randomUUID()}.json`);
+            try {
+                fs.writeFile(schemaPath, JSON.stringify(buildFmSchema(questions)));
+
+                // R5: k sequential samples; each stdout parsed as JSON, read by key.
+                const allowed = new Map(entries.map(([key, question]) => [key, declaredOptions(question)]));
+                const samplesByKey = new Map(entries.map(([key]) => [key, [] as string[]]));
+                for (let i = 0; i < k; i++) {
+                    const stdout = await runFmRespond(
+                        executor,
+                        fmPath,
+                        respondArgv({ schemaPath, instructions, prompt, greedy: deterministic, guardrails }),
+                        requestTimeoutMs,
+                    );
+                    const parsed = parseFmRespond(stdout);
+                    for (const [key, values] of samplesByKey) {
+                        values.push(requireEnumValue(parsed, key, allowed.get(key) ?? []));
+                    }
+                }
+
+                // R6: frequencies over the declared labels/levels, argmax with
+                // declaration-order / lower-level tie-break, entropy confidence.
+                const answers: Record<string, Answer> = {};
+                for (const [key, question] of entries) {
+                    const values = samplesByKey.get(key) ?? [];
+                    switch (question.kind) {
+                        case 'choice':
+                            answers[key] = estimateChoice(Object.keys(question.labels), values);
+                            break;
+                        case 'score':
+                            answers[key] = estimateScore(question.rubric, values);
+                            break;
+                        case 'noul':
+                            answers[key] = estimateNoul(values);
+                            break;
+                    }
+                }
+                return answers;
+            } finally {
+                fs.deleteFile(schemaPath);
+            }
+        },
+    };
+}