feat: dfs settlement os v4.0.0 + companion packages v1.0.0

.github/workflows/ci.yml

@@ -23,7 +23,11 @@ jobs:
       - run: npm run lint
       - run: npm run format:check
       - run: npm test
+      - run: npm run test:coverage
       - run: npm run build
       - run: npm run docs
+      - run: npm run smoke:exports
+      - run: npm run size:check
       - run: npm run pack:smoke
       - run: npm run bench
+      - run: npm run audit:high

README.md

@@ -7,7 +7,7 @@ Monorepo for the Buzzr DFS settlement packages.
 | Package | Purpose |
 |---|---|
 | `@buzzr/bets-core` | Pure Buzzr Bets domain contracts, sportsbook normalization, odds/edge math, ROI rollups, and settlement adapters. |
-| `@buzzr/dfs-engine` | Core zero-runtime-dependency settlement engine, grading math, v3 book policy registry, adapters, and compatibility exports. |
+| `@buzzr/dfs-engine` | Core zero-runtime-dependency settlement engine, grading math, strict v4 book policy registry, adapters, and validation exports. |
 | `@buzzr/dfs-provider-espn` | Optional provider contract package for wiring ESPN-shaped gamelog data into the engine. |
 | `@buzzr/dfs-testkit` | Golden fixture builders, mock providers, and contract helpers for consumers and Buzzr app tests. |
 

package.json

@@ -29,14 +29,14 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
-    "@types/node": "^22.19.18",
-    "@vitest/coverage-v8": "^4.1.6",
-    "eslint": "^10.3.0",
+    "@types/node": "^22.19.19",
+    "@vitest/coverage-v8": "^4.1.7",
+    "eslint": "^10.4.0",
     "prettier": "^3.8.3",
     "tsup": "^8.5.1",
     "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.59.2",
-    "vitest": "^4.1.6"
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.7"
   }
 }

packages/bets-core/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @buzzr/bets-core
+
+## 4.0.0
+
+### Major Changes
+
+- 07fc4c7: Harden DFS Settlement OS v4 with canonical settlement inputs, structured validation, typed definition and invariant errors, stricter provider/payout contracts, and cross-package v4 fixture/adaptor updates.

packages/bets-core/README.md

@@ -6,7 +6,9 @@ This package intentionally contains no React, no native modules, no Supabase
 client, no network calls, and no credentials. It is the app-facing domain layer
 for sportsbook normalization, external bet keys, no-vig fair-line math, ROI
 rollups, and converting tracked bet records into settlement inputs shaped for
-`@buzzr/dfs-engine`.
+`@buzzr/dfs-engine`. The DFS adapter emits v4-canonical settlement legs
+(`actual` and `status`, never legacy `stat` / `legStatus`) and rejects
+non-finite money or line values before they hit the engine.
 
 The package has zero runtime dependencies. Consumers can install
 `@buzzr/dfs-engine` when they want to pass the adapter output directly into the

packages/bets-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buzzr/bets-core",
-  "version": "3.0.1",
+  "version": "4.0.0",
   "description": "Pure Buzzr Bets domain contracts, odds math, ROI rollups, and settlement adapters.",
   "license": "MIT",
   "author": "Sarvesh Chidambaram",

packages/bets-core/src/index.ts

@@ -21,9 +21,8 @@ export type DfsLegInput = {
   propType: string;
   line: number;
   direction: 'over' | 'under';
-  stat?: number | null;
+  actual?: number | null;
   status?: DfsLegOutcome | null;
-  legStatus?: DfsLegOutcome | null;
   providerData?: Record<string, unknown> | null;
   metadata?: Record<string, unknown>;
 };
