pi-smart-router 0.21.0 → 0.22.0

package/.pi/extensions/smart-router/command-formatters.ts

@@ -1,23 +1,21 @@
 import {
   DEFAULT_HISTORY_LIMIT,
   MAX_HISTORY_LIMIT,
-} from '../../../src/infrastructure/telemetry/telemetry-limits.js';
+  aggregateSessionStatsFromFleet,
+  DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT,
+  parseExportTelemetryContribArgs,
+} from '../../../src/index.js';
 import type {
   ModelProfile,
   PriceCatalog,
   RoutingDecision,
   RoutingTelemetry,
-} from '../../../src/domain/types/index.js';
-import {
-  aggregateSessionStatsFromFleet,
-  type SessionStatsSnapshot,
-} from '../../../src/infrastructure/telemetry/session-stats.js';
+  SessionStatsSnapshot,
+  PlacementPlanReport,
+} from '../../../src/index.js';
+
 import { SMART_ROUTER_USAGE } from './commands.js';
-import {
-  DEFAULT_TELEMETRY_CONTRIB_EXPORT_LIMIT,
-  parseExportTelemetryContribArgs,
-} from '../../../src/cli/smart-router-cli.js';
-import type { PlacementPlanReport } from '../../../src/infrastructure/hardware/placement-plan.js';
+
 import {
   DEFAULT_DATASET_EXPORT_LIMIT,
   MAX_DATASET_EXPORT_LIMIT,

package/.pi/extensions/smart-router/commands.ts

@@ -10,8 +10,11 @@ import {
   parseSmartRouterArgs,
 } from './command-formatters.js';
 import { exportDatasetToFile } from './dataset-export.js';
-import { exportTelemetryContrib } from '../../../src/cli/smart-router-cli.js';
-import { collectPlacementPlan } from '../../../src/infrastructure/hardware/placement-plan.js';
+import {
+  exportTelemetryContrib,
+  collectPlacementPlan,
+} from '../../../src/index.js';
+
 import { bindSharedModelRegistry, rebuildFleet } from './fleet-bootstrap.js';
 import { refreshPricingCatalog } from './pricing-lifecycle.js';
 import { FLEET_MODE_ENTRY_TYPE } from './session-lifecycle.js';

package/.pi/extensions/smart-router/dataset-export.ts

@@ -6,15 +6,16 @@ import { createHash } from 'node:crypto';
 import {
   attachOutcomeLabelsToExport,
   indexOutcomesByRequestId,
-} from '../../../src/domain/routing/p-success-classifier.js';
-import { DATASET_MAX_ENTRIES } from '../../../src/infrastructure/telemetry/dataset-limits.js';
-import {
+  DATASET_MAX_ENTRIES,
   DatasetRecorder,
   DATASET_ENABLED_NOTIFY_MESSAGE,
-} from '../../../src/infrastructure/telemetry/dataset-recorder.js';
-import { OutcomeRecorder } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import type { RoutingDatasetRecord, RoutingOutcomeRecord } from '../../../src/domain/types/index.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
+  OutcomeRecorder,
+} from '../../../src/index.js';
+import type {
+  RoutingDatasetRecord,
+  RoutingOutcomeRecord,
+  StorePort,
+} from '../../../src/index.js';
 
 const DEFAULT_DATASET_EXPORT_DIR = '.pi-smart-router/exports';
 const DEFAULT_DATASET_EXPORT_LIMIT = DATASET_MAX_ENTRIES;

package/.pi/extensions/smart-router/delegate-stream.ts

@@ -9,13 +9,16 @@ import {
   streamSimple as compatDelegateStream,
 } from '@earendil-works/pi-ai/compat';
 
