@happyvertical/smrt-expenses 0.60.14 → 0.60.15

package/AGENTS.md

@@ -119,8 +119,9 @@ they are (review is method-only; see below). Help lives in
   state: a recorded expense is `unreviewed`, i.e. awaiting review.
 - **Cost object is not dereferenced on save.** `getCostObject()` resolves it
   through the registry and returns `null` for a foreign-tenant row. One cost
-  object per expense (columns, not a `SmrtPolymorphicAssociation` join) so a
-  cost can never roll up into two jobs.
+  original cost object per expense. Reviewed relational allocation revisions
+  can attribute that source to multiple targets; target totals count portions
+  instead of the original attribution. See [reviewed allocations](agents/reviewed-allocations.md).
 
 ## Optional financial facts
 
@@ -230,3 +231,15 @@ methods. Unknown basis or unreconciled refund remains unknown and blocks new
 settlement. A settlement records evidence; it executes no bank/provider/journal
 operation. Preserve explicit chronological prefixes and same-day ordering.
 See README and `agents/supplier-payable-test-matrix.md` for the full contract.
+
+## Reviewed allocations (#4746)
+
+See [reviewed allocations](agents/reviewed-allocations.md) and its
+[behavior matrix](agents/allocation-test-matrix.md). Source accounting remains
+singular; immutable portions own attribution and canonical billing identities.
+
+Unbilled `withdrawAllocation` audits a full return to the original unsplit target,
+requires source/all-old/restored-target authority, refuses any active billing
+claim, and permits later explicit source correction without losing history.
+Revision kind/predecessor + typed source snapshots preserve old portion facts
+when the active head is null; receipt provenance stays frozen after withdrawal.

package/README.md

@@ -394,3 +394,11 @@ source and current completion/event evidence cannot be replaced or deleted;
 managed source money/payer/context and linked refund facts cannot be edited
 around the position. Caller rollback includes both evidence and source revision.
 Expenses with no supplier-payable authority keep their existing behavior.
+
+## Reviewed expense allocations
+
+A reviewed original may be attributed through immutable, fully reconciled portions
+to multiple authorized same-tenant cost objects, without cloning its spend or
+receipt evidence. See [the allocation contract](agents/reviewed-allocations.md)
+for current actor/target authority, retries, corrections, reporting and canonical
+draft-to-issued billing reservations. Existing unsplit expense APIs remain valid.

package/agents/allocation-test-matrix.md

