@gobing-ai/ts-decision-fm 0.5.3

package/LICENSE

@@ -0,0 +1,176 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,5 @@
+@gobing-ai/ts-decision-fm
+Copyright 2026 Robin Min and ts-libs contributors
+
+This package bundles no third-party code and no model weights. The engine
+is the `fm` system binary on the host (macOS 27+).

package/README.md

@@ -0,0 +1,149 @@
+# @gobing-ai/ts-decision-fm
+
+Apple on-device Foundation Model decision backend for the neutral decision
+surface owned by `@gobing-ai/ts-ai-runner`: answers `choice` / `score` / `noul`
+questions on-device by driving the macOS 27 `fm` command-line tool as one-shot
+processes over `ts-runtime`'s `ProcessExecutor`
+([ADR-029](../../docs/00_ADR.md)). Probabilities are empirical sample
+frequencies — the model is never asked for a confidence
+([ADR-030](../../docs/00_ADR.md)).
+
+Part of the `@gobing-ai/ts-libs` monorepo and lockstep-versioned with it.
+
+- **License:** Apache-2.0 (see [LICENSE](./LICENSE)).
+- **No model weights or third-party code are bundled.** The engine is the `fm`
+  system binary on the host.
+
+---
+
+## Host prerequisites
+
+1. **Platform:** macOS on Apple Silicon (`darwin arm64`). Unsupported hosts fail
+   at construction with a `DecisionConfigError`, before any process is spawned.
+2. **`fm` CLI:** macOS 27+ ships `/usr/bin/fm` (validated against build
+   `FoundationModels-2.0.68.1.402`). A custom path can be injected via
+   `fmPath`. A missing binary is reported as `DecisionConfigError` "fm not
+   found" on the first ask.
+3. **System model availability:** probed once per driver with
+   `fm available --model system` before the first sample and cached for the
+   driver's lifetime. A model that is present but not ready raises
+   `DecisionConfigError` carrying fm's reason (e.g. `modelNotReady`).
+
+---
+
+## Usage
+
+```ts
+import { createFmDriver } from '@gobing-ai/ts-decision-fm';
+
+const driver = createFmDriver(); // defaults; or createFmDriver({ samples: 7 })
+const answers = await driver.ask({
+    state: 'Customer was billed twice for invoice INV-42.',
+    questions: {
+        sentiment: {
+            kind: 'choice',
+            prompt: 'Sentiment of the message',
+            labels: { positive: 'Praise', negative: 'Complaint' },
+        },
+        priority: {
+            kind: 'score',
+            prompt: 'Queue priority',
+            rubric: ['Routine — normal SLA', 'Critical — customer blocked'],
+        },
+        refund: { kind: 'noul', prompt: 'Refund the duplicate charge?' },
+    },
+});
+// answers.sentiment: { kind: 'choice', label, confidence, probabilities }
+// answers.priority:  { kind: 'score', score, confidence, legend, probabilities }
+// answers.refund:    { kind: 'noul', probability }
+```
+
+The `model` argument of `ask` accepts only `undefined` or `'system'` — the
+on-device system model is the only one fm offers; anything else raises
+`DecisionRequestError`.
+
+### Options
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `samples` | `5` | Sequential `fm respond` samples per ask. Ignored when `deterministic`. |
+| `deterministic` | `false` | One greedy sample (`fm respond -g`); probabilities are one-hot, confidence 1. |
+| `maxPromptTokens` | `6000` | Pre-flight budget. The rendered prompt is counted with `fm count-tokens -q` before sampling; over budget raises `DecisionRequestError` and no model call runs. |
+| `requestTimeoutMs` | `30000` | Budget for one `fm respond` process; expiry raises `DecisionTimeoutError`. |
+| `guardrails` | omitted | `--guardrails` level (`'default'` \| `'permissive-content-transformations'`). |
+| `fmPath` | `'fm'` | Executable to spawn. |
+| `executor` | ts-runtime `ProcessExecutor` | Injected process seam (tests stub this). |
+| `platform`, `arch` | `process.platform`, `process.arch` | Injectable host facts so tests can pin the host. |
+
+### Backend selection (`ts-ai-runner`)
+
+The `fm-local` backend name joins `createDecisionMaker` via `ts-ai-runner`
+(task 0085); `ts-ai-runner` resolves `@gobing-ai/ts-decision-fm` through a
+dynamic import, the same way `laya-local` resolves `ts-laya-mlx`. Callers who
+need non-default options pass the driver explicitly:
+
+```ts
+import { createDecisionMaker } from '@gobing-ai/ts-ai-runner';
+import { createFmDriver } from '@gobing-ai/ts-decision-fm';
+
+const dm = createDecisionMaker({ driver: createFmDriver({ deterministic: true }) });
+```
+
+---
+
+## Estimator semantics (read before trusting `confidence`)
+
+Every probability this driver returns is a **frequency over k parsed samples**
+(`estimator: { kind: 'sample-frequency' }`):
+
+- `choice` — `probabilities[label] = count(label) / k` for every supplied label
+  (unsampled labels get 0). `label` is the most frequent with ties broken by
+  label declaration order.
+- `score` — the same over level indices; ties go to the lower level.
+- `noul` — a bare yes-probability, no `confidence` key, by contract.
+
+`confidence` is `1 − H(p) / ln(n)` over the declared options — the Laya
+reference's `confidence_from_probs` on the empirical distribution. It measures
+**how much the samples agreed, not calibration**. The model is never asked for a
+confidence; a self-reported one would be fabricated calibration.
+
+Resolution limit: with k samples every probability is a multiple of 1/k, and
+`confidence` has at most k+1 distinct values. k = 5 detects a 60/40 split, not a
+64/36 one. In deterministic mode k = 1, so every answer is one-hot with
+confidence 1.
+
+### Latency
+
+fm one-shot calls cost ~0.3 s warm each, so an ask costs **~0.3 s × k** (plus
+one `count-tokens` call). Calls are sequential by design: parallel sampling is
+out of scope and fm exposes no logprobs that would make batching worthwhile
+(ADR-029).
+
+---
+
+## Errors
+
+All failures surface through the `@gobing-ai/ts-ai-runner` decision error
+taxonomy — never as an answer:
+
+| Condition | Class |
+|-----------|-------|
+| Not darwin/arm64; `fm` not found; system model unavailable | `DecisionConfigError` |
+| `model` other than `system`; prompt over `maxPromptTokens`; fewer than two options | `DecisionRequestError` |
+| fm reports the context size was exceeded | `DecisionRequestError` |
+| fm reports the safety guardrails were triggered | `DecisionBackendError` (not retried) |
+| Other non-zero exit; non-JSON stdout; schema violation | `DecisionBackendError` |
+| A sample exceeded `requestTimeoutMs` | `DecisionTimeoutError` |
+
+Failure is all-or-nothing: one failed sample rejects the whole ask. Partial
+frequencies are never returned as probabilities.
+
+---
+
+## Testing
+
+The default suite is stubbed (injected `ProcessExecutor`, pinned
+`darwin`/`arm64`) and runs on every platform including Linux CI. The live suite
+(`tests/live.test.ts`) runs only where the system model is actually available
+(darwin/arm64 and `fm available --model system` exits 0) and skips with a stated
+reason everywhere else.

