@mj-biz-apps/orders-core-entities-server 0.0.1 → 5.2.0

package/LICENSE

@@ -0,0 +1,183 @@
+Business Source License 1.1
+
+License text copyright (c) 2024 MariaDB plc, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB plc.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Blue Cypress, Inc.
+
+Licensed Work:        MemberJunction.
+                      The Licensed Work is (c) 2023-2026 Blue Cypress, Inc.
+
+Additional Use Grant: Subject to the terms of this License, Licensor grants
+                      you the following additional rights to make Production
+                      Use of the Licensed Work.
+
+                      1. Internal Use
+
+                      You may make production use of the Licensed Work for
+                      your own internal business or organizational operations.
+
+                      2. Nonprofit Use
+
+                      If you are a Nonprofit, you may make production use of
+                      the Licensed Work for the operations and activities of
+                      your Organizational Family.
+
+                      3. MemberJunction Certified Program Use
+
+                      If you are authorized by Licensor under the
+                      MemberJunction Certified Program to provide professional
+                      services using the Licensed Work, you may make
+                      production use of the Licensed Work in providing such
+                      professional services to a client, provided that:
+
+                      (a) the Licensed Work is deployed in, and the applicable
+                      production use occurs within, an environment owned,
+                      leased, licensed, subscribed to, or otherwise controlled
+                      by that client; and
+
+                      (b) the production use is for that client's own internal
+                      business or organizational operations or is otherwise
+                      independently permitted to that client under this
+                      Additional Use Grant.
+
+                      4. Definitions Applicable to the Additional Use Grant
+
+                      "Affiliate" means, with respect to a specified Person,
+                      any other Person that directly or indirectly Controls,
+                      is Controlled by, or is under common Control with such
+                      specified Person.
+
+                      "Control" (including the terms "Controls," "Controlled
+                      by," and "under common Control with") means the direct
+                      or indirect possession of the power to direct or cause
+                      the direction of the management and policies of a
+                      Person, whether through ownership of voting interests,
+                      by contract, or otherwise.
+
+                      "Organizational Family" means, with respect to a Person,
+                      (a) such Person and its Affiliates, and (b) any
+                      nonprofit organization, governmental entity, chapter,
+                      division, local affiliate, regional affiliate, state
+                      affiliate, national affiliate, or other entity that is
+                      formally affiliated with such Person through governing
+                      documents, a charter, bylaws, a membership agreement, or
+                      another written organizational instrument, and is
+                      recognized under such documents as part of the same
+                      organizational structure.
+
+                      "Nonprofit" means a Person recognized by the Internal
+                      Revenue Service as exempt from federal income taxation
+                      under Section 501(c)(3), 501(c)(4), 501(c)(5), or
+                      501(c)(6) of the Internal Revenue Code, or a foreign
+                      organization recognized under substantially equivalent
+                      laws.
+
+                      A Person claiming eligibility as a Nonprofit shall, upon
+                      Licensor's reasonable request, provide documentation
+                      reasonably sufficient to demonstrate that it qualifies
+                      as a Nonprofit. If such Person materially misrepresents,
+                      or is unable to demonstrate, its qualification as a
+                      Nonprofit, the rights granted to such Person under
+                      Section 2 of this Additional Use Grant shall terminate.
+
+                      "MemberJunction Certified Program" means Licensor's
+                      then-current program for certifying and authorizing a
+                      Person to provide professional services using the
+                      Licensed Work.
+
+                      "Person" means any individual, corporation, limited
+                      liability company, partnership, association, nonprofit
+                      organization, governmental entity, or other legal or
+                      organizational entity.
+
+Change Date:          Four (4) years from the date the Licensed Work is first
+                      made available.
+
+Change License:       MIT License.
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Blue Cypress, Inc.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License
+   can be included in a program with software provided under GPL Version 2.0
+   or a later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

package/README.md

@@ -1,3 +1,142 @@
-# @mj-biz-apps/orders-core-entities-server
+# `@mj-biz-apps/orders-core-entities-server`
 
-Placeholder release. See https://github.com/MemberJunction/bizapps-orders
+**Every rule that decides money lives here.** Entity subclasses that override `Save()`, the pure
+engines they call, and the remotable operations that expose multi-step work.
+
+This package is server-only. Import it from the server bootstrap so its `@RegisterClass` decorators
+fire — nothing here is reachable until they do.
+
+---
+
+## The shape: pure core, server shell
+
+Each domain is split in two, and the split is deliberate rather than tidy.
+
+| Pure (no DB, no entities) | Server (needs a database) |
+|---|---|
+| `PricingBehavior` | `PriceResolver` |
+| `PromotionBehavior` | `PromotionEngine` |
+| `ChargeBehavior` | `ChargeEngine` |
+| `SubscriptionBehavior` | `OrderEntityServer` |
+| `TaxResolver` *(the walk)* | `TaxResolver` *(the lookups)* |
+
+**Why:** the arithmetic is where the money is, and money should be provable without a database. Two
+10% promotions are 19% or 20% depending on one setting; a Volume band and a Tiered band give 800 and
+900 for identical inputs. Those facts are asserted in unit tests that run in milliseconds, and the
+server half is then only responsible for finding the right rows.
+
+## The order confirm, end to end
+
+`OrderEntityServer.Save()` is the spine. Everything happens in ONE transaction:
+
+```
+BeginTransaction
+  assign OrderNumber
+  save the header
+  ── per line, IN MEMORY ─────────────────────────────
+     proration (subscription terms)
+     event service period
+     price resolution            → UnitPrice, ProductPriceID
+  decide promotions              → DiscountAmount
+  decide charges + resolve tax   → LineTax, ChargeAmount
+  ── persist ─────────────────────────────────────────
+     save lines
+     write adjustment + charge + component rows
+  materialize subscriptions
+  book journal entries
+  create the initial payment
+CommitTransaction
+```
+
+**Everything that changes a line's money happens BEFORE the insert.** That ordering is forced, not
+stylistic: a Confirmed line is frozen by trigger 51003, and because MJ's CRUD procs run under
+`INSERT-EXEC`, a trigger rollback surfaces as *"Cannot use the ROLLBACK statement within an
+INSERT-EXEC statement"* — an error naming neither the line nor the rule it broke. Correcting a line
+after insert is not an option, so nothing may need correcting.
+
+## Resolution walks
+
+Two resolvers walk the **same path**, on purpose — anyone who understands one understands the other,
+and they cannot drift into disagreeing about what "the product's category tree" means:
+
+```
+product → its category → that category's ancestors → the company → default
+```
+
+- **`GLAccountResolver`** — role → GL account. Nothing resolving is a hard failure; a guessed account
+  still balances, so the misposting would be invisible.
+- **`PriceResolver`** — product → price, with `BasePriceResolver` pluggable at any level.
+
+`TaxResolver` uses the same chain for taxability (product → category → ancestors → type), with the
+type as a NOT NULL backstop so the walk always terminates.
+
+## Refusals are a feature
+
+This package refuses more than it computes, and each refusal exists because the alternative is a
+plausible wrong answer:
+
+| Situation | Refused because |
+|---|---|
+| Two price rules of equal priority | The winner would be whatever the database returned first — arbitrary, stable in test, liable to flip in production |
+| No GL account for a role or charge | A guessed account still balances; the entry would post and be wrong |
+| A manual discount with no `SalesAuthority` | Absence of an authority is not permission |
+| A captured payment whose lines ≠ its amount | The remainder would have no home in the ledger |
+| An intercompany pair with no mapping | Cash collected by A against B's line would credit A's receivable |
+
+**The recurring shape: the wrong answer still looks like a right one.** A wrong price is still a
+price; a mis-oriented intercompany pair still balances. Where a zero is a legitimate outcome, the
+REASON is recorded — tax writes a zero-amount `OrderLinePriceComponent` saying which of the four
+reasons applied.
+
+## Remotable operations
+
+Multi-step work with guards, exposed through `BaseRemotableOperation`. Logical refusals come back
+**inside** the output as `Success: false` with a reason; only genuine faults throw.
+
+| Operation | Does |
+|---|---|
+| `Orders.PreviewPrice` | Dry-run pricing. **Runs the real pipeline** — a preview that diverges from what is charged is worse than none |
+| `Orders.ApplyAccountCredit` | Spends an order's negative balance on another order. Zero-amount payment, two offsetting lines |
+| `Orders.RefundPayment` | Mirrors a capture (D53), proportionally across the orders it settled |
+| `Orders.CancelSubscription` | Cancels with the term's own rules. Revokes standing grants when access-through has already passed |
+| `Orders.SpawnRenewals` | Spawns renewal orders as Drafts |
+| `Orders.CheckEntitlement` | Does this person currently have this capability? Evaluated, not a poll of `Status`. Fail closed |
+| `Orders.ListEntitlements` | The person's library, one row per Code, same evaluator |
+
+## Accounting boundary
+
+`AccountingBridge` is the only place that knows about bizapps-accounting. Orders resolves accounts
+and submits balanced drafts; accounting owns the ledger.
+
+Two constraints that shape everything: accounting derives an entry's company **from its accounts**,
+so a cross-company entry cannot be booked at all — which is why intercompany legs are per company
+rather than one spanning entry. And it rejects negative amounts, so a reversal is the **mirror** of
+an entry (sides swapped, positive amounts), never a negation.
+
+## Testing
+
+- **Unit** (`src/__tests__`, vitest, no DB) — the pure engines. Volume vs Tiered, stacking
+  arithmetic, charge basis, the taxability walk, allocation.
+- **Integration** — `@mj-biz-apps/orders-integration-tests`, transaction-per-check with rollback.
+
+Both suites are mutation-tested: break the code deliberately, confirm the checks catch it. Worth the
+effort here because every wrong answer in this domain produces a plausible number *and* a balanced
+entry.
+
+## Adding behaviour
+
+Prefer a plugin over an edit:
+
+```ts
+@RegisterClass(BasePriceResolver, `Company:${companyId}`)
+export class AcmePricing extends BasePriceResolver { /* return null to decline */ }
+
+@RegisterClass(BasePromotionQualifier, 'LOYALTY-2YR')
+export class TwoYearMember extends BasePromotionQualifier { /* ... */ }
+
+@RegisterClass(BaseTaxJurisdictionResolver)
+export class RooftopResolver extends BaseTaxJurisdictionResolver { /* ... */ }
+```
+
+If you must edit an engine: put the arithmetic in the pure half with a unit test, and keep the
+server half to finding rows.

package/dist/AccountingBridge.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The one place orders reaches into accounting.
+ *
+ * Both booking paths — order confirm (`Dr AR / Cr Revenue`) and payment capture
+ * (`Dr Cash / Cr AR`) — need the same two things: a `GLAccountResolver` wired to the accounting
+ * engine, and the MJ entity IDs the polymorphic `GLAccountLink` rows hang off. This module owns
+ * both so there is exactly one copy of the coupling rather than one per entity server.
+ *
+ * `@mj-biz-apps/accounting-engine-base` is imported STATICALLY, like every other import in the repo
+ * (CLAUDE.md forbids dynamic require/import). This file used to load the engine through
+ * `await import(...)`, justified as keeping a peer dependency out of bundles that do not already
+ * have it — but the justification never held, because `pickActiveLinkIndex` below has always been a
+ * static import from the same package. The module was therefore already resolved and evaluated at
+ * load time; the dynamic form bought nothing and only cost us a lazy failure mode, where a missing
+ * peer surfaced deep inside a booking call instead of at import.
+ *
+ * Load ORDER still matters — accounting's server package registers the remote operation this class
+ * resolves by key — but that is a different package (`accounting-server`, wired up by the host app's
+ * resolver paths) and is unaffected by how this one is imported.
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { GLAccountResolver, type ResolverEntityIDs } from './GLAccountResolver.js';
+/** The subset of `AccountingEngineBase` used here, declared structurally so there is no type import. */
+export interface AccountingEngineSurface {
+    ConfigEx(options: {
+        forceRefresh?: boolean;
+        contextUser?: UserInfo;
+        provider?: IMetadataProvider;
+    }): Promise<unknown>;
+    ResolveLinkedAccount(entityId: string, recordId: string, role: string, asOfDate: Date): {
+        Link?: {
+            GLAccountID?: string;
+        };
+    } | null;
+    GLAccountByID(glAccountId: string): {
+        CompanyID?: string;
+    } | undefined;
+    /**
+     * The raw cached links and roles, needed for the COMPANY-SCOPED lookup (D71): a globally-shared
+     * record such as a charge type has one link per company, and `ResolveLinkedAccount` has no
+     * company dimension to choose between them.
+     */
+    GLAccountLinks: Array<{
+        EntityID: string;
+        RecordID: string;
+        GLAccountID: string;
+        GLAccountRoleID: string;
+        Status: 'Pending' | 'Active' | 'Disabled';
+        StartedAt: Date | null;
+        EndedAt: Date | null;
+    }>;
+    GLAccountRoles: Array<{
+        ID: string;
+        Name: string;
+    }>;
+}
+/** MJ entity ID for a name, with an error that says which name failed rather than `undefined`. */
+export declare function EntityIDFor(name: string): string;
+/** The entity IDs the account-link walk needs. */
+export declare function ResolverEntities(): ResolverEntityIDs;
+/** Load the accounting engine and make sure its caches are populated. */
+export declare function LoadAccountingEngine(provider: IMetadataProvider, user: UserInfo): Promise<AccountingEngineSurface>;
+/** A resolver bound to the live accounting engine. */
+export declare function BuildGLAccountResolver(provider: IMetadataProvider, user: UserInfo): Promise<GLAccountResolver>;
+//# sourceMappingURL=AccountingBridge.d.ts.map

package/dist/AccountingBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountingBridge.d.ts","sourceRoot":"","sources":["../src/AccountingBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,iBAAiB,EAAY,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAOnF,wGAAwG;AACxG,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,OAAO,EAAE;QACd,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,WAAW,CAAC,EAAE,QAAQ,CAAC;QACvB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;KAChC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrB,oBAAoB,CAChB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,IAAI,GACf;QAAE,IAAI,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9C,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;IACvE;;;;OAIG;IACH,cAAc,EAAE,KAAK,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;QAC1C,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;QACvB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;KACxB,CAAC,CAAC;IACH,cAAc,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvD;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,IAAI,iBAAiB,CAOpD;AAED,yEAAyE;AACzE,wBAAsB,oBAAoB,CACtC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,uBAAuB,CAAC,CASlC;AAED,sDAAsD;AACtD,wBAAsB,sBAAsB,CACxC,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,iBAAiB,CAAC,CA2C5B"}

package/dist/AccountingBridge.js

@@ -0,0 +1,102 @@
+/**
+ * The one place orders reaches into accounting.
+ *
+ * Both booking paths — order confirm (`Dr AR / Cr Revenue`) and payment capture
+ * (`Dr Cash / Cr AR`) — need the same two things: a `GLAccountResolver` wired to the accounting
+ * engine, and the MJ entity IDs the polymorphic `GLAccountLink` rows hang off. This module owns
+ * both so there is exactly one copy of the coupling rather than one per entity server.
+ *
+ * `@mj-biz-apps/accounting-engine-base` is imported STATICALLY, like every other import in the repo
+ * (CLAUDE.md forbids dynamic require/import). This file used to load the engine through
+ * `await import(...)`, justified as keeping a peer dependency out of bundles that do not already
+ * have it — but the justification never held, because `pickActiveLinkIndex` below has always been a
+ * static import from the same package. The module was therefore already resolved and evaluated at
+ * load time; the dynamic form bought nothing and only cost us a lazy failure mode, where a missing
+ * peer surfaced deep inside a booking call instead of at import.
+ *
+ * Load ORDER still matters — accounting's server package registers the remote operation this class
+ * resolves by key — but that is a different package (`accounting-server`, wired up by the host app's
+ * resolver paths) and is unaffected by how this one is imported.
+ */
+import { Metadata } from '@memberjunction/core';
+import { AccountingEngineBase, pickActiveLinkIndex } from '@mj-biz-apps/accounting-engine-base';
+import { GLAccountResolver } from './GLAccountResolver.js';
+const PRODUCT_ENTITY = 'MJ_BizApps_Orders: Products';
+const PRODUCT_CATEGORY_ENTITY = 'MJ_BizApps_Orders: Product Categories';
+const PRODUCT_TYPE_ENTITY = 'MJ_BizApps_Orders: Product Types';
+const COMPANY_ENTITY = 'MJ: Companies';
+/** MJ entity ID for a name, with an error that says which name failed rather than `undefined`. */
+export function EntityIDFor(name) {
+    // EntityByName, not Entities.find: it is case- and trim-insensitive and O(1), and it side-steps
+    // the global-provider footgun in code paths that were handed a provider (Marcelo, PR #15).
+    const entity = new Metadata().EntityByName(name);
+    if (!entity) {
+        throw new Error(`Entity '${name}' not found in metadata. Has CodeGen run for this schema?`);
+    }
+    return entity.ID;
+}
+/** The entity IDs the account-link walk needs. */
+export function ResolverEntities() {
+    return {
+        Product: EntityIDFor(PRODUCT_ENTITY),
+        ProductCategory: EntityIDFor(PRODUCT_CATEGORY_ENTITY),
+        ProductType: EntityIDFor(PRODUCT_TYPE_ENTITY),
+        Company: EntityIDFor(COMPANY_ENTITY),
+    };
+}
+/** Load the accounting engine and make sure its caches are populated. */
+export async function LoadAccountingEngine(provider, user) {
+    const engine = AccountingEngineBase.Instance;
+    // Force a refresh. ORD-WORLD (and any other process) writes links through BaseEntity
+    // in a different Node process than MJAPI; those events never reach this cache, so a
+    // Config(false) after startup keeps serving an empty link set and every confirm
+    // reports "No GL account is linked for role 'Accounts Receivable'". Reloading a few
+    // dozen link rows on a booking is cheaper than a silent miss.
+    await engine.ConfigEx({ forceRefresh: true, contextUser: user, provider });
+    return engine;
+}
+/** A resolver bound to the live accounting engine. */
+export async function BuildGLAccountResolver(provider, user) {
+    const engine = await LoadAccountingEngine(provider, user);
+    return new GLAccountResolver(ResolverEntities(), provider, user, (entityId, recordId, role, asOf, forCompanyID) => {
+        // COMPANY-SCOPED LOOKUP (D71). Some linked records are GLOBAL while their accounts are
+        // per-company — a charge type is one config row shared by every company, but 'shipping
+        // revenue' is a different account in each one. `ResolveLinkedAccount` answers "which link
+        // wins for this record", which for a global record means picking arbitrarily between several
+        // companies' accounts and then failing D6's cross-company guard.
+        //
+        // When the caller names the company, filter the candidates by the ACCOUNT's company first
+        // and let the ordinary window/status rules choose among what is left.
+        if (forCompanyID) {
+            const key = (v) => (v ?? '').trim().toLowerCase();
+            const candidates = engine.GLAccountLinks.filter((l) => {
+                if (key(l.EntityID) !== key(entityId))
+                    return false;
+                if (key(l.RecordID) !== key(recordId))
+                    return false;
+                const linkRole = engine.GLAccountRoles.find((r) => key(r.ID) === key(l.GLAccountRoleID));
+                if (!linkRole || linkRole.Name.trim().toLowerCase() !== role.trim().toLowerCase())
+                    return false;
+                const acct = engine.GLAccountByID(l.GLAccountID);
+                return key(acct?.CompanyID) === key(forCompanyID);
+            });
+            const winner = pickActiveLinkIndex(candidates.map((l) => ({ Status: l.Status, StartedAt: l.StartedAt, EndedAt: l.EndedAt })), asOf);
+            if (winner === -1)
+                return null;
+            const chosen = candidates[winner];
+            const acct = engine.GLAccountByID(chosen.GLAccountID);
+            return { GLAccountID: chosen.GLAccountID, CompanyID: acct?.CompanyID ?? '' };
+        }
+        // ResolveLinkedAccount returns { Link, Dimensions } — the account is on the link.
+        const hit = engine.ResolveLinkedAccount(entityId, recordId, role, asOf);
+        const glAccountID = hit?.Link?.GLAccountID;
+        if (!glAccountID)
+            return null;
+        // The company comes from the ACCOUNT, not the link. Accounting derives the entry's company
+        // that way (their CH-2), so it is the value D6's cross-company guard must compare — reading
+        // it off the link would compare the wrong thing and let a mismatch through.
+        const account = engine.GLAccountByID(glAccountID);
+        return { GLAccountID: glAccountID, CompanyID: account?.CompanyID ?? '' };
+    });
+}
+//# sourceMappingURL=AccountingBridge.js.map

package/dist/AccountingBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountingBridge.js","sourceRoot":"","sources":["../src/AccountingBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAqB,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAChG,OAAO,EAAE,iBAAiB,EAA0B,MAAM,wBAAwB,CAAC;AAEnF,MAAM,cAAc,GAAG,6BAA6B,CAAC;AACrD,MAAM,uBAAuB,GAAG,uCAAuC,CAAC;AACxE,MAAM,mBAAmB,GAAG,kCAAkC,CAAC;AAC/D,MAAM,cAAc,GAAG,eAAe,CAAC;AAiCvC,kGAAkG;AAClG,MAAM,UAAU,WAAW,CAAC,IAAY;IACpC,gGAAgG;IAChG,2FAA2F;IAC3F,MAAM,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,2DAA2D,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,MAAM,CAAC,EAAE,CAAC;AACrB,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB;IAC5B,OAAO;QACH,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC;QACpC,eAAe,EAAE,WAAW,CAAC,uBAAuB,CAAC;QACrD,WAAW,EAAE,WAAW,CAAC,mBAAmB,CAAC;QAC7C,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC;KACvC,CAAC;AACN,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACtC,QAA2B,EAC3B,IAAc;IAEd,MAAM,MAAM,GAAI,oBAAyE,CAAC,QAAQ,CAAC;IACnG,qFAAqF;IACrF,oFAAoF;IACpF,gFAAgF;IAChF,oFAAoF;IACpF,8DAA8D;IAC9D,MAAM,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC;AAClB,CAAC;AAED,sDAAsD;AACtD,MAAM,CAAC,KAAK,UAAU,sBAAsB,CACxC,QAA2B,EAC3B,IAAc;IAEd,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAE1D,OAAO,IAAI,iBAAiB,CAAC,gBAAgB,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE;QAC9G,uFAAuF;QACvF,uFAAuF;QACvF,0FAA0F;QAC1F,6FAA6F;QAC7F,iEAAiE;QACjE,EAAE;QACF,0FAA0F;QAC1F,sEAAsE;QACtE,IAAI,YAAY,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,CAAC,CAA4B,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAC7E,MAAM,UAAU,GAAG,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClD,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACpD,IAAI,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC;oBAAE,OAAO,KAAK,CAAC;gBACpD,MAAM,QAAQ,GAAG,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;gBACzF,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE;oBAAE,OAAO,KAAK,CAAC;gBAChG,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;gBACjD,OAAO,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,KAAK,GAAG,CAAC,YAAY,CAAC,CAAC;YACtD,CAAC,CAAC,CAAC;YACH,MAAM,MAAM,GAAG,mBAAmB,CAC9B,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,EACzF,IAAI,CACP,CAAC;YACF,IAAI,MAAM,KAAK,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC/B,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;YACtD,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;QACjF,CAAC;QAED,kFAAkF;QAClF,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QACxE,MAAM,WAAW,GAAG,GAAG,EAAE,IAAI,EAAE,WAAW,CAAC;QAC3C,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAE9B,2FAA2F;QAC3F,4FAA4F;QAC5F,4EAA4E;QAC5E,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,CAAC;QAClD,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,IAAI,EAAE,EAAE,CAAC;IAC7E,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/AdvanceOrderStateOperation.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview `Orders.AdvanceOrderState` — move a booked order up the status ladder.
+ *
+ * WHAT THIS IS FOR. Back-office entry of something that has ALREADY happened: a sale taken at a
+ * counter, a shipment that went out before anyone opened the system, a migration from whatever came
+ * before. The order needs to land in its final state without a human clicking through
+ * Confirmed → Posted → Fulfilled (D17).
+ *
+ * WHAT IT REPLACED, AND WHY IT SHRANK. This was `Orders.CreateOrderInState`, which took an
+ * `OrderDraft` — a hand-maintained mirror of the order entity — created the order by delegating to
+ * `Orders.ConfirmOrder`, and only then advanced it. Both halves of that are gone: composing and
+ * booking an order is now `order.Save()` through MJ's entity graph, which runs the identical booking
+ * walk on the server subclass. What is left is the part a save cannot do, and that part is this file.
+ *
+ * WHY THE LADDER STILL NEEDS AN OPERATION. Advancing to Posted is a plain save. Advancing to
+ * Fulfilled is not: the fulfillable LINES have to be marked first, and whether the order may move at
+ * all depends on how many could not be. That is a decision over a set of rows, taken on the server,
+ * with a caller-supplied override — a save on one header has nowhere to put it.
+ *
+ * NOTHING HERE BOOKS. Journal entries, subscriptions and entitlements are the confirm's business and
+ * have already happened by the time this runs. This operation reads the ledger back only to REPORT
+ * it, so a caller can tell "advanced an order that booked" from "advanced an order that did not".
+ *
+ * @module @mj-biz-apps/orders-core-entities-server
+ */
+import { BaseRemotableOperation, type IMetadataProvider, type UserInfo } from '@memberjunction/core';
+import { type BlockerResult, type OrderStateTransition } from '@mj-biz-apps/orders-entities';
+interface AdvanceOrderStateInput {
+    OrderHeaderID: string;
+    TargetStatus: string;
+    ForceFulfillment?: boolean;
+    Reason?: string | null;
+}
+interface AdvanceOrderStateOutput {
+    Success: boolean;
+    Message?: string | null;
+    OrderHeaderID: string | null;
+    OrderNumber: string | null;
+    Status: string | null;
+    RequestedStatus: string;
+    Transitions: OrderStateTransition[];
+    EntryCount: number;
+    AllBalanced: boolean;
+    UnfulfilledLineCount: number;
+    Blockers: BlockerResult[];
+}
+export declare class AdvanceOrderStateOperation extends BaseRemotableOperation<AdvanceOrderStateInput, AdvanceOrderStateOutput> {
+    OperationKey: string;
+    protected InternalExecute(input: AdvanceOrderStateInput, provider: IMetadataProvider, user: UserInfo): Promise<AdvanceOrderStateOutput>;
+    /**
+     * What booked against this order's lines, read back rather than assumed.
+     *
+     * The confirm happened on a different call — possibly on a different day, for a migration — so
+     * this operation has no first-hand knowledge of it. Reporting zero entries because nobody looked
+     * is indistinguishable from an order that never booked, and this whole file exists to keep those
+     * two apart.
+     */
+    private readBookedEntries;
+    /** Move the header, reporting a refusal rather than throwing — a stalled advance is still a result. */
+    private setStatus;
+    /**
+     * Mark every line that is awaiting fulfilment, and report how many would not go.
+     *
+     * The three lookups are per-order rather than per-line on purpose: a migration advances orders in
+     * bulk, and a per-line product/type round trip turns a hundred-line order into three hundred
+     * queries.
+     */
+    private fulfillLines;
+    /** The order is booked and moved as far as it could, but not as far as asked. */
+    private stopped;
+    private blocker;
+    private refuse;
+}
+/**
+ * Force the class registration. Tree-shaking removes a class nobody imports, and the decorator only
+ * runs if the module is loaded — so the server's bootstrap calls this.
+ */
+export declare function LoadAdvanceOrderStateOperation(): void;
+export {};
+//# sourceMappingURL=AdvanceOrderStateOperation.d.ts.map

package/dist/AdvanceOrderStateOperation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdvanceOrderStateOperation.d.ts","sourceRoot":"","sources":["../src/AdvanceOrderStateOperation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACH,sBAAsB,EAEtB,KAAK,iBAAiB,EAEtB,KAAK,QAAQ,EAChB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGH,KAAK,aAAa,EAClB,KAAK,oBAAoB,EAC5B,MAAM,8BAA8B,CAAC;AAmBtC,UAAU,sBAAsB;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,UAAU,uBAAuB;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,oBAAoB,EAAE,CAAC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED,qBACa,0BAA2B,SAAQ,sBAAsB,CAClE,sBAAsB,EACtB,uBAAuB,CAC1B;IACU,YAAY,SAA8B;cAEjC,eAAe,CAC3B,KAAK,EAAE,sBAAsB,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,QAAQ,GACf,OAAO,CAAC,uBAAuB,CAAC;IAoHnC;;;;;;;OAOG;YACW,iBAAiB;IA0B/B,uGAAuG;YACzF,SAAS;IAkBvB;;;;;;OAMG;YACW,YAAY;IA2D1B,iFAAiF;YACnE,OAAO;IAuBrB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,MAAM;CAqBjB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}