@opengeni/core 3.0.1 → 3.1.2

package/dist/billing/model-usage-settlement.d.ts

@@ -0,0 +1,112 @@
+import { type Settings } from "@opengeni/config";
+import type { LatencyMode } from "@opengeni/contracts";
+import type { InsightsUsageClassMicros } from "@opengeni/contracts/insights-usage";
+import { type Database } from "@opengeni/db";
+import type { ModelCallUsageNormalization, ModelResponseUsage } from "@opengeni/runtime";
+import type { ModelUsageInput } from "@opengeni/config";
+import { type SessionUsageLimitMetricsSink } from "../session-usage-limit-metrics.js";
+/**
+ * Price and settle one authoritative model response: the token-cap usage
+ * event, the `model.cost` event, and (for Opengeni-credit models) the
+ * idempotent credit debit. Agent turns and stateless single model calls both
+ * settle here; `sourceId` is the durable identity every idempotency key
+ * derives from, so a retried settlement never charges twice.
+ */
+export type ModelUsageBillingRecord = {
+    billingPath: "opengeni_credits" | "external";
+    /** Same quantity written to usage_events.model.cost when present; else 0. */
+    pricedCostMicros: number;
+    /** Hypothetical provider-rate USD micros; never an Opengeni charge. */
+    estimatedProviderCostMicros: number | null;
+    /** Hypothetical Opengeni credit price at the captured rate; never a debit. */
+    equivalentCreditCostMicros: number | null;
+    pricingSource: "configured_list_price" | "gateway_reported" | null;
+    /** Forward-only provider list class snapshot; older facts/events stay unknown. */
+    listByClassMicros?: InsightsUsageClassMicros | null;
+    listByClassApprox?: boolean;
+    normalizedUsage: ModelCallUsageNormalization;
+    upstreamProvider?: string;
+};
+export type ModelUsageSettlementInput = {
+    accountId: string;
+    workspaceId: string;
+    /** Product model id used for pricing and ledger attribution. */
+    model: string;
+    chargesOpenGeniCredits: boolean;
+    countsTowardTokenCap: boolean;
+    creditPolicyRevision?: number | undefined;
+    gatewayBilling?: ModelResponseUsage["gatewayBilling"];
+    normalizedUsage: ModelCallUsageNormalization;
+    /** Durable source identity (for a turn, `${turnId}:${sourceKey}`). */
+    sourceId: string;
+    sessionId?: string | null;
+    /**
+     * The session whose task usage limit this response counts against when it
+     * differs from the usage attribution `sessionId` (an attempt-authenticated
+     * single-model call keeps its existing usage attribution). Defaults to
+     * `sessionId`.
+     */
+    usageLimitSessionId?: string | null;
+    turnId?: string | null;
+    turnAttemptId?: string | null;
+    latencyMode?: LatencyMode;
+    /** Non-secret correlation fields added to the credit debit metadata. */
+    debitMetadata?: Record<string, unknown>;
+    /** Best-effort metrics hook after a committed debit. */
+    onCreditsDebited?: (result: {
+        debitedMicros: number;
+        grantDebitedMicros: number;
+    }) => void;
+    /** Content-free per-task usage limit diagnostics (closed-set labels only). */
+    usageLimitMetrics?: SessionUsageLimitMetricsSink | null;
+    /**
+     * Attempt-scoped custody for a receipt whose write failed. When present, a
+     * failed receipt write is handed over (content-free, original identity) and
+     * settlement continues, so the response is never lost or replayed; the
+     * owner must write held receipts before its next model request. Without
+     * custody the failure throws.
+     */
+    receiptCustody?: ((receipt: HeldSessionUsageReceipt, error: unknown) => void) | null;
+};
+/** A content-free task usage receipt whose write is still owed. */
+export type HeldSessionUsageReceipt = {
+    sessionId: string;
+    sourceId: string;
+    turnId: string | null;
+    amountMicros: number | null;
+    pricingSource: "configured_list_price" | "gateway_reported" | null;
+    model: string | null;
+};
+/**
+ * The per-task meter amount: the canonical pre-margin estimate, but only when
+ * the response actually reported usage. A response without token telemetry
+ * (or with zero input and output tokens) and no provider-reported cost is an
+ * unknown amount, never a known-free call. Billing and Insights keep their
+ * own `estimatedProviderCostMicros` unchanged.
+ */
+export declare function sessionUsageMeterAmountMicros(input: {
+    estimatedProviderCostMicros: number | null;
+    gatewayReported: boolean;
+    inputTokens: number | null;
+    outputTokens: number | null;
+}): number | null;
+/** The receipt table's `source_id` byte bound. */
+export declare const SESSION_USAGE_RECEIPT_SOURCE_ID_MAX_BYTES = 1100;
+/**
+ * The per-task receipt identity for a producer source. Every identity the
+ * event trigger or the legacy import can produce (`<turnId>:<sourceKey>` with
+ * a source key of at most 1024 bytes) fits the bound and is used unchanged,
+ * so their deduplication is untouched. Only a longer identity, which those
+ * paths skip, is replaced by a stable digest, so a long provider response id
+ * is recorded once instead of failing the receipt write on every retry.
+ *
+ * A source key PostgreSQL cannot store as given (NUL, a lone UTF-16
+ * surrogate, the lossless codec's own prefix) is stored by the event in its
+ * lossless encoding, and the trigger meters that encoded key. The receipt uses
+ * the same encoded key, so both writers share one identity instead of the
+ * direct write being refused.
+ */
+export declare function sessionUsageReceiptSourceId(sourceId: string, turnId?: string | null): string;
+export declare function settleModelUsage(settings: Settings, db: Database, input: ModelUsageSettlementInput): Promise<ModelUsageBillingRecord>;
+/** Bounded, validated token counts for pricing; raw provider values never price. */
+export declare function sanitizedModelUsageInput(normalized: ModelCallUsageNormalization): ModelUsageInput;