package/dist/driver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 DecisionDriver } from '@gobing-ai/ts-ai-runner';
+import { type ProcessExecutor } from '@gobing-ai/ts-runtime';
+import { type FmGuardrails } from './fm-process';
+/** 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 declare function createFmDriver(options?: FmDriverOptions): FmDecisionDriver;
+//# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGH,KAAK,cAAc,EAItB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAKH,KAAK,eAAe,EACvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAEH,KAAK,YAAY,EAMpB,MAAM,cAAc,CAAC;AAGtB,wDAAwD;AACxD,MAAM,WAAW,eAAe;IAC5B,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0FAA0F;IAC1F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,mFAAmF;AACnF,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACpD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,mFAAmF;IACnF,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;CACjH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,gBAAgB,CAwI9E"}

package/dist/driver.js

@@ -0,0 +1,105 @@
+/**
+ * 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 { DecisionConfigError, DecisionRequestError, } from '@gobing-ai/ts-ai-runner';
+import { createNodeFileSystem, getProcessEnv, joinPath, nodeBunFactory, } from '@gobing-ai/ts-runtime';
+import { estimateChoice, estimateNoul, estimateScore } from './estimate.js';
+import { countPromptTokens, parseFmRespond, probeFmAvailability, requireEnumValue, respondArgv, runFmRespond, } from './fm-process.js';
+import { buildFmSchema, buildPrompt, declaredOptions, FM_INSTRUCTIONS } from './schema.js';
+/**
+ * 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 = {}) {
+    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() {
+        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, }) {
+            // 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, []]));
+                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 = {};
+                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);
+            }
+        },
+    };
+}

package/dist/estimate.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Probability estimation from repeated samples (task 0084 R6, ADR-030,
+ * design § Probability estimation). Every probability is an empirical sample
+ * frequency — never a self-reported confidence — so the resolution limit is
+ * 1/k and `confidence` measures how much the k samples agreed, not calibration.
+ */
+import type { ChoiceAnswer, Desc, NoulAnswer, ScoreAnswer } from '@gobing-ai/ts-ai-runner';
+/**
+ * Laya reference `confidence_from_probs` on the empirical distribution:
+ * `1 − H(p) / ln(n)` over the n declared options. One-hot ⇒ 1, uniform ⇒ 0.
+ */
+export declare function entropyConfidence(probabilities: number[]): number;
+/**
+ * Choice frequencies over every supplied label (unsampled ⇒ 0). The answer
+ * label is the most frequent with ties broken by label declaration order.
+ */
+export declare function estimateChoice(labels: readonly string[], samples: readonly string[]): ChoiceAnswer<string>;
+/**
+ * Score frequencies over the level indices `0…n-1`. The answer score is the
+ * most frequent level with ties going to the lower level; the legend maps each
+ * index back to its rubric description.
+ */
+export declare function estimateScore(rubric: readonly Desc[], samples: readonly string[]): ScoreAnswer;
+/** Noul is a bare yes-probability — no `confidence` key, by contract. */
+export declare function estimateNoul(samples: readonly string[]): NoulAnswer;
+//# sourceMappingURL=estimate.d.ts.map