@@ -0,0 +1,82 @@
+# Reviewed expense allocations (#4746)
+
+Risk: **high** — public financial contract, tenant authority, concurrent monetary
+reservations and issued invoice lineage. The integration coordinator owns full
+release validation and independent review; worker evidence is narrow only.
+
+All rows exercise real persistence. Commands: `pnpm --filter
+@happyvertical/smrt-expenses exec vitest run allocation` (SQLite), then the
+package PostgreSQL lane at integration. DuckDB is not a declared expense release
+lane; its status must be explicitly assessed before release. No provider writes.
+New feature: base-fail comparison is N/A (no allocation API exists on base).
+
+| Behavior / reachable trigger | Positive | Negative / failure | Actor/context | Executor / transaction | Runtime/dialect | Contract edge / level |
+| --- | --- | --- | --- | --- | --- | --- |
+| Review split | 100 → 60/40, reload, one receipt graph | zero/fraction/unsafe/duplicate keys/unknown fields, wrong sum | tenant reviewer | source row lock + revision CAS, all children same tx | SQLite/PostgreSQL | strict public input; integration |
+| Current authority | every old and new target authorized | foreign tenant, revoked actor/grants, denied second target | ambient authenticated actor × owner × active tenant | callback receives bound executor | SQLite/PostgreSQL | required host callback; integration |
+| Retry/concurrency | identical key returns same UUIDs | changed payload conflict; stale source; concurrent competing revisions | same tenant reviewer | lock then CAS; caller retry whole tx | SQLite/PostgreSQL | idempotency contract; integration |
+| Atomicity | caller commit persists all | throw after first portion; outer rollback leaves no head/children | authorized reviewer | caller-owned executor | SQLite/PostgreSQL | injected failure; integration |
+| Immutable revisions/source | unbilled supersession preserves history | direct save/delete, source review/money/tenant rewrite | owner and foreign actor | revision/head atomic | SQLite/PostgreSQL | guarded models; integration |
+| Totals and accounting | global 100, targets 60/40; commitment100 once | source never added to portions, no partial remainder | current tenant | same bound executor reads | SQLite/PostgreSQL | legacy unsplit APIs; integration |
+| Refund/reimbursement/reporting | source cash/tax facts count100 once, separate refund follows existing model | no allocated source review/money rewrite; refund capacity unchanged | tenant owner | source locks/CAS preserved | SQLite/PostgreSQL | original source remains accounting authority; integration |
+| Canonical billable identity | portion resolves target/source/fingerprint/currency; reserve once | foreign/missing line, wrong tenant/target, reused portion | current tenant billing actor | source+invoice lock/CAS; reservation atomic | SQLite/PostgreSQL | public invoice/line contract; integration |
+| Billed lineage | draft release then supersede; issued reservation retained | issued release/rewrite and supersede blocked | current tenant billing actor | bound transaction | SQLite/PostgreSQL | immutable issued snapshot; integration |
+| Generated surface / migration | new tables/FKs/indexes; old rows unsplit | direct generated CRUD absent | no actor transport surface | real generated schema | SQLite/PostgreSQL | closed API/MCP/CLI; integration |
+
+UI/browser N/A: no new user interface. External provider failure N/A: allocation
+records local evidence and performs no external execution.
+
+## Invoice binding extension (captured before its implementation)
+
+Commerce owns only a nullable guarded `InvoiceLineItem.sourceReservationId`
+pointer. The expense reservation remains the single capacity authority. A host
+may reserve against its own draft, then bind the same reservation UUID to one
+commerce line. Trusted package registration allowlists the `billable:` qualified
+source type; client strings never dispatch arbitrary model methods.
+
+| Behavior / trigger | Positive | Negative / failure | Actor/context | Executor / transaction | Runtime/dialect | Contract edge / level |
+| --- | --- | --- | --- | --- | --- | --- |
+| Host-draft bridge | reserve once, later bind same UUID | second capacity claim, two concurrent bind targets | ambient reviewer + host draft/invoice authority | source lock/CAS, unique `(relatedReservationId,kind)`, same executor | SQLite/PostgreSQL | public compose API; integration |
+| Commerce pointer guards | authorized bind then issue | direct pointer assignment, old-pointer clearing with source namespace change, clone/duplicate, model and collection delete, cascading invoice deletion | active tenant | document lock, owning reservation checks | SQLite/PostgreSQL | existing public mutations; integration |
+| Missing capability | registered protected type resolves | unknown/missing handler; unbound protected line at issue | active tenant | same issue transaction | SQLite/PostgreSQL | fail-closed protocol; integration |
+| Withdrawal | release + pointer removal then supersede | issued release, rollback after release before unbind | host current authority | one source/invoice transaction, immutable event history | SQLite/PostgreSQL | no second ledger; integration |
+
+Initial SQLite evidence: allocation-fourth.log (6/6); extended billing first run
+allocation-billing-first.log (8/8). These are worker evidence, not release gates.
+
+## Dialect assessment evidence
+
+Existing package AGENTS validation defines SQLite and migrated PostgreSQL lanes;
+its supplier-payable matrix explicitly uses Node26 SQLite+PG. No explicit
+DuckDB compatibility promise was found in the owning README/AGENTS. A real
+DuckDB graph bootstrap was attempted: `allocation-dialects.log` records failure
+before allocation behavior on the existing
+`_smrt_billing_accounts.customer_id ON UPDATE CASCADE` relationship. Core
+`schema/foreign-key-planner.ts` deliberately refuses that unsupported DuckDB
+contract and directs callers to PostgreSQL/SQLite. This diagnostic is preserved;
+no FK/schema weakening or alternate toolchain was used. It does not constitute
+DuckDB execution evidence for allocations, and release review must reconcile the
+supported-dialect contract rather than claim universal compatibility.
+
+| Additional bounded contract | Positive | Negative/failure | Context/actor | Executor | Dialect/runtime | Validation |
+| --- | --- | --- | --- | --- | --- | --- |
+| Source privacy by action | full review source grant; bounded billing context | denied original source even when destinations allowed | real ambient review actor; callback action review/reserve/bind/release | caller bound | SQLite/PG Node26 | allocation shared suite |
+| Read authority | actual expenses.read + host target grant | read-only principal cannot reserve/review; source privacy denial does not hide own bounded portion | read actor × own target | same scoped DB | SQLite/PG Node26 | allocation shared suite |
+| Exact economic attestation | known zero-tax gross basis60, company category only | unknown/recoverable/refunded basis stays null; refunded new bill denied | target-authorized reader/biller | source lock/CAS for mutation | SQLite/PG Node26 | allocation shared suite |
+
+## Explicit unbilled withdrawal (before implementation)
+
+High-risk financial/tenancy/contract continuation. Withdraw is not a billed
+reversal and never releases claims implicitly. Public input includes exact source
+revision, expected active allocation revision, request key and audit evidence.
+
+| Behavior / trigger | Positive | Negative/failure | Actor/context | Executor/atomicity | Dialect | Evidence |
+| --- | --- | --- | --- | --- | --- | --- |
+| Unbilled withdrawal | released draft claim → audited withdrawal → reopen/amount correction or duplicate rejection | active reserved/bound/issued capacity refuses; no auto-release | source-private reviewer + ALL old target grants + mandatory restored-unsplit destination grant | source lock/CAS, same caller executor, immutable event + null head in one transaction | SQLite/PG shared suite | narrow allocation command |
+| Retry/concurrency | identical replay reauthorizes and returns same audit UUID | changed payload/key collision, stale active/source revisions, competing withdrawals | current actor/source/old targets/restored destination | unique request, unique predecessor successor; source CAS | SQLite/PG | shared feature proof |
+| Atomic reporting | source100 returns once to unsplit target; commitments/global totals unchanged | injected failure after audit insert leaves old head/targets, caller rollback restores all | same tenant | no transient committed source+portion cost | SQLite/PG | shared real persistence |
+| History after correction | next review links latest withdrawal deterministically; old portion facts remain immutable across source edits/reject/reopen | foreign/revoked old/restored target denies, ambiguous chain fails closed | bounded old-target reader vs full source editor | immutable relational predecessor chain; typed revision source snapshot | SQLite/PG | shared lineage/reload proof |
+
+New API absent on prior source is feature baseline N/A for existing API
+regression, but executable absent-command/blocked-correction evidence is captured.
+No provider writes, browser/UI N/A; root owns PG/fullvalidation/review.

