docs(erp-extension-readiness): define business transaction, posting, period-lock, item, and report-projection contracts #755

Parent epic: #738
Depends on: #739, #742, #746, #749, #750, #751, #753

Context

AWCMS-Mini should become a secure modular application kernel that ERP extensions can reuse. It should not become a monolithic ERP in the base repository. The safe boundary is to define neutral references, capability ports, and versioned events that an external ERP extension can implement.

The base must explicitly separate:

• tenant from legal entity and organization scope;
• SaaS service catalog/subscription billing from ERP item catalog and accounting;
• operational/payment allocation ledgers from double-entry general ledger;
• canonical party/profile from contextual customer/supplier/employee roles.

Objective

Document and validate provider-neutral ERP extension contracts and an external example fixture without adding accounting, inventory, sales, procurement, AR/AP, payroll, tax, asset, or manufacturing domain tables to AWCMS-Mini.

Scope

• Add an accepted ADR or architecture contract package defining ownership and dependency direction: base exposes contracts; ERP extension implements/consumes them; Core never depends on ERP implementation.
• Define versioned neutral contracts for:
  • business transaction reference and lifecycle metadata;
  • document/reference/numbering integration;
  • tenant/legal-entity/organization-scope references;
  • canonical party reference plus contextual role ownership in ERP modules;
  • accounting posting request/result event envelope;
  • period-lock query/check capability;
  • item/service reference;
  • currency and unit-of-measure reference;
  • inventory movement reference;
  • reconciliation reference/control totals;
  • reporting projection/read-model contribution.
• State invariants and failure semantics:
  • posted transactions are immutable;
  • corrections use reversal/compensation;
  • posting is idempotent and externally correlated;
  • period lock fails closed for posting but does not become an identity/RLS boundary;
  • request acceptance is not equivalent to successful accounting posting;
  • source modules do not write ERP tables directly.
• Define minimal OpenAPI/AsyncAPI or TypeScript/domain contract schemas where machine verification is valuable.
• Add an external/sample ERP extension fixture that:
  • composes through feat(module-assembly): add deterministic build-time composition for base and derived application modules #740/test(extension-contract): publish derived-module compatibility manifest, test kit, and semantic-version gates #741;
  • consumes party/scope/reference/document contracts;
  • receives a posting request and emits a posting result through feat(domain-events): add transactional event outbox, idempotent consumers, retries, ordering, and dead-letter handling #742;
  • contributes a reporting projection through feat(reporting): add module-contributed read models, incremental projections, freshness, and scheduled exports #753;
  • contains all ERP tables outside the base module registry/source tree.
• Add compatibility and contract tests proving dependency direction and version gates.
• Document how domain implementations may vary by jurisdiction, accounting standards, tax regime, inventory costing, and business policy.

Explicitly out of scope for the base

• Chart of accounts and journal tables.
• Double-entry posting engine.
• Inventory valuation/stock costing.
• Sales orders, purchase orders, AR/AP, cash/bank, payment allocation.
• Fixed assets, depreciation, payroll, tax calculation/reporting.
• Manufacturing, project costing, budget control, consolidation.
• Any claim that AWCMS-Mini itself is a complete or compliant ERP.

Security, integrity, and compliance requirements

• ERP extension remains tenant-isolated with RLS and business scopes verified separately.
• Posting request/result uses versioned schemas, correlation/causation IDs, idempotency, audit, and minimized PII.
• No provider or external ERP call occurs inside the source database transaction.
• Period-lock and posting authorization are default-deny when the capability is unavailable or ambiguous for a required operation.
• Cross-tenant/legal-entity reference mismatches are rejected.
• Compliance mapping references applicable Indonesian regulations and relevant ISO/OWASP/NIST controls, while domain-specific accounting/tax compliance remains the ERP extension owner's responsibility.

Acceptance criteria

• An accepted ADR/contract package clearly states that AWCMS-Mini is a technical kernel, not a functional ERP.
• All listed contract families have stable ownership, versioning, failure semantics, privacy classification, and examples.
• Base contains no chart-of-accounts, journal, inventory valuation, sales/procurement, AR/AP, payroll, tax, asset, or manufacturing tables/routes.
• Dependency tests prove Core/System do not import or depend on the example ERP extension.
• External fixture composes and passes semantic/capability compatibility gates without editing base registry.
• Posting request/result is idempotent, correlated, event-versioned, and demonstrates reversal/compensation rather than mutation of posted state.
• Period-lock and cross-tenant/legal-entity mismatch negative tests fail safely.
• Reference, document, projection, and reconciliation examples use capability/event contracts rather than shared-table writes.
• Architecture/ADR, derived-app guide, module admission, OpenAPI/AsyncAPI/generated references, data ownership matrix, security/compliance guidance, and repository inventory are updated.
• Contract fixture tests, extension compatibility checks, API/event parity, module DAG/boundary checks, and bun run check pass.