@@ -373,7 +372,14 @@ export function betRecordToDfsEntryInput(
 
   const displayedMultiplier =
     options.displayedMultiplier ?? bet.dfs?.displayedMultiplier ?? inferDisplayedMultiplier(bet);
-  assertFiniteNumber(displayedMultiplier, 'displayedMultiplier');
+  assertPositiveNumber(bet.stake, 'stake');
+  assertPositiveNumber(displayedMultiplier, 'displayedMultiplier');
+  if (bet.dfs?.baseMultiplier != null) {
+    assertPositiveNumber(bet.dfs.baseMultiplier, 'baseMultiplier');
+  }
+  if (bet.dfs?.profitBoostPct != null) {
+    assertNonNegativeNumber(bet.dfs.profitBoostPct, 'profitBoostPct');
+  }
 
   return {
     entryId: options.entryId ?? bet.id,
@@ -401,6 +407,10 @@ function toDfsLegInput(leg: BetLeg): DfsLegInput {
   if (leg.line == null) {
     throw new Error(`betRecordToDfsEntryInput: ${leg.legId} line is required`);
   }
+  assertFiniteNumber(leg.line, `${leg.legId}.line`);
+  if (leg.actual != null) {
+    assertFiniteNumber(leg.actual, `${leg.legId}.actual`);
+  }
 
   const direction = leg.direction ?? directionFromSide(leg.side);
   if (!direction) {
@@ -417,8 +427,8 @@ function toDfsLegInput(leg: BetLeg): DfsLegInput {
     propType: leg.propType,
     line: leg.line,
     direction,
-    stat: leg.actual ?? null,
-    legStatus: leg.status ?? null,
+    actual: leg.actual ?? null,
+    status: leg.status ?? null,
   };
 }
 
@@ -486,6 +496,20 @@ function assertFiniteNumber(value: number, label: string): void {
   }
 }
 
+function assertPositiveNumber(value: number, label: string): void {
+  assertFiniteNumber(value, label);
+  if (value <= 0) {
+    throw new Error(`${label} must be a positive number`);
+  }
+}
+
+function assertNonNegativeNumber(value: number, label: string): void {
+  assertFiniteNumber(value, label);
+  if (value < 0) {
+    throw new Error(`${label} must be a non-negative number`);
+  }
+}
+
 function assertProbability(value: number, label: string): void {
   assertFiniteNumber(value, label);
   if (value <= 0 || value >= 1) {

packages/bets-core/tests/bets-core.test.ts

@@ -173,7 +173,8 @@ describe('@buzzr/bets-core', () => {
           propType: 'Points',
           line: 20.5,
           direction: 'over',
-          stat: 24,
+          actual: 24,
+          status: null,
         },
         {
           legId: 'leg-2',
@@ -182,6 +183,8 @@ describe('@buzzr/bets-core', () => {
         },
       ],
     });
+    expect(betRecordToDfsEntryInput(baseBet()).legs[0]).not.toHaveProperty('stat');
+    expect(betRecordToDfsEntryInput(baseBet()).legs[0]).not.toHaveProperty('legStatus');
 
     expect(
       betRecordToDfsEntryInput(
@@ -237,5 +240,24 @@ describe('@buzzr/bets-core', () => {
         }),
       ),
     ).toThrow('direction is required');
+    expect(() => betRecordToDfsEntryInput(baseBet({ stake: 0 }))).toThrow(
+      'stake must be a positive number',
+    );
+    expect(() =>
+      betRecordToDfsEntryInput(
+        baseBet({
+          legs: [
+            {
+              legId: 'bad-line',
+              playerName: 'C. Example',
+              league: 'NBA',
+              propType: 'Assists',
+              line: Number.NaN,
+              side: 'under',
+            },
+          ],
+        }),
+      ),
+    ).toThrow('bad-line.line must be a finite number');
   });
 });

packages/dfs-cli/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @buzzr/dfs-cli
+
+## 1.0.0
+
+### Major Changes
+
+- Graduate v4-aligned companion packages to 1.0.0: CLI wrapper, Sportradar stat-provider adapter, framework-agnostic display helpers, and canonical settlement test vectors. All four ship pinned against `@buzzr/dfs-engine@^4.0.0` and follow Settlement OS v4 strict contracts.
+
+### Patch Changes
+
+- Updated dependencies [07fc4c7]
+  - @buzzr/dfs-engine@4.0.0

packages/dfs-cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarvesh Chidambaram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/dfs-cli/README.md