package/agents/reviewed-allocations.md

@@ -0,0 +1,138 @@
+# Reviewed expense attribution
+
+`ExpenseCollection.reviewAllocation(input, authority)` reviews a **full** split
+of a positive, reviewed original. The source keeps its original amount, payer,
+commitment, reimbursement, refund capacity, supplier tax facts and receipt graph.
+Children are attribution, never additional expenses or another cash authority.
+
+The input names `sourceExpenseId`, the loaded `updated_at` as
+`expectedSourceRevision`, `requestId`, `reviewEvidence`, and 1–1000 portions.
+Each portion has an exact positive safe-integer `amountMinor`, unique
+`portionKey`, registered same-tenant `costObjectType`/`costObjectId`, and explicit
+`costCodeRef`. Portions must sum exactly to source gross money in source currency.
+No remainder, tax allocation, customer markup or tax policy is inferred.
+
+Ambient `expenses.recordReview` authorizes a person in the active tenant. The
+mandatory host `authorizeSource(principal,sourceExpenseId,executor,context)`
+callback checks original source privacy for full reviews. Its context names the
+explicit review/reserve/bind/release action; billing contexts include only the
+bounded authorized portion so target finance users need no unrelated original
+project or full receipt disclosure. The mandatory
+`authorizeTarget(principal,target,executor)` callback must enforce
+current project grants for **every old and proposed target**. The supplied
+executor is the command's caller-affine transaction. Callback denial rolls back
+all children/head/revision claims. Never perform provider writes in the callback.
+
+A source lock and revision compare-and-swap serialize allocations and billing
+reservations. Same request/payload returns the same immutable IDs after current
+authority checks; changed payload conflicts. On serialization/revision failure,
+retry the whole caller transaction with fresh instances. Unreserved corrections
+append a revision linked by `previousRevisionId`; prior children remain readable.
+While an allocation is active, source review cannot be reopened/rejected.
+Use explicit audited unbilled withdrawal before source correction; immutable
+allocation provenance prevents physical source deletion.
+
+`totalsByCurrency()` counts each source once. Target filters project the current
+portions instead of counting the source's original attribution. Commitment
+positions, supplier-tax reports and reimbursement/refund positions retain the
+original accounting source exactly once. `forCostObject()` remains an original
+source/evidence query; use target-filtered totals for allocated money. Do not sum
+source amounts obtained as evidence to calculate target costs.
+
+`resolveExpenseAllocationPortion(db,portionId,authority)` returns only that
+portion's immutable source/revision/fingerprint/target/code/amount/currency and
+current `active` flag after project authority; it does not disclose receipt URLs
+or other projects. Receipt access still needs the original source privacy check.
+`getExpenseAllocationPortionPosition` adds current reservation UUID, host draft
+references and bound invoice references/status for that same target portion. It
+is advisory; reservation mutations always recheck capacity atomically. Historical
+or issued claims never become available implicitly.
+
+## Billing
+
+`reserveExpenseAllocationPortion` reserves a whole portion once against a host
+`draftType`/`draftId`, requiring `authority.authorizeDraft`; it can alternatively
+reserve and bind directly to an existing invoice/line. Customer price remains
+independent of source capacity. `bindExpenseAllocationPortion` assigns that same
+reservation UUID to one same-tenant, same-currency commerce draft line after
+mandatory `authorizeInvoice` current-grant/project checks. The line must use
+`EXPENSE_ALLOCATION_INVOICE_SOURCE` and `sourceId = portionId`.
+
+Commerce stores only the reservation pointer, with trusted source-handler checks
+on line mutations and invoice issue. Missing handlers, unbound protected lines,
+changed/cleared bound identities, copied pointers and duplicate line claims fail.
+All reservation and binding events are immutable relational rows; source locking,
+CAS and unique event keys prevent concurrent double assignment. There is no
+commerce-side source availability balance.
+
+`releaseExpenseAllocationPortion` records withdrawal and removes a bound draft
+pointer in the same transaction. It retains claim/binding history. Active claims
+block allocation supersession. Once issued, a claim remains consumed: ordinary
+release/reallocation is refused and corrections require an explicit credit or
+reversal policy; the API never rewrites issued invoices or infers such policy.
+
+Migrate schemas before use, including the three new allocation tables, nullable
+Expense head and nullable commerce line pointer. Existing unsplit rows retain
+NULL heads/pointers and unchanged accounting semantics. See the
+[behavior matrix](allocation-test-matrix.md) for release evidence requirements.
+
+Bounded readers use the explicitly published `expenses.read` catalog permission
+(registered through public `registerPermissionDefinitions`; `get`/`list`
+normalize to `.read`) and the host's mandatory current target-cost
+visibility callback. They never require review authority or original-source
+privacy access. Mutations retain `expenses.recordReview`. Consumers must grant
+these real permissions through their role configuration; never fabricate a
+permission snapshot to call the library.
+
+Bounded identities include source date, payer **category** (no person/name),
+reimbursement eligibility, nullable supplier-tax presence, refund presence and
+nullable exact `costBasisMinor`. Basis equals portion gross only when the
+original's complete known basis equals gross and no linked refunds exist. It is
+otherwise unknown; tax is never apportioned implicitly. New reserve/bind commands
+refuse a source with any linked refunds pending explicit reversal policy.
+Reimbursement eligibility freezes with allocation provenance. Existing issued
+reservations remain consumed and immutable when later refund evidence arrives.
+
+The source fingerprint includes a private random per-source nonce retained only
+in full source-authorized revision evidence. Bounded readers receive its digest,
+not the nonce, preventing offline guesses of another project's source total.
+Unbilled supersession reuses the nonce and retains the same source fingerprint.
+
+## Explicit unbilled withdrawal before source correction
+
+`ExpenseCollection.withdrawAllocation` (root `withdrawExpenseAllocation`) accepts
+`sourceExpenseId`, `expectedActiveRevisionId`, `expectedSourceRevision`,
+`requestId` and `reviewEvidence`. It appends an immutable revision with
+`kind: 'withdrawal'` and clears the active head atomically on the caller executor.
+The result is `{revision, withdrawnRevisionId}`; reload the original source for
+its current state/revision. No portion row is changed or deleted.
+
+Withdrawal requires current source privacy/edit authority with action
+`withdrawAllocation`, authority for **every old portion target**, and a separate
+mandatory `authorizeUnsplitTarget(principal,{sourceExpenseId,costObjectType,
+costObjectId},executor)` callback for the restored original destination. The
+latter has no invented cost code. Assigned destinations must exist in the active
+tenant; an explicitly unassigned original has both destination strings empty and
+still requires the callback. Replays reauthorize all of these paths; changed
+payload, stale source/head or a conflicting request is refused.
+
+Any active reservation, bound claim or issued claim refuses withdrawal. First
+abandon/release an authorized unissued draft explicitly; withdrawal never
+silently releases capacity or rewrites issued invoices. **This is not billed
+reversal support.** Existing settlement/refund/reimbursement guards also remain.
+
+Global and commitment totals still count the original source once. Its monetary
+attribution switches atomically back to the original unsplit destination. Source
+review status is unchanged: no financial approval is implied. The caller may
+then explicitly reopen and correct the original amount/date/payer or reject a
+duplicate using existing guarded source methods. Corrected unreviewed money stays
+excluded until separately reviewed. Original receipt evidence remains immutable
+once allocation history exists, including after withdrawal.
+
+The immutable predecessor chain has one successor per revision. Its unique leaf
+retains the latest withdrawal independently of a null active head; the next
+review links to that withdrawal deterministically. Typed source snapshot facts
+on each revision preserve historical portion date/payer/basis attestation across
+later source correction. Inactive historical portions remain bounded-readable
+with `active:false` when the source is reopened/rejected; they are never available
+for fresh billing. Active portions still require a usable reviewed source.

