@classytic/primitives 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.16.0] - 2026-07-27
+
+### Added — `assertApproved` + `CHAIN_INCOMPLETE` (`/approval`)
+
+- **`ApprovalErrorCode` gains `'CHAIN_INCOMPLETE'`** — the single canonical
+  error code for "finalize/commit attempted before the chain reached `approved`".
+  Hosts route it through `rethrowApprovalError` to the `approval.chain_incomplete`
+  wire code so all commit/post/finalize boundaries raise the same structured error.
+- **`assertApproved(chain, message?)`** — canonical finalize-time gate: asserts
+  the chain has reached `approved`, else throws `ApprovalError('CHAIN_INCOMPLETE')`.
+  A `null`/absent chain passes (no chain required). Use at every journal-entry
+  post, PO approve, transfer dispatch, etc. to replace per-domain hand-rolled
+  divergent codes with one definition.
+
+Purely additive — no existing exports changed.
+
 ## [0.15.0] - 2026-07-25
 
 ### Added — `/retention`: `PurgeEvidence` value object

package/dist/approval.d.mts

@@ -83,7 +83,12 @@ interface CreateStepInput {
   readonly requiredApprovals?: number;
   readonly threshold?: ApprovalThreshold;
 }
-type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER';
+type ApprovalErrorCode = 'EMPTY_STEPS' | 'DUPLICATE_STEP_ID' | 'EMPTY_APPROVERS' | 'DUPLICATE_APPROVER_ID' | 'INVALID_QUORUM' | 'UNKNOWN_STEP' | 'UNAUTHORIZED_APPROVER' | 'STEP_NOT_ACTIVE' | 'STEP_ALREADY_DECIDED_BY_APPROVER'
+/** A finalize/commit was attempted while the chain has not reached
+ *  `approved` (still `pending`, or `rejected`). The single canonical
+ *  "not yet approved" gate — hosts route it through arc-approval's
+ *  `rethrowApprovalError` to the `approval.chain_incomplete` wire code. */
+| 'CHAIN_INCOMPLETE';
 declare class ApprovalError extends Error {
   readonly name = "ApprovalError";
   readonly code: ApprovalErrorCode;
@@ -123,6 +128,16 @@ declare function applyDecision(chain: ApprovalChain, input: DecisionInput): Appr
  */
 declare function skipStep(chain: ApprovalChain, stepId: string, reason?: string): ApprovalChain;
 declare function isApproved(chain: ApprovalChain): boolean;
+/**
+ * The canonical finalize-time gate: assert `chain` has reached `approved`,
+ * else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+ * commit/post/finalize boundary that must not proceed on an unapproved chain
+ * (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+ * SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+ * treated as "no chain required" and passes — callers that require a chain
+ * check presence separately.
+ */
+declare function assertApproved(chain: ApprovalChain | null | undefined, message?: string): void;
 declare function isRejected(chain: ApprovalChain): boolean;
 declare function isPending(chain: ApprovalChain): boolean;
 /**
@@ -130,4 +145,4 @@ declare function isPending(chain: ApprovalChain): boolean;
  */
 declare function decisionCount(chain: ApprovalChain): number;
 //#endregion
-export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalChain, ApprovalDecision, ApprovalError, ApprovalErrorCode, ApprovalStatus, ApprovalStep, ApprovalThreshold, Approver, ChainOrder, CreateChainInput, CreateStepInput, DecisionInput, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/dist/approval.mjs

@@ -115,6 +115,18 @@ function skipStep(chain, stepId, reason) {
 function isApproved(chain) {
 	return chain.status === "approved";
 }
+/**
+* The canonical finalize-time gate: assert `chain` has reached `approved`,
+* else throw `ApprovalError('CHAIN_INCOMPLETE')`. Use this at every
+* commit/post/finalize boundary that must not proceed on an unapproved chain
+* (journal-entry post, PO approve, transfer dispatch, …) so they all raise the
+* SAME error instead of hand-rolling divergent codes. A `null`/absent chain is
+* treated as "no chain required" and passes — callers that require a chain
+* check presence separately.
+*/
+function assertApproved(chain, message) {
+	if (chain != null && !isApproved(chain)) throw new ApprovalError("CHAIN_INCOMPLETE", message ?? `approval chain has not reached 'approved' (status='${chain.status}')`);
+}
 function isRejected(chain) {
 	return chain.status === "rejected";
 }
@@ -143,4 +155,4 @@ function computeChainStatus(steps) {
 	return steps.every((s) => s.status === "approved" || s.status === "skipped") ? "approved" : "pending";
 }
 //#endregion
-export { ApprovalError, applyDecision, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };
+export { ApprovalError, applyDecision, assertApproved, createChain, decisionCount, isApproved, isPending, isRejected, nextPendingStep, pendingSteps, skipStep };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",