-import { parseAssistantMessageError } from '../../../src/infrastructure/delegation/provider-error.js';
-import { extractUsageActuals } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
 import {
+  parseAssistantMessageError,
+  extractUsageActuals,
   resolveAdaptiveReasoning,
-  type AdaptiveReasoningResult,
-  type AdaptiveReasoningSignal,
-} from '../../../src/domain/delegation/adaptive-reasoning.js';
+} from '../../../src/index.js';
+import type {
+  AdaptiveReasoningResult,
+  AdaptiveReasoningSignal,
+} from '../../../src/index.js';
+
 import {
   buildDelegationContext,
   forwardDelegatedEvent,

package/.pi/extensions/smart-router/delegation-runtime.ts

@@ -15,26 +15,23 @@ import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 
 import {
   applyConcisenessHint,
-  type AdaptiveReasoningResult,
-} from '../../../src/domain/delegation/adaptive-reasoning.js';
-import {
   isGoogleDelegationTarget,
   normalizeDelegationContext,
   repairGeminiReplayContext,
-} from '../../../src/domain/delegation/delegation-context.js';
-import {
   computeOutputHeadroom,
-  type OutputHeadroomConfig,
-} from '../../../src/domain/delegation/output-headroom.js';
-import type { ModelProfile } from '../../../src/domain/types/index.js';
-import {
   formatGeminiThoughtSignatureErrorMessage,
   formatProviderErrorMessage,
   isGeminiThoughtSignatureAssistantError,
   parseAssistantMessageError,
   sanitizeLengthStopMessage,
-  type LengthStopHints,
-} from '../../../src/infrastructure/delegation/provider-error.js';
+} from '../../../src/index.js';
+import type {
+  AdaptiveReasoningResult,
+  OutputHeadroomConfig,
+  ModelProfile,
+  LengthStopHints,
+} from '../../../src/index.js';
+
 import type { StreamDelegationDeps } from './types.js';
 
 /** Stream options safe to forward to a delegated provider call. */

package/.pi/extensions/smart-router/extension-setup.ts

@@ -4,10 +4,15 @@ import {
   type ExtensionAPI,
 } from '@earendil-works/pi-coding-agent';
 