package/dist/allocation-internal.d.ts

@@ -0,0 +1,6 @@
+/** Package-private command capabilities; never exported from the package root. */
+import type { SmrtObject } from '@happyvertical/smrt-core';
+export declare const allocationWrites: WeakSet<SmrtObject>;
+export declare const allocationHeads: WeakMap<SmrtObject, string | null>;
+export declare function insertAllocation<T extends SmrtObject>(row: T): Promise<T>;
+//# sourceMappingURL=allocation-internal.d.ts.map

package/dist/allocation-internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocation-internal.d.ts","sourceRoot":"","sources":["../src/allocation-internal.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,eAAO,MAAM,gBAAgB,qBAA4B,CAAC;AAC1D,eAAO,MAAM,eAAe,oCAA2C,CAAC;AACxE,wBAAsB,gBAAgB,CAAC,CAAC,SAAS,UAAU,EACzD,GAAG,EAAE,CAAC,GACL,OAAO,CAAC,CAAC,CAAC,CASZ"}

package/dist/chunks/{Expense-CimA4lxE.js → Expense-Deq19w2r.js}

@@ -1,8 +1,22 @@
 import { ExpenseError } from "../types.js";
 import { ObjectRegistry, SmrtObject, crossPackageRef, field, foreignKey, isPostgresDatabase, isUniqueViolationError, smrt } from "@happyvertical/smrt-core";
 import { TenantScoped, getTenantId, tenantId } from "@happyvertical/smrt-tenancy";
