@nodaro/shared 1.24.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.24.0",
+  "version": "2.0.1",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/credit-conversion.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest"
+import { CREDIT_BASE_USD } from "../model-constants.js"
+import { usdToCredits, creditsToUsd } from "../credit-conversion.js"
+
+describe("usdToCredits", () => {
+  it("converts exact multiples of the base without rounding up", () => {
+    // Stated against the constant, not a literal: this is an INVARIANT of the
+    // conversion, so it must hold at whatever CREDIT_BASE_USD currently is.
+    for (const multiple of [1, 2, 50, 500]) {
+      expect(usdToCredits(multiple * CREDIT_BASE_USD)).toBe(multiple)
+    }
+  })
+
+  it("rounds fractional cost up to a whole credit", () => {
+    expect(usdToCredits(CREDIT_BASE_USD * 1.5)).toBe(2)
+    expect(usdToCredits(CREDIT_BASE_USD / 2)).toBe(1)
+  })
+
+  it("returns 0 for zero cost", () => {
+    expect(usdToCredits(0)).toBe(0)
+  })
+
+  // The reason this helper exists rather than a bare ceil(usd / base).
+  it("absorbs IEEE-754 division noise (bare ceil would over-charge)", () => {
+    // 0.02 here is a LITERAL on purpose: it reproduces the historical bug the
+    // guard was written for (0.14 / 0.02 = 7.000000000000001, so a bare ceil
+    // charged 8 instead of 7), which stays meaningful after the base moves.
+    expect(0.14 / 0.02).toBeGreaterThan(7)
+    expect(Math.ceil(0.14 / 0.02)).toBe(8) // the bug
+    // The guard's own property: an exact multiple never rounds up, at any base.
+    for (const usd of [0.28, 0.56, 1.12, 2.22, 2.24, 4.44, 4.48, 4.94, 4.98]) {
+      expect(usdToCredits(usd)).toBe(Math.round(usd / CREDIT_BASE_USD))
+    }
+  })
+
+  it("rejects non-finite input rather than emitting NaN credits", () => {
+    expect(() => usdToCredits(Number.NaN)).toThrow(/finite/)
+    expect(() => usdToCredits(Number.POSITIVE_INFINITY)).toThrow(/finite/)
+    expect(() => usdToCredits(-0.5)).toThrow(/negative/)
+  })
+})
+
+describe("creditsToUsd", () => {
+  it("is the inverse of the base", () => {
+    expect(creditsToUsd(1)).toBeCloseTo(CREDIT_BASE_USD, 10)
+    expect(creditsToUsd(50)).toBeCloseTo(50 * CREDIT_BASE_USD, 10)
+    expect(creditsToUsd(0)).toBe(0)
+  })
+
+  it("rejects non-finite input", () => {
+    expect(() => creditsToUsd(Number.NaN)).toThrow(/finite/)
+  })
+})

package/src/__tests__/video-analysis-catalog-sync.test.ts

@@ -87,9 +87,10 @@ describe("bare video-analysis node-type credit id", () => {
       expect(credits, `${id} exceeds the bare-id ceiling ${ceiling}`).toBeLessThanOrEqual(ceiling)
     }
     // The migration writes this number; keep them in lockstep (277 wrote 200,
-    // 279 wrote 739, 280 writes 346 — every tier now dispatches one identical
-    // analyzer pass, so the whole schedule flattened and the ceiling fell with it).
-    expect(ceiling).toBe(346)
+    // 279 wrote 739, 283 wrote 346, 284 wrote 350 — `smart` owns the ceiling and
+    // gained the continuity pass — and the credit re-denomination scaled it x10
+    // to 3500, the value 288 now writes).
+    expect(ceiling).toBe(3500)
   })
 
   it("the bare id still bounds the default tier at the ceiling bucket", () => {

package/src/credit-conversion.ts

@@ -0,0 +1,39 @@
+/**
+ * The ONLY place credit⇄USD arithmetic is written.
+ *
+ * Every credit figure derives from {@link CREDIT_BASE_USD}. Dividing by a
+ * hardcoded copy of that number instead makes the base impossible to change
+ * without a multi-file hunt, so route conversions through here.
+ *
+ * MILLI-CREDIT GUARD — do not remove. `usd / base` is IEEE-754 division and
+ * lands a hair above an integer for many exact-multiple inputs
+ * (0.14 / 0.02 = 7.000000000000001), so a bare `Math.ceil` rounds up a whole
+ * credit that was not owed. Rounding to milli-credits first absorbs that noise
+ * at 1000x finer resolution than any credit-level decision.
+ *
+ * The guard matters at every base, not just the current one — a finer base does
+ * not make it unnecessary, it only moves which inputs trip it. Do not
+ * "simplify" it away if {@link CREDIT_BASE_USD} ever changes.
+ */
+import { CREDIT_BASE_USD } from "./model-constants.js"
+
+/** Milli-credits per credit — the intermediate rounding resolution. */
+export const CREDIT_ROUNDING_RESOLUTION = 1000
+
+function assertUsableUsd(usd: number): void {
+  if (!Number.isFinite(usd)) throw new Error(`usdToCredits: cost must be finite, got ${usd}`)
+  if (usd < 0) throw new Error(`usdToCredits: cost must not be negative, got ${usd}`)
+}
+
+/** A USD amount → whole credits at the current base. Rounds up. */
+export function usdToCredits(usd: number): number {
+  assertUsableUsd(usd)
+  const milliCredits = Math.round((usd / CREDIT_BASE_USD) * CREDIT_ROUNDING_RESOLUTION)
+  return Math.ceil(milliCredits / CREDIT_ROUNDING_RESOLUTION)
+}
+
+/** Whole credits → their USD value at the current base. Display/reporting only. */
+export function creditsToUsd(credits: number): number {
+  if (!Number.isFinite(credits)) throw new Error(`creditsToUsd: credits must be finite, got ${credits}`)
+  return credits * CREDIT_BASE_USD
+}

package/src/index.ts

@@ -13,6 +13,8 @@ export { DEFAULT_LABEL_BY_SOURCE } from "./types.js"
 
 export * from "./freecut-protocol.js"
 
+export { usdToCredits, creditsToUsd, CREDIT_ROUNDING_RESOLUTION } from "./credit-conversion.js"
+
 export {
   CREDIT_BASE_USD,
   IMAGE_PROMPT_MAX,