package/dist/estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"estimate.d.ts","sourceRoot":"","sources":["../src/estimate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3F;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,MAAM,CAQjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAyB1G;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,IAAI,EAAE,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,WAAW,CAiC9F;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU,CAGnE"}

package/dist/estimate.js

@@ -0,0 +1,90 @@
+/**
+ * Laya reference `confidence_from_probs` on the empirical distribution:
+ * `1 − H(p) / ln(n)` over the n declared options. One-hot ⇒ 1, uniform ⇒ 0.
+ */
+export function entropyConfidence(probabilities) {
+    const n = probabilities.length;
+    if (n <= 1)
+        return 1;
+    let entropy = 0;
+    for (const p of probabilities) {
+        if (p > 0)
+            entropy -= p * Math.log(p);
+    }
+    return 1 - entropy / Math.log(n);
+}
+/**
+ * Choice frequencies over every supplied label (unsampled ⇒ 0). The answer
+ * label is the most frequent with ties broken by label declaration order.
+ */
+export function estimateChoice(labels, samples) {
+    const counts = new Map(labels.map((label) => [label, 0]));
+    for (const sample of samples)
+        counts.set(sample, (counts.get(sample) ?? 0) + 1);
+    const k = samples.length;
+    const probabilities = {};
+    const distribution = [];
+    let bestLabel = labels[0] ?? '';
+    let bestCount = -1;
+    for (const label of labels) {
+        const count = counts.get(label) ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[label] = probability;
+        // Declaration order wins ties: strict `>` keeps the earlier label.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLabel = label;
+        }
+    }
+    return {
+        kind: 'choice',
+        label: bestLabel,
+        confidence: entropyConfidence(distribution),
+        probabilities,
+    };
+}
+/**
+ * Score frequencies over the level indices `0…n-1`. The answer score is the
+ * most frequent level with ties going to the lower level; the legend maps each
+ * index back to its rubric description.
+ */
+export function estimateScore(rubric, samples) {
+    const k = samples.length;
+    const counts = [];
+    for (const sample of samples) {
+        const level = Number.parseInt(sample, 10);
+        counts[level] = (counts[level] ?? 0) + 1;
+    }
+    const probabilities = {};
+    const distribution = [];
+    let bestLevel = 0;
+    let bestCount = -1;
+    for (let level = 0; level < rubric.length; level++) {
+        const count = counts[level] ?? 0;
+        const probability = count / k;
+        distribution.push(probability);
+        probabilities[level] = probability;
+        // Lower level wins ties: strict `>` keeps the smaller index.
+        if (count > bestCount) {
+            bestCount = count;
+            bestLevel = level;
+        }
+    }
+    const legend = {};
+    rubric.forEach((desc, level) => {
+        legend[level] = desc;
+    });
+    return {
+        kind: 'score',
+        score: bestLevel,
+        confidence: entropyConfidence(distribution),
+        legend,
+        probabilities,
+    };
+}
+/** Noul is a bare yes-probability — no `confidence` key, by contract. */
+export function estimateNoul(samples) {
+    const yes = samples.filter((sample) => sample === 'yes').length;
+    return { kind: 'noul', probability: yes / samples.length };
+}

package/dist/fm-process.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 type { ProcessExecutor } from '@gobing-ai/ts-runtime';
+/** `--guardrails` levels accepted by `fm respond` (design: fm CLI facts). */
+export type FmGuardrails = 'default' | 'permissive-content-transformations';
+/** Subcommand + flag order verified against the design's live observations. */
+export declare function countTokensArgv(instructions: string, prompt: string): string[];
+/** Builds the `fm respond` argv: schema flag, `-i` instructions, positional prompt, optional `-g`/`--guardrails`. */
+export declare function respondArgv(options: {
+    schemaPath: string;
+    instructions: string;
+    prompt: string;
+    /** Deterministic mode: single greedy sample. */
+    greedy?: boolean;
+    /** Omitted ⇒ the flag is omitted (fm's `default`). */
+    guardrails?: FmGuardrails;
+}): string[];
+/** Bare `fm available` always exits 0 — only `--model system` is a real probe. */
+export declare function availableArgv(): string[];
+/**
+ * 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 declare function probeFmAvailability(executor: ProcessExecutor, fmPath: string): Promise<void>;
+/**
+ * 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 declare function countPromptTokens(executor: ProcessExecutor, fmPath: string, instructions: string, prompt: string): Promise<number>;
+/**
+ * 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 declare function runFmRespond(executor: ProcessExecutor, fmPath: string, args: string[], requestTimeoutMs: number): Promise<string>;
+/**
+ * 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 declare function parseFmRespond(stdout: string): Record<string, string>;
+/** A parsed value outside the declared enum is a schema violation, never an answer (R7). */
+export declare function requireEnumValue(parsed: Record<string, string>, key: string, allowed: readonly string[]): string;
+//# sourceMappingURL=fm-process.d.ts.map