-import { ContractLineItemCollection, PurchaseContractCollection, VendorCollection } from "@happyvertical/smrt-commerce";
 import { createHash, randomUUID } from "node:crypto";
+import { ContractLineItemCollection, PurchaseContractCollection, VendorCollection } from "@happyvertical/smrt-commerce";
+//#region src/allocation-internal.ts
+var allocationWrites = /* @__PURE__ */ new WeakSet();
+var allocationHeads = /* @__PURE__ */ new WeakMap();
+async function insertAllocation(row) {
+	await row.initialize();
+	allocationWrites.add(row);
+	try {
+		await row.save();
+		return row;
+	} finally {
+		allocationWrites.delete(row);
+	}
+}
+//#endregion
 //#region src/validation.ts
 var CATEGORY_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var ISO_CURRENCY = /^[A-Z]{3}$/;
@@ -643,8 +657,10 @@ var Expense = class extends SmrtObject {
 	reimbursedAmount = null;
 	reimbursedAt = null;
 	reimbursementReference = "";
+	activeAllocationRevisionId = null;
 	constructor(options = {}) {
 		super(options);
+		if (options.activeAllocationRevisionId !== void 0) this.activeAllocationRevisionId = options.activeAllocationRevisionId;
 		if (options.tenantId !== void 0) this.tenantId = options.tenantId;
 		if (options.costObjectType !== void 0) this.costObjectType = options.costObjectType;
 		if (options.costObjectId !== void 0) this.costObjectId = options.costObjectId;
@@ -867,6 +883,10 @@ var Expense = class extends SmrtObject {
 		const persisted = await this.readPersisted();
 		const inserting = await pinNaturalKey("Expense", this, persisted);
 		if (persisted && String(persisted.tenant_id ?? "") !== String(effectiveTenant(this.tenantId) ?? "")) throw new ExpenseError("EXPENSE_INVALID", `Expense ${this.id}: its tenant cannot change after it is recorded.`);
+		const storedAllocation = asNullableString(persisted?.active_allocation_revision_id);
+		if (storedAllocation && persisted && Boolean(persisted.reimbursable) !== this.reimbursable) throw new ExpenseError("EXPENSE_INVALID", "Allocated source reimbursement eligibility is frozen.");
+		if (storedAllocation !== this.activeAllocationRevisionId && !(allocationHeads.has(this) && allocationHeads.get(this) === this.activeAllocationRevisionId)) throw new ExpenseError("EXPENSE_INVALID", "Allocation head is command-owned.");
+		if (storedAllocation && persisted && (String(persisted.review_status) !== this.reviewStatus || String(persisted.duplicate_of_id ?? "") !== String(this.duplicateOfId ?? ""))) throw new ExpenseError("EXPENSE_INVALID", "Allocated source review cannot change; supersede its allocation instead.");
 		await this.assertSupplierPayable(persisted);
 		this.assertReviewFields(persisted);
 		this.assertReviewedLock(persisted);
@@ -994,6 +1014,7 @@ var Expense = class extends SmrtObject {
 			await this.lockRefundRows();
 			const row = await this.readPersisted();
 			if (row && String(row.tenant_id ?? "") !== String(effectiveTenant(this.tenantId) ?? "")) payableInvalid("owned source is required.");
+			if (row?.active_allocation_revision_id) throw new ExpenseError("EXPENSE_INVALID", "Allocated source evidence cannot be deleted.");
 			if (row?.supplier_payable_json) payableInvalid("supplier authority cannot be deleted.");
 			const parentId = asNullableString(row?.refund_of_id);
 			if (parentId) {
@@ -1312,6 +1333,10 @@ __decorateClass([field({
 	type: "text",
 	readonly: true
 })], Expense.prototype, "reimbursementReference", 2);
+__decorateClass([foreignKey("ExpenseAllocationRevision", {
+	nullable: true,
+	onDelete: "RESTRICT"
+}), field({ readonly: true })], Expense.prototype, "activeAllocationRevisionId", 2);
 Expense = __decorateClass([TenantScoped({ mode: "optional" }), smrt({
 	tableName: "expenses",
 	api: { include: [
@@ -1359,6 +1384,6 @@ function sameTenant(a, b) {
 	return (a ?? null) === (b ?? null);
 }
 //#endregion
-export { identityConflict as a, pinNaturalKey as c, effectiveTenant as i, assertMinorUnits as n, normalizeSha256 as o, computeContentSha256 as r, normalizeTenantId as s, Expense as t };
+export { effectiveTenant as a, normalizeSha256 as c, allocationHeads as d, allocationWrites as f, computeContentSha256 as i, normalizeTenantId as l, assertMinorUnits as n, identityConflict as o, insertAllocation as p, assertQualifiedClassName as r, instantMs as s, Expense as t, pinNaturalKey as u };
 
-//# sourceMappingURL=Expense-CimA4lxE.js.map
+//# sourceMappingURL=Expense-Deq19w2r.js.map