-import { resolveOperatorConfigFromEnv } from '../../../src/config/defaults.js';
-import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
-import type { SessionRoutingSnapshot } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import { createRouterFromFleet, LifecycleHookState } from '../../../src/index.js';
+import {
+  resolveOperatorConfigFromEnv,
+  ExecutionLedger,
+  createRouterFromFleet,
+  LifecycleHookState,
+} from '../../../src/index.js';
+import type {
+  SessionRoutingSnapshot,
+} from '../../../src/index.js';
 
 import { registerSmartRouterCommand } from './commands.js';
 import {

package/.pi/extensions/smart-router/fleet-bootstrap.ts

@@ -2,39 +2,37 @@ import type { Api, Model } from '@earendil-works/pi-ai/compat';
 import {
   ModelRegistry,
   SettingsManager,
-  type ExtensionAPI,
+  ExtensionAPI,
 } from '@earendil-works/pi-coding-agent';
 
-import { mapFleetFromRegistry } from '../../../src/config/pi-model-mapper.js';
 import {
+  mapFleetFromRegistry,
   DEFAULT_OPERATOR_CONFIG,
   resolveOperatorConfigFromEnv,
-} from '../../../src/config/defaults.js';
-import {
   HydraMatcher,
   createOnnxEmbeddingProvider,
-} from '../../../src/domain/matching/hydra-matcher.js';
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
-import {
+  SessionPinner,
   collectPoolModelIds,
   resolveQuotaWindowEstimateConfigFromEnv,
   resolveQuotaWindowPosition,
-  type QuotaWindowAdapter,
-  type QuotaWindowEstimateConfig,
-} from '../../../src/domain/pricing/quota-window-feed.js';
-import type { ModelProfile, PriceCatalog } from '../../../src/domain/types/index.js';
-import type { QuotaWindowPosition } from '../../../src/domain/types/entities.js';
-import type { OperatorConfig } from '../../../src/domain/types/schemas.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import { getDefaultSystemInfo } from '../../../src/infrastructure/hardware/hardware-probe.js';
-import { DEFAULT_LOCAL_CONFIG } from '../../../src/infrastructure/local/local-zero-tier.js';
-import { RoutingTelemetryEmitter } from '../../../src/infrastructure/telemetry/routing-telemetry.js';
-import { applyCatalogPricesToFleet } from '../../../src/infrastructure/pricing/price-broker.js';
-import {
+  getDefaultSystemInfo,
+  DEFAULT_LOCAL_CONFIG,
+  RoutingTelemetryEmitter,
+  applyCatalogPricesToFleet,
   createRouterFromFleet,
-  type GatewayDispatchOptions,
-  type PiExtensionHooks,
 } from '../../../src/index.js';
+import type {
+  QuotaWindowAdapter,
+  QuotaWindowEstimateConfig,
+  ModelProfile,
+  PriceCatalog,
+  QuotaWindowPosition,
+  OperatorConfig,
+  StorePort,
+  GatewayDispatchOptions,
+  PiExtensionHooks,
+} from '../../../src/index.js';
+
 import { resolveModelScope } from './pi-model-scope.js';
 import type { FleetMode, SmartRouterRuntime } from './types.js';
 import { resolveRateLimiter } from './utils.js';

package/.pi/extensions/smart-router/index.ts

@@ -6,8 +6,9 @@
  * hooks for routing state. Stream delegation routes each request through the
  * pipeline and forwards to the selected provider's built-in streaming API.
  *
- * Imports from ../../../src/** (not dist/) because the extension is loaded by pi
- * from source at dev time and is excluded from the npm dist artifact.
+ * Imports the package public facade (../../../src/index.js, not dist/) because
+ * the extension is loaded by pi from source at dev time and is excluded from
+ * the npm dist artifact. Deep src/** subpath imports are forbidden (SP-256/257).
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -116,14 +117,14 @@ export { routeAndDelegate } from './route-and-delegate.js';
 export {
   formatGeminiThoughtSignatureErrorMessage,
   isGeminiThoughtSignatureAssistantError,
-} from '../../../src/infrastructure/delegation/provider-error.js';
+} from '../../../src/index.js';
 export {
   GEMINI_TOOL_HISTORY_EXCLUDED,
   hasToolCallHistory,
   hasToolCallHistoryFromContext,
   isGoogleGeminiProfile,
   resolveEffectiveFleet,
-} from '../../../src/domain/routing/tool-history-guard.js';
+} from '../../../src/index.js';
 
 export default async function smartRouterExtension(pi: ExtensionAPI): Promise<void> {
   const cwd = process.cwd();

package/.pi/extensions/smart-router/planning-delegate.ts

@@ -22,21 +22,22 @@ import {
   type TextContent,
 } from '@earendil-works/pi-ai/compat';
 
-import type {
-  CompressedContextSpec,
-  PlanningDelegateObservability,
-  RoutingDecision,
-} from '../../../src/domain/types/index.js';
-import { resolveAdaptiveReasoning } from '../../../src/domain/delegation/adaptive-reasoning.js';
-import { DEFAULT_PLANNING_DELEGATE_CONFIG } from '../../../src/domain/types/schemas.js';
 import {
+  resolveAdaptiveReasoning,
+  DEFAULT_PLANNING_DELEGATE_CONFIG,
   createPlanningDelegateObservability,
   enrichRoutingDecisionWithPlanningDelegate,
   PLANNING_DELEGATE,
   PLANNING_DELEGATE_TIMEOUT,
   PLANNING_DELEGATE_UNAVAILABLE,
   PLANNING_DIRECT_FRONTIER,
-} from '../../../src/infrastructure/telemetry/routing-telemetry.js';
+} from '../../../src/index.js';
+import type {
+  CompressedContextSpec,
+  PlanningDelegateObservability,
+  RoutingDecision,
+} from '../../../src/index.js';
+
 import { collectDelegatedStream } from './delegate-stream.js';
 import { findFleetProfile, resolveRegistryModel } from './delegation-runtime.js';
 import type { StreamDelegationDeps } from './types.js';

package/.pi/extensions/smart-router/pricing-lifecycle.ts

@@ -1,7 +1,12 @@
-import { DEFAULT_OPERATOR_CONFIG } from '../../../src/config/defaults.js';
-import type { PriceCatalog } from '../../../src/domain/types/index.js';
-import { fetchLitellmPriceCatalog } from '../../../src/infrastructure/pricing/litellm-fetch.js';
-import { checkStaleness } from '../../../src/infrastructure/pricing/pricing-monitor.js';
+import {
+  DEFAULT_OPERATOR_CONFIG,
+  fetchLitellmPriceCatalog,
+  checkStaleness,
+} from '../../../src/index.js';
+import type {
+  PriceCatalog,
+} from '../../../src/index.js';
+
 import type { SmartRouterRuntime } from './types.js';
 
 export async function refreshPricingCatalog(

package/.pi/extensions/smart-router/route-and-delegate.ts

@@ -7,27 +7,28 @@ import type {
   SimpleStreamOptions,
 } from '@earendil-works/pi-ai/compat';
 
-import { safeCloudDefault } from '../../../src/domain/pipeline/safe-default.js';
-import { computeOutputHeadroom } from '../../../src/domain/delegation/output-headroom.js';
-import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
 import {
+  safeCloudDefault,
+  computeOutputHeadroom,
+  resolvePeakPricingAdjustment,
   CONTEXT_OVERFLOW_NO_FIT,
   resolveContextOverflowFallback,
-} from '../../../src/domain/routing/context-fit.js';
-import {
   assertRoutableFleetAfterGeminiToolHistoryGuard,
   GEMINI_TOOL_HISTORY_EXCLUDED,
   isGoogleGeminiProfile,
   resolveEffectiveFleet,
-} from '../../../src/domain/routing/tool-history-guard.js';
-import type { ModelProfile, RoutingDecision, RoutingRequest } from '../../../src/domain/types/index.js';
-import type { GeminiToolHistoryGuardResult } from '../../../src/domain/routing/tool-history-guard.js';
-import {
   isGeminiThoughtSignatureAssistantError,
   parseAssistantMessageError,
-} from '../../../src/infrastructure/delegation/provider-error.js';
-import { GEMINI_REPLAY_INCOMPATIBLE } from '../../../src/infra/gemini-provider.js';
-import { shouldFailoverOnProviderError } from '../../../src/infrastructure/gateway/gateway-dispatch.js';
+  GEMINI_REPLAY_INCOMPATIBLE,
+  shouldFailoverOnProviderError,
+} from '../../../src/index.js';
+import type {
+  ModelProfile,
+  RoutingDecision,
+  RoutingRequest,
+  GeminiToolHistoryGuardResult,
+} from '../../../src/index.js';
+
 import {
   commitPipedTerminal,
   delegateWithOutcome,

package/.pi/extensions/smart-router/routing-context.ts

@@ -7,12 +7,14 @@ import {
   type TextContent,
 } from '@earendil-works/pi-ai/compat';
 
+import {
+  LifecycleHookState,
+} from '../../../src/index.js';
 import type {
   Message as RoutingMessage,
   RoutingRequest,
   TurnType,
-} from '../../../src/domain/types/index.js';
-import { LifecycleHookState } from '../../../src/index.js';
+} from '../../../src/index.js';
 
 const TOKEN_ESTIMATE_KEYS = [
   'estimatedInputTokens',

package/.pi/extensions/smart-router/routing-outcomes.ts

@@ -1,5 +1,9 @@
-import type { RoutingDecision, RoutingRequest } from '../../../src/domain/types/index.js';
-import type { SessionRoutingSnapshot } from '../../../src/infrastructure/telemetry/outcome-recorder.js';
+import type {
+  RoutingDecision,
+  RoutingRequest,
+  SessionRoutingSnapshot,
+} from '../../../src/index.js';
+
 import type { StreamDelegationDeps } from './types.js';
 
 export function capturePreRouteOutcomes(

package/.pi/extensions/smart-router/session-lifecycle.ts

@@ -1,7 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 
-import { evictInMemorySessionState } from '../../../src/api/session-eviction.js';
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import {
+  evictInMemorySessionState,
+  SessionPinner,
+} from '../../../src/index.js';
+
 import {
   bindSharedModelRegistry,
   ensureFleetFresh,

package/.pi/extensions/smart-router/stream-delegation.ts

@@ -7,8 +7,14 @@ import {
   createAssistantMessageEventStream,
 } from '@earendil-works/pi-ai/compat';
 
-import type { RoutingDecision, RoutingFeatureSidecar } from '../../../src/domain/types/index.js';
-import { resolvePeakPricingAdjustment } from '../../../src/domain/pricing/peak-pricing.js';
+import {
+  resolvePeakPricingAdjustment,
+} from '../../../src/index.js';
+import type {
+  RoutingDecision,
+  RoutingFeatureSidecar,
+} from '../../../src/index.js';
+
 import { createErrorMessage } from './delegation-runtime.js';
 import { routeAndDelegate } from './route-and-delegate.js';
 import type { StreamDelegationDeps } from './types.js';

package/.pi/extensions/smart-router/types.ts

@@ -7,10 +7,15 @@ import type {
 } from '@earendil-works/pi-ai/compat';
 import type { ModelRegistry } from '@earendil-works/pi-coding-agent';
 
-import type { HydraMatcher } from '../../../src/domain/matching/hydra-matcher.js';
-import { ExecutionLedger } from '../../../src/domain/delegation/execution-ledger.js';
-import { SessionPinner } from '../../../src/domain/pinning/session-pinner.js';
+import {
+  ExecutionLedger,
+  SessionPinner,
+  DatasetRecorder,
+  OutcomeRecorder,
+  LifecycleHookState,
+} from '../../../src/index.js';
 import type {
+  HydraMatcher,
   AdaptiveReasoningConfig,
   ModelProfile,
   PlanningDelegateConfig,
@@ -18,21 +23,13 @@ import type {
   RoutingDecision,
   RoutingReasoningTelemetry,
   RoutingUsageActuals,
-} from '../../../src/domain/types/index.js';
-import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import {
-  DatasetRecorder,
-} from '../../../src/infrastructure/telemetry/dataset-recorder.js';
-import {
-  OutcomeRecorder,
-  type SessionRoutingSnapshot,
-} from '../../../src/infrastructure/telemetry/outcome-recorder.js';
-import {
-  LifecycleHookState,
-  type RouterHandle,
+  StorePort,
+  SessionRoutingSnapshot,
+  RouterHandle,
 } from '../../../src/index.js';
 
+import type { PlanningDelegateSpawnFn } from './planning-delegate.js';
+
 export type FleetMode = 'scoped' | 'all';
 
 export type SmartRouterCommand =

package/.pi/extensions/smart-router/utils.ts

@@ -4,9 +4,11 @@ import {
   createResilientStore,
   SqliteStore,
   SqliteStoreError,
-} from '../../../src/infrastructure/persistence/sqlite-store.js';
-import type { StorePort } from '../../../src/domain/types/store-port.js';
-import type { RateLimitPort } from '../../../src/infrastructure/gateway/gateway-dispatch.js';
+} from '../../../src/index.js';
+import type {
+  StorePort,
+  RateLimitPort,
+} from '../../../src/index.js';
 
 export const DEFAULT_ROUTER_STATE_DB_PATH = '.pi-smart-router/state.db';
 export const DEFAULT_RATE_LIMIT_MAX_TOKENS = 60;

package/README.md

@@ -290,7 +290,7 @@ These behaviors run in `.pi/extensions/smart-router/` and have **no equivalent i
 ### Recommended integration path
 
 - **pi users:** install the **extension** (`pi install npm:pi-smart-router`). It is the full product — everything in the table above works out of the box, including failover, delegate spawn, headroom escalation, and quota reaction.
-- **npm embedders:** you get the **routing core** (12-stage pipeline, fleet mapping, telemetry, gateway health tracking, failover *selection*). Plan to implement your own stream delegation, failover iteration, headroom checks, and planning-delegate spawn around the decisions the pipeline returns — or track [#149](https://github.com/beettlle/pi-smart-router/issues/149) (**extension public facade**), the migration plan for exposing the extension's stream/delegation surface as supported library API so this gap closes over time. Until #149 lands, the extension modules also import `src/**` internals directly, so deep imports into `src/` are not a stable API.
+- **npm embedders:** you get the **routing core** (12-stage pipeline, fleet mapping, telemetry, gateway health tracking, failover *selection*). Plan to implement your own stream delegation, failover iteration, headroom checks, and planning-delegate spawn around the decisions the pipeline returns — or track [#149](https://github.com/beettlle/pi-smart-router/issues/149) (**extension public facade**), the migration plan for exposing the extension's stream/delegation surface as supported library API so this gap closes over time. Until #149 lands, the extension modules also import `src/**` internals directly, so deep imports into `src/` are not a stable API. See [docs/extension-package-boundary.md](docs/extension-package-boundary.md) for the facade vs internal-API boundary, the deep-import lint guard, and the extension coverage gate.
 
 ```text
 pi extension path (full product)        npm library path (routing core)
@@ -972,6 +972,32 @@ npm run benchmark:encoder
 
 The script reports p50/p95 latency for each encoder and asserts Granite p50/p95 stay within the 120 ms budget ceiling. Requires `@huggingface/transformers` and a one-time ONNX artifact download.
 
+#### Supply-chain: artifact pins, offline cache, and audit posture
+
+**Digest pinning (SP-259, [#147](https://github.com/beettlle/pi-smart-router/issues/147)).** The embedder verifies cached ONNX artifacts against SHA-256 pins before they are used. Pins live in [`config/onnx-artifact-pins.json`](config/onnx-artifact-pins.json) (`pins[modelId][cacheRelativePath] = sha256`; digests are the HuggingFace LFS oids for the default quantized artifacts). Pin mode is controlled by `SMART_ROUTER_ONNX_PIN_MODE`:
+
+| Mode | Behavior |
+|------|----------|
+| `off` (default) | No verification — first run downloads unpinned (local dogfood preserved). |
+| `verify` | Configured pins are verified after load; models without pins still download unpinned. |
+| `enforce` | CI/prod: pins are **required** for the loaded model — missing pin file, missing pins for the model, missing cached artifact, or any digest mismatch all fail closed. |
+
+Override the pin file location with `SMART_ROUTER_ONNX_PIN_FILE`. Verification runs **after** the transformers.js pipeline loads but **before** the embedder is returned, so even a first-run anonymous download is checked against configured pins — tampered or unexpected bytes fail closed and the session is never usable. Anonymous fetch does not silently bypass pins when they are configured. When upgrading model revisions, re-fetch digests from the HuggingFace API out-of-band and update the pin file; never pin a digest you have not verified.
+
+**Offline / air-gapped cache warm.** The artifact cache (`hydra.artifact_cache_path`, default `.pi-smart-router/models/`) is fully self-contained once warmed:
+
+1. On a networked host, warm the cache with the encoder you deploy — run any routed request, or `npm run benchmark:encoder -- --cache .pi-smart-router/models/`.
+2. Enable pin mode (`verify` or `enforce`) during the warm so digest mismatches surface on the networked host, before rollout.
+3. Copy the cache directory (and `config/onnx-artifact-pins.json` when pinning) to the offline host and point `hydra.artifact_cache_path` at the copy.
+4. Defense in depth: embedders can set `env.allowRemoteModels = false` (from `@huggingface/transformers`) before routing to forbid any network fetch, so no anonymous download path exists in production.
+
+**`npm audit` posture for the transformers chain.** The audit baseline includes high-severity advisories in `@huggingface/transformers` → `onnxruntime-node` → `adm-zip` ([GHSA-xcpc-8h2w-3j85](https://github.com/advisories/GHSA-xcpc-8h2w-3j85) — crafted ZIP triggers a 4GB memory allocation) and `sharp` (libvips CVEs), both **with no upstream fix available**. Accepted-risk rationale:
+
+- Model bytes in the pinned production path come only from the operator-controlled local cache, verified by SHA-256 — the vulnerable archive-decompression path is not exposed to untrusted input there.
+- Inference runs locally with no gradients and no untrusted deserialization; untrusted bytes enter only on first cache warm, over TLS from the HuggingFace hub, and (with pin mode on) are digest-checked before use.
+
+**Monitoring policy:** run `npm audit` at each release and record the baseline. A *new* high-severity advisory in the transformers/onnxruntime chain requires a documented exception with rationale (release notes or a linked issue) — never silently dismiss; exceptions without rationale are release blockers.
+
 ## Architecture
 
 ### Three execution tiers
@@ -1102,7 +1128,7 @@ Contributors must run `npm run build` before publishing or consuming the library
 | `npm run verify:ci` | Full CI parity: build, typecheck, lint, test, coverage (baseline PR gate; see [PR and pre-release quality gate set](#pr-and-pre-release-quality-gate-set)) |
 | `npm run typecheck` | TypeScript strict mode check (`tsc --noEmit`) |
 | `npm test` | Run test suite (`vitest run`) |
-| `npm run coverage:check` | Tests with line-coverage thresholds |
+| `npm run coverage:check` | Tests with line-coverage thresholds (src + extension, 80% floor — see [docs/extension-package-boundary.md](docs/extension-package-boundary.md#extension-coverage-gate-144)) |
 | `npm run lint` | ESLint + fleet catalog validation |
 | `npm run routing:bootstrap-centroids` | Regenerate `config/routing-centroids.json` from cluster catalog |
 | `npm run routing:calibration-aggregate` | Aggregate community telemetry for calibration |

package/config/benchmark-profiles.json

@@ -7,8 +7,8 @@
       "livecodebench": "https://livecodebench.github.io/leaderboard.html",
       "bfcl": "https://gorilla.cs.berkeley.edu/leaderboard.html"
     },
-    "scrape_date": "2026-09-03",
-    "catalog_freeze_date": "2026-09-03"
+    "scrape_date": "2026-09-05",
+    "catalog_freeze_date": "2026-09-05"
   },
   "aliases": {
     "anthropic/claude-opus-4": "claude-opus-4-5",

package/config/onnx-artifact-pins.json

@@ -0,0 +1,18 @@
+{
+  "_documentation": {
+    "purpose": "SP-259 (#147) — SHA-256 digest pins for ONNX embedding artifacts loaded by src/domain/matching/embedding-provider.ts. Verified on load when pin mode is enabled; mismatch or missing pinned artifact fails closed.",
+    "activation": "Set SMART_ROUTER_ONNX_PIN_MODE=verify (verify configured pins; unpinned models still download) or =enforce (CI/prod — pins REQUIRED for the loaded model; missing pin file, missing pins, missing cached artifact, or any mismatch fails closed). Default is off (unpinned local dogfood preserved). Override this file path with SMART_ROUTER_ONNX_PIN_FILE.",
+    "format": "pins[modelId][cacheRelativePath] = lowercase hex SHA-256. Paths are relative to the model directory inside the transformers.js cache (hydra.artifact_cache_path): <cache>/<modelId>/<path> (hub-style models--org--name/snapshots/<rev>/ layout also supported).",
+    "digest_source": "Digests are HuggingFace LFS oids (= SHA-256 of file content) from https://huggingface.co/api/models/<modelId>/tree/main/onnx, fetched 2026-09-05. onnx/model_quantized.onnx is the default q8 artifact transformers.js loads for feature-extraction.",
+    "refresh": "Re-fetch digests from the HF API when upgrading model revisions; never pin digests you have not verified out-of-band."
+  },
+  "version": 1,
+  "pins": {
+    "Xenova/all-MiniLM-L6-v2": {
+      "onnx/model_quantized.onnx": "afdb6f1a0e45b715d0bb9b11772f032c399babd23bfc31fed1c170afc848bdb1"
+    },
+    "onnx-community/granite-embedding-97m-multilingual-r2-ONNX": {
+      "onnx/model_quantized.onnx": "704c1ebca5fbb7cd83ced41827658ac4c9990c64f7f2874d22b78044e5022e22"
+    }
+  }
+}

package/config/operator-config.json.example

@@ -22,6 +22,7 @@
     "artifact_cache_path": ".pi-smart-router/models/",
     "encoder": "minilm",
     "hydra_heads": "learned_projection",
+    "_onnx_artifact_pins_documentation": "SP-259 (#147) — ONNX artifact supply-chain pinning. Digests live in config/onnx-artifact-pins.json (SHA-256 per cached artifact). Enable with env SMART_ROUTER_ONNX_PIN_MODE=verify (verify configured pins; unpinned models still download) or =enforce (CI/prod: pins required for the loaded model — missing pin file, missing pins, missing cached artifact, or any digest mismatch fails closed). Default off preserves first-run unpinned dogfood downloads. Override pin file path with SMART_ROUTER_ONNX_PIN_FILE. See README 'HyDRA model cache → Supply-chain' for offline cache warm and audit posture.",
     "_hydra_heads_documentation": {
       "learned_projection": "Default — SP-115 384×3 linear projection on MiniLM/Granite embeddings (config/hydra-projection-weights.json). Approximates HyDRA K sigmoid heads; keep until calibration Top-1 error exceeds ~10%.",
       "modernbert_k4": "ModernBERT-base [CLS] with K=4 independent sigmoid heads (config/modernbert-k4-heads.json). Migrating from SP-115: train K=4 head weights offline, set hydra_heads to modernbert_k4, and remove or ignore hydra-projection-weights.json. The fourth debugging dimension is predicted for HyDRA fidelity but excluded from the catalog-decoupled shortfall gate (reasoning, code_gen, tool_use only). See docs/routing-roadmap.md §2 P3 and GitHub #81."

package/dist/domain/matching/embedding-provider.d.ts

@@ -18,6 +18,43 @@ export interface TextEmbedder {
     embed(text: string): Promise<Float32Array>;
     dispose(): Promise<void>;
 }
+/**
+ * Artifact pin verification mode:
+ * - `off` — no verification (default; preserves unpinned local dogfood downloads)
+ * - `verify` — verify cached artifacts when pins exist for the model; fail
+ *   closed on digest mismatch or missing cached artifact. Models without pins
+ *   remain unpinned (first-run download allowed).
+ * - `enforce` — CI/prod mode: pins are REQUIRED for the model; fail closed when
+ *   the pin file is missing/unparseable, the model has no pins, a pinned
+ *   artifact is missing from the cache, or any digest mismatches.
+ */
+export type OnnxArtifactPinMode = 'off' | 'verify' | 'enforce';
+export declare const ONNX_ARTIFACT_PIN_MODES: readonly OnnxArtifactPinMode[];
+/** Default pin file (relative to process CWD). Override via options or env. */
+export declare const DEFAULT_ONNX_PIN_FILE = "config/onnx-artifact-pins.json";
+/** Env vars (operator wiring; schemas/hydra-matcher out of SP-259 scope). */
+export declare const ONNX_PIN_MODE_ENV = "SMART_ROUTER_ONNX_PIN_MODE";
+export declare const ONNX_PIN_FILE_ENV = "SMART_ROUTER_ONNX_PIN_FILE";
+/** Pin file shape: per-model map of cache-relative file path → SHA-256 hex. */
+export interface OnnxArtifactPinFile {
+    readonly version: number;
+    readonly pins: Record<string, Record<string, string>>;
+}
+export interface OnnxPinOptions {
+    /** Pin mode. Default: $SMART_ROUTER_ONNX_PIN_MODE, else 'off'. */
+    readonly pinMode?: OnnxArtifactPinMode;
+    /** Pin file path. Default: $SMART_ROUTER_ONNX_PIN_FILE, else DEFAULT_ONNX_PIN_FILE. */
+    readonly pinFilePath?: string;
+}
+/**
+ * Verify cached ONNX artifacts for `modelId` against configured SHA-256 pins.
+ * Fails closed on digest mismatch or missing pinned artifact; in `enforce`
+ * mode also fails when the pin file or model pins are missing.
+ *
+ * Runs after pipeline load so first-run downloads are verified before the
+ * embedder is returned; a mismatching session is never usable.
+ */
+export declare function verifyOnnxArtifactPins(modelId: string, cachePath: string, options?: OnnxPinOptions): Promise<void>;
 /**
  * Creates a TextEmbedder backed by @huggingface/transformers ONNX runtime.
  * Model: Xenova/all-MiniLM-L6-v2 (384-dim).
@@ -25,12 +62,12 @@ export interface TextEmbedder {
  * The package is loaded dynamically — not required at compile time.
  * Install: `npm i @huggingface/transformers`
  */
-export declare function createOnnxTextEmbedder(artifactCachePath: string): Promise<TextEmbedder>;
+export declare function createOnnxTextEmbedder(artifactCachePath: string, pinOptions?: OnnxPinOptions): Promise<TextEmbedder>;
 /**
  * Granite 97M long-context embedder (384-dim ONNX drop-in for SP-115 head).
  * Model: ibm-granite/granite-embedding-97m-multilingual-r2 via ONNX runtime.
  */
-export declare function createGraniteOnnxTextEmbedder(artifactCachePath: string): Promise<TextEmbedder>;
+export declare function createGraniteOnnxTextEmbedder(artifactCachePath: string, pinOptions?: OnnxPinOptions): Promise<TextEmbedder>;
 /** Select ONNX text embedder by operator encoder flag. */
-export declare function createTextEmbedder(encoder: Encoder | undefined, artifactCachePath: string): Promise<TextEmbedder>;
+export declare function createTextEmbedder(encoder: Encoder | undefined, artifactCachePath: string, pinOptions?: OnnxPinOptions): Promise<TextEmbedder>;
 //# sourceMappingURL=embedding-provider.d.ts.map

package/dist/domain/matching/embedding-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/domain/matching/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,8DAC8B,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA+DD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,0DAA0D;AAC1D,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,YAAkB,EAClC,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,YAAY,CAAC,CAWvB"}
+{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/domain/matching/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAGnD,eAAO,MAAM,aAAa,MAAM,CAAC;AAEjC,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,kBAAkB,8DAC8B,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAID;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,eAAO,MAAM,uBAAuB,EAAE,SAAS,mBAAmB,EAIjE,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,mCAAmC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,+BAA+B,CAAC;AAE9D,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC,uFAAuF;IACvF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AA6FD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC,CAuCf;AA0GD;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,iBAAiB,EAAE,MAAM,EACzB,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,iBAAiB,EAAE,MAAM,EACzB,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,YAAY,CAAC,CAEvB;AAED,0DAA0D;AAC1D,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,YAAkB,EAClC,iBAAiB,EAAE,MAAM,EACzB,UAAU,CAAC,EAAE,cAAc,GAC1B,OAAO,CAAC,YAAY,CAAC,CAWvB"}