@@ -0,0 +1,35 @@
+# @buzzr/dfs-cli
+
+Command-line wrapper around [`@buzzr/dfs-engine`](https://www.npmjs.com/package/@buzzr/dfs-engine).
+Grade a DFS entry from JSON fixtures without writing any TypeScript.
+
+## Install
+
+```bash
+npm install -g @buzzr/dfs-cli
+```
+
+## Usage
+
+```bash
+dfs-grade ./entry.json --gamelogs ./gamelogs.json
+```
+
+`entry.json` is a `DfsEntryInput`. `gamelogs.json` is a map of `legId` to an
+array of `PlayerGameLogEntryShape` rows. The settlement result is printed to
+stdout as pretty JSON; non-zero exit code on any error.
+
+## Programmatic API
+
+```ts
+import { runGrade } from '@buzzr/dfs-cli';
+
+const result = await runGrade({
+  entry,
+  gameLogsByLegId: { 'leg-1': [gameLogRow] },
+});
+```
+
+## License
+
+MIT

packages/dfs-cli/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@buzzr/dfs-cli",
+  "version": "1.0.0",
+  "description": "Command-line wrapper around @buzzr/dfs-engine — grade a DFS entry from JSON fixtures without writing code.",
+  "license": "MIT",
+  "author": "Sarvesh Chidambaram",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "dfs-grade": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src tests",
+    "format": "prettier --write src tests",
+    "format:check": "prettier --check src tests"
+  },
+  "keywords": [
+    "dfs",
+    "buzzr",
+    "cli",
+    "settlement",
+    "grading",
+    "prizepicks",
+    "underdog"
+  ],
+  "dependencies": {
+    "@buzzr/dfs-engine": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/dfs-cli/src/cli.ts

@@ -0,0 +1,62 @@
+import { runGradeFromFiles } from './index';
+
+type ParsedArgs = {
+  entryPath: string | null;
+  gameLogsPath: string | null;
+  showHelp: boolean;
+};
+
+function parseArgs(argv: readonly string[]): ParsedArgs {
+  const out: ParsedArgs = { entryPath: null, gameLogsPath: null, showHelp: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '-h' || arg === '--help') {
+      out.showHelp = true;
+    } else if (arg === '--gamelogs' || arg === '-g') {
+      out.gameLogsPath = argv[i + 1] ?? null;
+      i += 1;
+    } else if (!arg.startsWith('-') && !out.entryPath) {
+      out.entryPath = arg;
+    }
+  }
+  return out;
+}
+
+const HELP = `dfs-grade <entry.json> --gamelogs <gamelogs.json>
+
+  Grades a DFS entry using @buzzr/dfs-engine and prints the settlement as JSON.
+
+  <entry.json>           Path to a DfsEntryInput JSON file.
+  --gamelogs, -g <path>  Path to a JSON map of legId -> PlayerGameLogEntryShape[].
+  -h, --help             Show this help.`;
+
+export async function main(argv: readonly string[]): Promise<number> {
+  const args = parseArgs(argv);
+  if (args.showHelp || !args.entryPath || !args.gameLogsPath) {
+    process.stdout.write(`${HELP}\n`);
+    return args.showHelp ? 0 : 1;
+  }
+  try {
+    const result = await runGradeFromFiles({
+      entryPath: args.entryPath,
+      gameLogsPath: args.gameLogsPath,
+    });
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`dfs-grade: ${message}\n`);
+    return 1;
+  }
+}
+
+const isDirectInvocation =
+  typeof process !== 'undefined' &&
+  Array.isArray(process.argv) &&
+  process.argv[1] !== undefined &&
+  import.meta.url === `file://${process.argv[1]}`;
+
+if (isDirectInvocation) {
+  const code = await main(process.argv.slice(2));
+  process.exit(code);
+}

packages/dfs-cli/src/engine-shim.ts

@@ -0,0 +1,28 @@
+import {
+  createDfsEngine,
+  defineStatProvider,
+  type DfsEntryInput,
+  type DfsSettlementResult,
+  type PlayerGameLogEntryShape,
+  type StatProvider,
+} from '@buzzr/dfs-engine';
+
+export {
+  createDfsEngine,
+  type DfsEntryInput,
+  type DfsSettlementResult,
+  type PlayerGameLogEntryShape,
+  type StatProvider,
+};
+
+export function createMockStatProviderFromMap(
+  rowsByLegId: Record<string, PlayerGameLogEntryShape[]>,
+  id = 'dfs-cli-mock',
+): StatProvider {
+  return defineStatProvider({
+    id,
+    getGameLog({ leg }) {
+      return rowsByLegId[leg.legId] ?? [];
+    },
+  });
+}