package/dist/canonical-human-identities.js

@@ -3,7 +3,7 @@ import {
   getManagedAuthRequestActorLeaseStamp,
   getManagedSession,
   markManagedAuthRequestActorTransitionApplied
-} from "./chunk-OF65T3PM.js";
+} from "./chunk-TTWTXQB2.js";
 import "./chunk-QO5GVFFO.js";
 
 // src/canonical-human-identities.ts

package/dist/{chunk-VCZFFEPB.js → chunk-7T2SZ7BI.js}

@@ -1206,6 +1206,17 @@ var EditableArtifactService = class {
     }
     const intentBytes = request.intentBytes.slice();
     const actorKey = editableArtifactActorKey(context.actor);
+    if (input.authorizeCommit) {
+      return await this.applyTransactionOptimistically({
+        context,
+        actorKey,
+        request,
+        intent,
+        intentBytes,
+        authorizationRevision,
+        authorizeCommit: input.authorizeCommit
+      });
+    }
     const inFlightKey = transactionInFlightKey(
       context.scope,
       context.artifactId,
@@ -1260,7 +1271,8 @@ var EditableArtifactService = class {
           actorKey,
           clientTransactionId: intent.clientTransactionId,
           previousLocalTransactionId: intent.previousLocalTransactionId,
-          selectiveUndoOperationIds: intent.selectiveUndoOperationIds
+          selectiveUndoOperationIds: intent.selectiveUndoOperationIds,
+          ...input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {}
         }
       );
       if (basisRead.kind === "existing") {
@@ -1400,6 +1412,7 @@ var EditableArtifactService = class {
           expectedLifecycle: "active",
           expectedAuthorizationRevision: authorizationRevision,
           authorizationActor: context.actor,
+          ...input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {},
           expectedHeadSequence: artifact.headSequence,
           actorKey,
           clientTransactionId: intent.clientTransactionId,
@@ -1616,6 +1629,7 @@ var EditableArtifactService = class {
         expectedLifecycle: "active",
         expectedAuthorizationRevision: authorizationRevision,
         authorizationActor: context.actor,
+        ...input.authorizeCommit ? { authorizeCommit: input.authorizeCommit } : {},
         expectedHeadSequence: artifact.headSequence,
         actorKey,
         clientTransactionId: intent.clientTransactionId,
@@ -2722,4 +2736,4 @@ export {
   EDITABLE_ARTIFACT_COMPACTION_BYTE_THRESHOLD,
   EditableArtifactService
 };
-//# sourceMappingURL=chunk-VCZFFEPB.js.map
+//# sourceMappingURL=chunk-7T2SZ7BI.js.map