@hesohq/node 0.5.0-dev.81 → 0.5.0-dev.95

package/index.d.ts

@@ -71,6 +71,73 @@ export interface RedactCommitResult {
 export declare function verify(receiptBytes: Buffer | Uint8Array | string): ActionVerdict
 /** Verify a receipt AND report its trusted-time status separately. */
 export declare function verifyWithTime(receiptBytesInput: Buffer | Uint8Array | string): ActionVerdictWithTime
+/**
+ * The base verdict + the rendered signed metrics + the offline-recomputed cost.
+ *
+ * `verdict` / `trustLevel` are exactly what [`verify`] returns. The metric fields
+ * are the SIGNED values (the closed `status` / `token_source` enums rendered to
+ * their wire snake_case strings). `recomputedCostMicros` / `costDisplay` are
+ * RECOMPUTED from the rate card the caller passed in — `priced == false` (and
+ * both absent) when that card does not price the model; never a guessed figure.
+ * `cardIdMatches` tells the reader whether the card handed in is the one the
+ * receipt actually named.
+ */
+export interface MetricsVerdict {
+  /** The base `ActionOutcome` verdict tag (`"Valid"`, `"HashMismatch"`, …). */
+  verdict: string
+  /** The re-derived trust level (`"L0"`/`"L1"`); `""` unless `verdict == "Valid"`. */
+  trustLevel: string
+  /** Whether the receipt carried a signed `metrics` block. */
+  hasMetrics: boolean
+  /** Wall-clock duration in whole milliseconds. */
+  durationMs?: number
+  /** Execution-outcome class, wire snake_case (`"ok"`, `"server_error"`, …). */
+  status?: string
+  /** Transport status code, when one applied. */
+  statusCode?: number
+  /** Provider-reported (or estimated) input tokens. */
+  tokensIn?: number
+  /** Provider-reported (or estimated) output tokens. */
+  tokensOut?: number
+  /** Token-count source, wire snake_case (`"provider_reported"`/`"estimated"`). */
+  tokenSource?: string
+  /** Request bytes sent, when the transport exposed it. */
+  bytesIn?: number
+  /** Response bytes received, when the transport exposed it. */
+  bytesOut?: number
+  /** Transport-level retries before this outcome. */
+  retries?: number
+  /** The rate-card id AS NAMED in the signed receipt. */
+  rateCardId?: string
+  /** The `provider/model` key derived from the signed `action.fields`. */
+  modelKey?: string
+  /** Recomputed cost in micro-USD (`BigInt`); absent when not priced. */
+  recomputedCostMicros?: bigint
+  /** Recomputed cost as a 6-decimal display string; absent when not priced. */
+  costDisplay?: string
+  /** `true` iff the model is priced by the passed-in card. */
+  priced: boolean
+  /** Whether the passed-in card is the one the receipt named. */
+  cardIdMatches: boolean
+}
+/**
+ * Verify a single `ActionReceipt` AND render its signed metrics + recompute cost
+ * from the passed-in public rate card — the node mirror of the WASM
+ * `verifyActionReceiptWithRates`.
+ *
+ * Runs the EXISTING offline verify for the base outcome + trust level (so that
+ * path is unchanged), then renders the signed metrics and recomputes the cost via
+ * the SHARED `heso_action::metrics_view` glue. Never throws on a malformed receipt
+ * or card — those degrade to `has_metrics: false` / `priced: false` exactly as the
+ * WASM export does. The cost render is purely informational and NEVER masks a
+ * verify failure: a tampered metric flips the `action_hash`, so `verdict` is a
+ * non-`Valid` tag while the (meaningless) recompute still reflects whatever bytes
+ * are present — the caller branches on `verdict`, never the dollar figure.
+ *
+ * `receipt_bytes`   — the raw `ActionReceipt` JSON bytes (Buffer/Uint8Array/string).
+ * `rate_card_json`  — the public rate-card JSON the cost is recomputed from.
+ */
+export declare function verifyWithRates(receiptBytes: Buffer | Uint8Array | string, rateCardJson: string): MetricsVerdict
 /**
  * Verify a receipt AND re-derive its ERT classification from the embedded taxonomy
  * (heso-engine's ClassifyReDeriver). Only available when `process` is enabled.
@@ -361,6 +428,44 @@ export declare function assembleL1FromParts(suspendedContentJson: string, approv
  * wasm-reachable).
  */
 export declare function assembleQuorumFromParts(suspendedContentJson: string, threshold: number, rosterJson: string, partsJson: string, projectRoot: string, keyPassphrase?: string | undefined | null, chainHead?: string | undefined | null): Buffer
+/**
+ * Suspend a gated action: mint the signed `suspended` chain link and return the
+ * raw resume token (returned ONCE) plus the action spec hash. Mirrors the PyO3
+ * `process_suspend` body 1:1 — the ProcessInput MUST carry `reclassify=false` so
+ * the descriptor is signed verbatim and stays byte-stable across the lifecycle.
+ *
+ * Returns JSON bytes:
+ * `{"session_id": str, "resume_token": str, "action_spec": str, "chain_path": str}`.
+ */
+export declare function processSuspend(processInputJson: Buffer | Uint8Array | string, projectRoot: string, sessionId: string, sla: string, expiresAt: string, onTimeout: string, contextScheme: string, contextBlob: Buffer, toolVersionHash?: string | undefined | null): Buffer
+/**
+ * Resume a suspended session: re-read the chain, apply the decision, fire-or-replay.
+ * Mirrors the PyO3 `process_resume` body 1:1. On `Fire` it mints + appends the
+ * `completed` link under `ACTION_SIGNING_DOMAIN` and advances the cursor.
+ *
+ * Returns JSON bytes `{"decision": str, "committed": bool, "kind"?: str,
+ * "reason"?: str}` where `decision` is one of
+ * `fire`/`replay`/`pending`/`terminal`/`uncertain`/`refused`.
+ */
+export declare function processResume(processInputJson: Buffer | Uint8Array | string, projectRoot: string, sessionId: string, presentedToken: string, contextBlob: Buffer): Buffer
+/**
+ * Append an approver/ledger-signed decision link to a session's chain. Mirrors the
+ * PyO3 `process_append_decision` body 1:1.
+ *
+ * `kind`: one of `"approved"` / `"denied"` / `"escalated"` / `"expired"`. **Fails
+ * closed** without a `decision.key` unless [`INSECURE_DECISION_KEY_ENV`] is set
+ * (see `load_decision_signer`) — the approver key is cloud-custodied in prod.
+ */
+export declare function processAppendDecision(projectRoot: string, sessionId: string, kind: string, reason?: string | undefined | null, decidedAt?: string | undefined | null): void
+/**
+ * Read the current lifecycle state of a session chain (the head link's kind).
+ * Mirrors the PyO3 `process_read_chain_head` body 1:1.
+ *
+ * Returns the head kind as a lowercase string (`"suspended"` / `"approved"` /
+ * `"denied"` / `"expired"` / `"completed"` / `"escalated"`), or `None` if no chain
+ * exists yet.
+ */
+export declare function processReadChainHead(projectRoot: string, sessionId: string): string | null
 /** A loaded operator key, exposing just the public-key surface. */
 export declare class OperatorKey {
   /** Return the base64 standard-alphabet public key. */

package/index.js

@@ -310,11 +310,12 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { OperatorKey, verify, verifyWithTime, verifyRederiving, actionCanonicalBytesJs, l1ContentCanonicalBytesJs, contentHash, anchoredContentHashJs, shortHash, chainHashHex, verifyApprovalToken, verifyDelegation, verifyCommitment, commitmentEnvelopeCanonicalBytes, commitmentFingerprint, signerFingerprint, bindIntoChainJs, verifyChain, verifySessionChainJs, verifySessionChainWithRotationJs, verifyInclusionJs, verifyConsistencyJs, verifyAuditChain, taxonomyHash, classify, isDestructive, redactDestructiveJs, redactCommitJs, verifyRevealJs, keyFromSeed, generateKey, blake3Hex, processAction, assembleL1FromParts, assembleQuorumFromParts } = nativeBinding
+const { OperatorKey, verify, verifyWithTime, verifyWithRates, verifyRederiving, actionCanonicalBytesJs, l1ContentCanonicalBytesJs, contentHash, anchoredContentHashJs, shortHash, chainHashHex, verifyApprovalToken, verifyDelegation, verifyCommitment, commitmentEnvelopeCanonicalBytes, commitmentFingerprint, signerFingerprint, bindIntoChainJs, verifyChain, verifySessionChainJs, verifySessionChainWithRotationJs, verifyInclusionJs, verifyConsistencyJs, verifyAuditChain, taxonomyHash, classify, isDestructive, redactDestructiveJs, redactCommitJs, verifyRevealJs, keyFromSeed, generateKey, blake3Hex, processAction, assembleL1FromParts, assembleQuorumFromParts, processSuspend, processResume, processAppendDecision, processReadChainHead } = nativeBinding
 
 module.exports.OperatorKey = OperatorKey
 module.exports.verify = verify
 module.exports.verifyWithTime = verifyWithTime
+module.exports.verifyWithRates = verifyWithRates
 module.exports.verifyRederiving = verifyRederiving
 module.exports.actionCanonicalBytesJs = actionCanonicalBytesJs
 module.exports.l1ContentCanonicalBytesJs = l1ContentCanonicalBytesJs
@@ -347,3 +348,7 @@ module.exports.blake3Hex = blake3Hex
 module.exports.processAction = processAction
 module.exports.assembleL1FromParts = assembleL1FromParts
 module.exports.assembleQuorumFromParts = assembleQuorumFromParts
+module.exports.processSuspend = processSuspend
+module.exports.processResume = processResume
+module.exports.processAppendDecision = processAppendDecision
+module.exports.processReadChainHead = processReadChainHead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hesohq/node",
-  "version": "0.5.0-dev.81",
+  "version": "0.5.0-dev.95",
   "description": "napi-rs native Node.js addon for the HESO Enterprise trust layer",
   "main": "index.js",
   "types": "index.d.ts",
@@ -34,10 +34,10 @@
   },
   "license": "LicenseRef-Proprietary",
   "optionalDependencies": {
-    "@hesohq/node-darwin-arm64": "0.5.0-dev.81",
-    "@hesohq/node-darwin-x64": "0.5.0-dev.81",
-    "@hesohq/node-linux-arm64-gnu": "0.5.0-dev.81",
-    "@hesohq/node-linux-x64-gnu": "0.5.0-dev.81",
-    "@hesohq/node-win32-x64-msvc": "0.5.0-dev.81"
+    "@hesohq/node-darwin-arm64": "0.5.0-dev.95",
+    "@hesohq/node-darwin-x64": "0.5.0-dev.95",
+    "@hesohq/node-linux-arm64-gnu": "0.5.0-dev.95",
+    "@hesohq/node-linux-x64-gnu": "0.5.0-dev.95",
+    "@hesohq/node-win32-x64-msvc": "0.5.0-dev.95"
   }
 }