朱子纯 / vibe-erp

The killer demo finally works: place a sales order, ship it, watch
inventory drop. This chunk lands the two pieces that close the loop:
the inventory movement ledger (the audit-grade history of every
stock change) and the sales-order /ship endpoint that calls
InventoryApi.recordMovement to atomically debit stock for every line.

This is the framework's FIRST cross-PBC WRITE flow. Every earlier
cross-PBC call was a read (CatalogApi.findItemByCode,
PartnersApi.findPartnerByCode, InventoryApi.findStockBalance).
Shipping inverts that: pbc-orders-sales synchronously writes to
inventory's tables (via the api.v1 facade) as a side effect of
changing its own state, all in ONE Spring transaction.

What landed
-----------
* New `inventory__stock_movement` table — append-only ledger
  (id, item_code, location_id FK, signed delta, reason enum,
  reference, occurred_at, audit cols). CHECK constraint
  `delta <> 0` rejects no-op rows. Indexes on item_code,
  location_id, the (item, location) composite, reference, and
  occurred_at. Migration is in its own changelog file
  (002-inventory-movement-ledger.xml) per the project convention
  that each new schema cut is a new file.
* New `StockMovement` JPA entity + repository + `MovementReason`
  enum (RECEIPT, ISSUE, ADJUSTMENT, SALES_SHIPMENT, PURCHASE_RECEIPT,
  TRANSFER_OUT, TRANSFER_IN). Each value carries a documented sign
  convention; the service rejects mismatches (a SALES_SHIPMENT
  with positive delta is a caller bug, not silently coerced).
* New `StockMovementService.record(...)` — the ONE entry point for
  changing inventory. Cross-PBC item validation via CatalogApi,
  local location validation, sign-vs-reason enforcement, and
  negative-balance rejection all happen BEFORE the write. The
  ledger row insert AND the balance row update happen in the
  SAME database transaction so the two cannot drift.
* `StockBalanceService.adjust` refactored to delegate: it computes
  delta = newQty - oldQty and calls record(... ADJUSTMENT). The
  REST endpoint keeps its absolute-quantity semantics — operators
  type "the shelf has 47" not "decrease by 3" — but every
  adjustment now writes a ledger row too. A no-op adjustment
  (re-saving the same value) does NOT write a row, so the audit
  log doesn't fill with noise from operator clicks that didn't
  change anything.
* New `StockMovementController` at `/api/v1/inventory/movements`:
  GET filters by itemCode, locationId, or reference (for "all
  movements caused by SO-2026-0001"); POST records a manual
  movement. Both protected by `inventory.stock.adjust`.
* `InventoryApi` facade extended with `recordMovement(itemCode,
  locationCode, delta, reason: String, reference)`. The reason is
  a String in the api.v1 surface (not the local enum) so plug-ins
  don't import inventory's internal types — the closed set is
  documented on the interface. The adapter parses the string with
  a meaningful error on unknown values.
* New `SHIPPED` status on `SalesOrderStatus`. Transitions:
  DRAFT → CONFIRMED → SHIPPED (terminal). Cancelling a SHIPPED
  order is rejected with "issue a return / refund flow instead".
* New `SalesOrderService.ship(id, shippingLocationCode)`: walks
  every line, calls `inventoryApi.recordMovement(... -line.quantity
  reason="SALES_SHIPMENT" reference="SO:{order_code}")`, flips
  status to SHIPPED. The whole operation runs in ONE transaction
  so a failure on any line — bad item, bad location, would push
  balance negative — rolls back the order status change AND every
  other line's already-written movement. The customer never ends
  up with "5 of 7 lines shipped, status still CONFIRMED, ledger
  half-written".
* New `POST /api/v1/orders/sales-orders/{id}/ship` endpoint with
  body `{"shippingLocationCode": "WH-MAIN"}`, gated by the new
  `orders.sales.ship` permission key.
* `ShipSalesOrderRequest` is a single-arg Kotlin data class — same
  Jackson deserialization trap as `RefreshRequest`. Fixed with
  `@JsonCreator(mode = PROPERTIES) + @param:JsonProperty`. The
  trap is documented in the class KDoc.

End-to-end smoke test (the killer demo)
---------------------------------------
Reset Postgres, booted the app, ran:
* Login as admin
* POST /catalog/items → PAPER-A4
* POST /partners → CUST-ACME
* POST /inventory/locations → WH-MAIN
* POST /inventory/balances/adjust → quantity=1000
  (now writes a ledger row via the new path)
* GET /inventory/movements?itemCode=PAPER-A4 →
  ADJUSTMENT delta=1000 ref=null
* POST /orders/sales-orders → SO-2026-0001 (50 units of PAPER-A4)
* POST /sales-orders/{id}/confirm → status CONFIRMED
* POST /sales-orders/{id}/ship body={"shippingLocationCode":"WH-MAIN"}
  → status SHIPPED
* GET /inventory/balances?itemCode=PAPER-A4 → quantity=950
  (1000 - 50)
* GET /inventory/movements?itemCode=PAPER-A4 →
  ADJUSTMENT     delta=1000   ref=null
  SALES_SHIPMENT delta=-50    ref=SO:SO-2026-0001

Failure paths verified:
* Re-ship a SHIPPED order → 400 "only CONFIRMED orders can be shipped"
* Cancel a SHIPPED order → 400 "issue a return / refund flow instead"
* Place a 10000-unit order, confirm, try to ship from a 950-stock
  warehouse → 400 "stock movement would push balance for 'PAPER-A4'
  at location ... below zero (current=950.0000, delta=-10000.0000)";
  balance unchanged after the rollback (transaction integrity
  verified)

Regression: catalog uoms, identity users, inventory locations,
printing-shop plates with i18n, metadata entities — all still
HTTP 2xx.

Build
-----
* `./gradlew build`: 15 subprojects, 175 unit tests (was 163),
  all green. The 12 new tests cover:
  - StockMovementServiceTest (8): zero-delta rejection, positive
    SALES_SHIPMENT rejection, negative RECEIPT rejection, both
    signs allowed on ADJUSTMENT, unknown item via CatalogApi seam,
    unknown location, would-push-balance-negative rejection,
    new-row + existing-row balance update.
  - StockBalanceServiceTest, rewritten (5): negative-quantity
    early reject, delegation with computed positive delta,
    delegation with computed negative delta, no-op adjustment
    short-circuit (NO ledger row written), no-op on missing row
    creates an empty row at zero.
  - SalesOrderServiceTest, additions (3): ship rejects non-CONFIRMED,
    ship walks lines and calls recordMovement with negated quantity
    + correct reference, cancel rejects SHIPPED.

What was deferred
-----------------
* **Event publication.** A `StockMovementRecorded` event would
  let pbc-finance and pbc-production react to ledger writes
  without polling. The event bus has been wired since P1.7 but
  no real cross-PBC flow uses it yet — that's the natural next
  chunk and the chunk after this commit.
* **Multi-leg transfers.** TRANSFER_OUT and TRANSFER_IN are in
  the enum but no service operation atomically writes both legs
  yet (both legs in one transaction is required to keep total
  on-hand invariant).
* **Reservation / pick lists.** "Reserve 50 of PAPER-A4 for an
  unconfirmed order" is its own concept that lands later.
* **Shipped-order returns / refunds.** The cancel-SHIPPED rule
  points the user at "use a return flow" — that flow doesn't
  exist yet. v1 says shipments are terminal.

The framework's authorization layer is now live. Until now, every
authenticated user could do everything; the framework had only an
authentication gate. This chunk adds method-level @RequirePermission
annotations enforced by a Spring AOP aspect that consults the JWT's
roles claim and a metadata-driven role-permission map.

What landed
-----------
* New `Role` and `UserRole` JPA entities mapping the existing
  identity__role + identity__user_role tables (the schema was
  created in the original identity init but never wired to JPA).
  RoleJpaRepository + UserRoleJpaRepository with a JPQL query that
  returns a user's role codes in one round-trip.
* `JwtIssuer.issueAccessToken(userId, username, roles)` now accepts a
  Set<String> of role codes and encodes them as a `roles` JWT claim
  (sorted for deterministic tests). Refresh tokens NEVER carry roles
  by design — see the rationale on `JwtIssuer.issueRefreshToken`. A
  role revocation propagates within one access-token lifetime
  (15 min default).
* `JwtVerifier` reads the `roles` claim into `DecodedToken.roles`.
  Missing claim → empty set, NOT an error (refresh tokens, system
  tokens, and pre-P4.3 tokens all legitimately omit it).
* `AuthService.login` now calls `userRoles.findRoleCodesByUserId(...)`
  before minting the access token. `AuthService.refresh` re-reads
  the user's roles too — so a refresh always picks up the latest
  set, since refresh tokens deliberately don't carry roles.
* New `AuthorizationContext` ThreadLocal in `platform-security.authz`
  carrying an `AuthorizedPrincipal(id, username, roles)`. Separate
  from `PrincipalContext` (which lives in platform-persistence and
  carries only the principal id, for the audit listener). The two
  contexts coexist because the audit listener has no business
  knowing what roles a user has.
* `PrincipalContextFilter` now populates BOTH contexts on every
  authenticated request, reading the JWT's `username` and `roles`
  claims via `Jwt.getClaimAsStringList("roles")`. The filter is the
  one and only place that knows about Spring Security types AND
  about both vibe_erp contexts; everything downstream uses just the
  Spring-free abstractions.
* `PermissionEvaluator` Spring bean: takes a role set + permission
  key, returns boolean. Resolution chain:
  1. The literal `admin` role short-circuits to `true` for every
     key (the wildcard exists so the bootstrap admin can do
     everything from the very first boot without seeding a complete
     role-permission mapping).
  2. Otherwise consults an in-memory `Map<role, Set<permission>>`
     loaded from `metadata__role_permission` rows. The cache is
     rebuilt by `refresh()`, called from `VibeErpPluginManager`
     after the initial core load AND after every plug-in load.
  3. Empty role set is always denied. No implicit grants.
* `@RequirePermission("...")` annotation in `platform-security.authz`.
  `RequirePermissionAspect` is a Spring AOP @Aspect with @Around
  advice that intercepts every annotated method, reads the current
  request's `AuthorizationContext`, calls
  `PermissionEvaluator.has(...)`, and either proceeds or throws
  `PermissionDeniedException`.
* New `PermissionDeniedException` carrying the offending key.
  `GlobalExceptionHandler` maps it to HTTP 403 Forbidden with
  `"permission denied: 'partners.partner.deactivate'"` as the
  detail. The key IS surfaced to the caller (unlike the 401's
  generic "invalid credentials") because the SPA needs it to
  render a useful "your role doesn't include X" message and
  callers are already authenticated, so it's not an enumeration
  vector.
* `BootstrapAdminInitializer` now creates the wildcard `admin`
  role on first boot and grants it to the bootstrap admin user.
* `@RequirePermission` applied to four sensitive endpoints as the
  demo: `PartnerController.deactivate`,
  `StockBalanceController.adjust`, `SalesOrderController.confirm`,
  `SalesOrderController.cancel`. More endpoints will gain
  annotations as additional roles are introduced; v1 keeps the
  blast radius narrow.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, verified:
* Admin login → JWT length 265 (was 241), decoded claims include
  `"roles":["admin"]`
* Admin POST /sales-orders/{id}/confirm → 200, status DRAFT → CONFIRMED
  (admin wildcard short-circuits the permission check)
* Inserted a 'powerless' user via raw SQL with no role assignments
  but copied the admin's password hash so login works
* Powerless login → JWT length 247, decoded claims have NO roles
  field at all
* Powerless POST /sales-orders/{id}/cancel → **403 Forbidden** with
  `"permission denied: 'orders.sales.cancel'"` in the body
* Powerless DELETE /partners/{id} → **403 Forbidden** with
  `"permission denied: 'partners.partner.deactivate'"`
* Powerless GET /sales-orders, /partners, /catalog/items → all 200
  (read endpoints have no @RequirePermission)
* Admin regression: catalog uoms, identity users, inventory
  locations, printing-shop plates with i18n, metadata custom-fields
  endpoint — all still HTTP 2xx

Build
-----
* `./gradlew build`: 15 subprojects, 163 unit tests (was 153),
  all green. The 10 new tests cover:
  - PermissionEvaluator: empty roles deny, admin wildcard, explicit
    role-permission grant, multi-role union, unknown role denial,
    malformed payload tolerance, currentHas with no AuthorizationContext,
    currentHas with bound context (8 tests).
  - JwtRoundTrip: roles claim round-trips through the access token,
    refresh token never carries roles even when asked (2 tests).

What was deferred
-----------------
* **OIDC integration (P4.2)**. Built-in JWT only. The Keycloak-
  compatible OIDC client will reuse the same authorization layer
  unchanged — the roles will come from OIDC ID tokens instead of
  the local user store.
* **Permission key validation at boot.** The framework does NOT
  yet check that every `@RequirePermission` value matches a
  declared metadata permission key. The plug-in linter is the
  natural place for that check to land later.
* **Role hierarchy**. Roles are flat in v1; a role with permission
  X cannot inherit from another role. Adding a `parent_role` field
  on the role row is a non-breaking change later.
* **Resource-aware permissions** ("the user owns THIS partner").
  v1 only checks the operation, not the operand. Resource-aware
  checks are post-v1.
* **Composite (AND/OR) permission requirements**. A single key
  per call site keeps the contract simple. Composite requirements
  live in service code that calls `PermissionEvaluator.currentHas`
  directly.
* **Role management UI / REST**. The framework can EVALUATE
  permissions but has no first-class endpoints for "create a
  role", "grant a permission to a role", "assign a role to a
  user". v1 expects these to be done via direct DB writes or via
  the future SPA's role editor (P3.x); the wiring above is
  intentionally policy-only, not management.

The fifth real PBC and the first business workflow PBC. pbc-inventory
proved a PBC could consume ONE cross-PBC facade (CatalogApi).
pbc-orders-sales consumes TWO simultaneously (PartnersApi for the
customer, CatalogApi for every line's item) in a single transaction —
the most rigorous test of the modular monolith story so far. Neither
source PBC is on the compile classpath; the Gradle build refuses any
direct dependency. Spring DI wires the api.v1 interfaces to their
concrete adapters at runtime.

What landed
-----------
* New Gradle subproject `pbc/pbc-orders-sales` (15 modules total).
* Two JPA entities, both extending `AuditedJpaEntity`:
  - `SalesOrder` (header) — code, partner_code (varchar, NOT a UUID
    FK to partners), status enum DRAFT/CONFIRMED/CANCELLED, order_date,
    currency_code (varchar(3)), total_amount numeric(18,4),
    ext jsonb. Eager-loaded `lines` collection because every read of
    the header is followed by a read of the lines in practice.
  - `SalesOrderLine` — sales_order_id FK, line_no, item_code (varchar,
    NOT a UUID FK to catalog), quantity, unit_price, currency_code.
    Per-line currency in the schema even though v1 enforces all-lines-
    match-header (so multi-currency relaxation is later schema-free).
    No `ext` jsonb on lines: lines are facts, not master records;
    custom fields belong on the header.
* `SalesOrderService.create` performs **three independent
  cross-PBC validations** in one transaction:
  1. PartnersApi.findPartnerByCode → reject if null (covers unknown
     AND inactive partners; the facade hides them).
  2. PartnersApi result.type must be CUSTOMER or BOTH (a SUPPLIER-only
     partner cannot be the customer of a sales order).
  3. CatalogApi.findItemByCode for EVERY line → reject if null.
  Then it ALSO validates: at least one line, no duplicate line numbers,
  positive quantity, non-negative price, currency matches header.
  The header total is RECOMPUTED from the lines — the caller's value
  is intentionally ignored. Never trust a financial aggregate sent
  over the wire.
* State machine enforced by `confirm()` and `cancel()`:
  - DRAFT → CONFIRMED   (confirm)
  - DRAFT → CANCELLED   (cancel from draft)
  - CONFIRMED → CANCELLED (cancel a confirmed order)
  Anything else throws with a descriptive message. CONFIRMED orders
  are immutable except for cancellation — the `update` method refuses
  to mutate a non-DRAFT order.
* `update` with line items REPLACES the existing lines wholesale
  (PUT semantics for lines, PATCH for header columns). Partial line
  edits are not modelled because the typical "edit one line" UI
  gesture renders to a full re-send anyway.
* REST: `/api/v1/orders/sales-orders` (CRUD + `/confirm` + `/cancel`).
  State transitions live on dedicated POST endpoints rather than
  PATCH-based status writes — they have side effects (lines become
  immutable, downstream PBCs will receive events in future versions),
  and sentinel-status writes hide that.
* New api.v1 facade `org.vibeerp.api.v1.ext.orders.SalesOrdersApi`
  with `findByCode`, `findById`, `SalesOrderRef`, `SalesOrderLineRef`.
  Fifth ext.* package after identity, catalog, partners, inventory.
  Sets up the next consumers: pbc-production for work orders, pbc-finance
  for invoicing, the printing-shop reference plug-in for the
  quote-to-job-card workflow.
* `SalesOrdersApiAdapter` runtime implementation. Cancelled orders ARE
  returned by the facade (unlike inactive items / partners which are
  hidden) because downstream consumers may legitimately need to react
  to a cancellation — release a production slot, void an invoice, etc.
* `orders-sales.yml` metadata declaring 2 entities, 5 permission keys,
  1 menu entry.

Build enforcement (still load-bearing)
--------------------------------------
The root `build.gradle.kts` STILL refuses any direct dependency from
`pbc-orders-sales` to either `pbc-partners` or `pbc-catalog`. Try
adding either as `implementation(project(...))` and the build fails
at configuration time with the architectural violation. The
cross-PBC interfaces live in api-v1; the concrete adapters live in
their owning PBCs; Spring DI assembles them at runtime via the
bootstrap @ComponentScan. pbc-orders-sales sees only the api.v1
interfaces.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, hit:
* POST /api/v1/catalog/items × 2  → PAPER-A4, INK-CYAN
* POST /api/v1/partners/partners → CUST-ACME (CUSTOMER), SUP-ONLY (SUPPLIER)
* POST /api/v1/orders/sales-orders → 201, two lines, total 386.50
  (5000 × 0.05 + 3 × 45.50 = 250.00 + 136.50, correctly recomputed)
* POST .../sales-orders with FAKE-PARTNER → 400 with the meaningful
  message "partner code 'FAKE-PARTNER' is not in the partners
  directory (or is inactive)"
* POST .../sales-orders with SUP-ONLY → 400 "partner 'SUP-ONLY' is
  type SUPPLIER and cannot be the customer of a sales order"
* POST .../sales-orders with FAKE-ITEM line → 400 "line 1: item code
  'FAKE-ITEM' is not in the catalog (or is inactive)"
* POST /{id}/confirm → status DRAFT → CONFIRMED
* PATCH the CONFIRMED order → 400 "only DRAFT orders are mutable"
* Re-confirm a CONFIRMED order → 400 "only DRAFT can be confirmed"
* POST /{id}/cancel a CONFIRMED order → status CANCELLED (allowed)
* SELECT * FROM orders_sales__sales_order — single row, total
  386.5000, status CANCELLED
* SELECT * FROM orders_sales__sales_order_line — two rows in line_no
  order with the right items and quantities
* GET /api/v1/_meta/metadata/entities → 13 entities now (was 11)
* Regression: catalog uoms, identity users, partners, inventory
  locations, printing-shop plates with i18n (Accept-Language: zh-CN)
  all still HTTP 2xx.

Build
-----
* `./gradlew build`: 15 subprojects, 153 unit tests (was 139),
  all green. The 14 new tests cover: unknown/SUPPLIER-only/BOTH-type
  partner paths, unknown item path, empty/duplicate-lineno line
  arrays, negative-quantity early reject (verifies CatalogApi NOT
  consulted), currency mismatch reject, total recomputation, all
  three state-machine transitions and the rejected ones.

What was deferred
-----------------
* **Sales-order shipping**. Confirmed orders cannot yet ship, because
  shipping requires atomically debiting inventory — which needs the
  movement ledger that was deferred from P5.3. The pair of chunks
  (movement ledger + sales-order shipping flow) is the natural next
  combination.
* **Multi-currency lines**. The schema column is per-line but the
  service enforces all-lines-match-header in v1. Relaxing this is a
  service-only change.
* **Quotes** (DRAFT-but-customer-visible) and **deliveries** (the
  thing that triggers shipping). v1 only models the order itself.
* **Pricing engine / discounts**. v1 takes the unit price the caller
  sends. A real ERP has a price book lookup, customer-specific
  pricing, volume discounts, promotional pricing — all of which slot
  in BEFORE the line price is set, leaving the schema unchanged.
* **Tax**. v1 totals are pre-tax. Tax calculation is its own PBC
  (and a regulatory minefield) that lands later.

The fourth real PBC, and the first one that CONSUMES another PBC's
api.v1.ext facade. Until now every PBC was a *provider* of an
ext.<pbc> interface (identity, catalog, partners). pbc-inventory is
the first *consumer*: it injects org.vibeerp.api.v1.ext.catalog.CatalogApi
to validate item codes before adjusting stock. This proves the
cross-PBC contract works in both directions, exactly as guardrail #9
requires.

What landed
-----------
* New Gradle subproject `pbc/pbc-inventory` (14 modules total now).
* Two JPA entities, both extending `AuditedJpaEntity`:
  - `Location` — code, name, type (WAREHOUSE/BIN/VIRTUAL), active,
    ext jsonb. Single table for all location levels with a type
    discriminator (no recursive self-reference in v1; YAGNI for the
    "one warehouse, handful of bins" shape every printing shop has).
  - `StockBalance` — item_code (varchar, NOT a UUID FK), location_id
    FK, quantity numeric(18,4). The item_code is deliberately a
    string FK that references nothing because pbc-inventory has no
    compile-time link to pbc-catalog — the cross-PBC link goes
    through CatalogApi at runtime. UNIQUE INDEX on
    (item_code, location_id) is the primary integrity guarantee;
    UUID id is the addressable PK. CHECK (quantity >= 0).
* `LocationService` and `StockBalanceService` with full CRUD +
  adjust semantics. ext jsonb on Location goes through ExtJsonValidator
  (P3.4 — Tier 1 customisation).
* `StockBalanceService.adjust(itemCode, locationId, quantity)`:
  1. Reject negative quantity.
  2. **Inject CatalogApi**, call `findItemByCode(itemCode)`, reject
     if null with a meaningful 400. THIS is the cross-PBC seam test.
  3. Verify the location exists.
  4. SELECT-then-save upsert on (item_code, location_id) — single
     row per cell, mutated in place when the row exists, created
     when it doesn't. Single-instance deployment makes the
     read-modify-write race window academic.
* REST: `/api/v1/inventory/locations` (CRUD), `/api/v1/inventory/balances`
  (GET with itemCode or locationId filters, POST /adjust).
* New api.v1 facade `org.vibeerp.api.v1.ext.inventory` with
  `InventoryApi.findStockBalance(itemCode, locationCode)` +
  `totalOnHand(itemCode)` + `StockBalanceRef`. Fourth ext.* package
  after identity, catalog, partners. Sets up the next consumers
  (sales orders, purchase orders, the printing-shop plug-in's
  "do we have enough paper for this job?").
* `InventoryApiAdapter` runtime implementation in pbc-inventory.
* `inventory.yml` metadata declaring 2 entities, 6 permission keys,
  2 menu entries.

Build enforcement (the load-bearing bit)
----------------------------------------
The root build.gradle.kts STILL refuses any direct dependency from
pbc-inventory to pbc-catalog. Try adding `implementation(project(
":pbc:pbc-catalog"))` to pbc-inventory's build.gradle.kts and the
build fails at configuration time with "Architectural violation in
:pbc:pbc-inventory: depends on :pbc:pbc-catalog". The CatalogApi
interface is in api-v1; the CatalogApiAdapter implementation is in
pbc-catalog; Spring DI wires them at runtime via the bootstrap
@ComponentScan. pbc-inventory only ever sees the interface.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, hit:
* POST /api/v1/inventory/locations → 201, "WH-MAIN" warehouse
* POST /api/v1/catalog/items → 201, "PAPER-A4" sheet item
* POST /api/v1/inventory/balances/adjust with itemCode=PAPER-A4 → 200,
  the cross-PBC catalog lookup succeeded
* POST .../adjust with itemCode=FAKE-ITEM → 400 with the meaningful
  message "item code 'FAKE-ITEM' is not in the catalog (or is inactive)"
  — the cross-PBC seam REJECTS unknown items as designed
* POST .../adjust with quantity=-5 → 400 "stock quantity must be
  non-negative", caught BEFORE the CatalogApi mock would be invoked
* POST .../adjust again with quantity=7500 → 200; SELECT shows ONE
  row with id unchanged and quantity = 7500 (upsert mutates, not
  duplicates)
* GET /api/v1/inventory/balances?itemCode=PAPER-A4 → the row, with
  scale-4 numeric serialised verbatim
* GET /api/v1/_meta/metadata/entities → 11 entities now (was 9 before
  Location + StockBalance landed)
* Regression: catalog uoms, identity users, partners, printing-shop
  plates with i18n (Accept-Language: zh-CN), Location custom-fields
  endpoint all still HTTP 2xx.

Build
-----
* `./gradlew build`: 14 subprojects, 139 unit tests (was 129),
  all green. The 10 new tests cover Location CRUD + the StockBalance
  adjust path with mocked CatalogApi: unknown item rejection, unknown
  location rejection, negative-quantity early reject (verifies
  CatalogApi is NOT consulted), happy-path create, and upsert
  (existing row mutated, save() not called because @Transactional
  flushes the JPA-managed entity on commit).

What was deferred
-----------------
* `inventory__stock_movement` append-only ledger. The current operation
  is "set the quantity"; receipts/issues/transfers as discrete events
  with audit trail land in a focused follow-up. The balance row will
  then be regenerated from the ledger via a Liquibase backfill.
* Negative-balance / over-issue prevention. The CHECK constraint
  blocks SET to a negative value, but there's no concept of "you
  cannot ISSUE more than is on hand" yet because there is no
  separate ISSUE operation — only absolute SET.
* Lots, batches, serial numbers, expiry dates. Plenty of printing
  shops need none of these; the ones that do can either wait for
  the lot/serial chunk later or add the columns via Tier 1 custom
  fields on Location for now.
* Cross-warehouse transfer atomicity (debit one, credit another in
  one transaction). Same — needs the ledger.

The keystone of the framework's "key user adds fields without code"
promise. A YAML declaration is now enough to add a typed custom field
to an existing entity, validate it on every save, and surface it to
the SPA / OpenAPI / AI agent. This is the bit that makes vibe_erp a
*framework* instead of a fork-per-customer app.

What landed
-----------
* Extended `MetadataYamlFile` with a top-level `customFields:` section
  and `CustomFieldYaml` + `CustomFieldTypeYaml` wire-format DTOs. The
  YAML uses a flat `kind: decimal / scale: 2` discriminator instead of
  Jackson polymorphic deserialization so plug-in authors don't have to
  nest type configs and api.v1's `FieldType` stays free of Jackson
  imports.
* `MetadataLoader.doLoad` now upserts `metadata__custom_field` rows
  alongside entities/permissions/menus, with the same delete-by-source
  idempotency. `LoadResult` carries the count for the boot log.
* `CustomFieldRegistry` reads every `metadata__custom_field` row from
  the database and builds an in-memory `Map<entityName, List<CustomField>>`
  for the validator's hot path. `refresh()` is called by
  `VibeErpPluginManager` after the initial core load AND after every
  plug-in load, so a freshly-installed plug-in's custom fields are
  immediately enforceable. ConcurrentHashMap under the hood; reads
  are lock-free.
* `ExtJsonValidator` is the on-save half: takes (entityName, ext map),
  walks the declared fields, coerces each value to its native type,
  and returns the canonicalised map (or throws IllegalArgumentException
  with ALL violations joined for a single 400). Per-FieldType rules:
  - String: maxLength enforced.
  - Integer: accepts Number and numeric String, rejects garbage.
  - Decimal: precision/scale enforced; preserved as plain string in
    canonical form so JSON encoding doesn't lose trailing zeros.
  - Boolean: accepts true/false (case-insensitive).
  - Date / DateTime: ISO-8601 parse via java.time.
  - Uuid: java.util.UUID parse.
  - Enum: must be in declared `allowedValues`.
  - Money / Quantity / Json / Reference: pass-through (Reference target
    existence check pending the cross-PBC EntityRegistry seam).
  Unknown ext keys are rejected with the entity's name and the keys
  themselves listed. ALL violations are returned in one response, not
  failing on the first, so a form submitter fixes everything in one
  round-trip.
* `Partner` is the first PBC entity to wire ext through the validator:
  `CreatePartnerRequest` and `UpdatePartnerRequest` accept an
  `ext: Map<String, Any?>?`; `PartnerService.create/update` calls
  `extValidator.validate("Partner", ext)` and persists the canonical
  JSON to the existing `partners__partner.ext` JSONB column;
  `PartnerResponse` parses it back so callers see what they wrote.
* `partners.yml` now declares two custom fields on Partner —
  `partners_credit_limit` (Decimal precision=14, scale=2) and
  `partners_industry` (Enum of printing/publishing/packaging/other) —
  with English and Chinese labels. Tagged `source=core` so the
  framework has something to demo from a fresh boot.
* New public `GET /api/v1/_meta/metadata/custom-fields/{entityName}`
  endpoint serves the api.v1 runtime view of declarations from the
  in-memory registry (so it reflects every refresh) for the SPA's form
  builder, the OpenAPI generator, and the AI agent function catalog.
  The existing `GET /api/v1/_meta/metadata` endpoint also gained a
  `customFields` list.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, verified:
* Boot log: `CustomFieldRegistry: refreshed 2 custom fields across 1
  entities (0 malformed rows skipped)` — twice (after core load and
  after plug-in load).
* `GET /api/v1/_meta/metadata/custom-fields/Partner` → both declarations
  with their labels.
* `POST /api/v1/partners/partners` with `ext = {credit_limit: "50000.00",
  industry: "printing"}` → 201; the response echoes the canonical map.
* `POST` with `ext = {credit_limit: "1.234", industry: "unicycles",
  rogue: "x"}` → 400 with all THREE violations in one body:
  "ext contains undeclared key(s) for 'Partner': [rogue]; ext.partners_credit_limit:
  decimal scale 3 exceeds declared scale 2; ext.partners_industry:
  value 'unicycles' is not in allowed set [printing, publishing,
  packaging, other]".
* `SELECT ext FROM partners__partner WHERE code = 'CUST-EXT-OK'` →
  `{"partners_industry": "printing", "partners_credit_limit": "50000.00"}`
  — the canonical JSON is in the JSONB column verbatim.
* Regression: catalog uoms, identity users, partners list, and the
  printing-shop plug-in's POST /plates (with i18n via Accept-Language:
  zh-CN) all still HTTP 2xx.

Build
-----
* `./gradlew build`: 13 subprojects, 129 unit tests (was 118), all
  green. The 11 new tests cover each FieldType variant, multi-violation
  reporting, required missing rejection, unknown key rejection, and the
  null-value-dropped case.

What was deferred
-----------------
* JPA listener auto-validation. Right now PartnerService explicitly
  calls extValidator.validate(...) before save; Item, Uom, User and
  the plug-in tables don't yet. Promoting the validator to a JPA
  PrePersist/PreUpdate listener attached to a marker interface
  HasExt is the right next step but is its own focused chunk.
* Reference target existence check. FieldType.Reference passes
  through unchanged because the cross-PBC EntityRegistry that would
  let the validator look up "does an instance with this id exist?"
  is a separate seam landing later.
* The customization UI (Tier 1 self-service add a field via the SPA)
  is P3.3 — the runtime enforcement is done, the editor is not.
* Custom-field-aware permissions. The `pii: true` flag is in the
  metadata but not yet read by anything; the DSAR/erasure pipeline
  that will consume it is post-v1.0.

The third real PBC. Validates the modular-monolith template against a
parent-with-children aggregate (Partner → Addresses → Contacts), where
the previous two PBCs only had single-table or two-independent-table
shapes.

What landed
-----------
* New Gradle subproject `pbc/pbc-partners` (12 modules total now).
* Three JPA entities, all extending `AuditedJpaEntity`:
  - `Partner` — code, name, type (CUSTOMER/SUPPLIER/BOTH), tax_id,
    website, email, phone, active, ext jsonb. Single-table for both
    customers and suppliers because the role flag is a property of
    the relationship, not the organisation.
  - `Address` — partner_id FK, address_type (BILLING/SHIPPING/OTHER),
    line1/line2/city/region/postal_code/country_code (ISO 3166-1),
    is_primary. Two free address lines + structured city/region/code
    is the smallest set that round-trips through every postal system.
  - `Contact` — partner_id FK, full_name, role, email, phone, active.
    PII-tagged in metadata YAML for the future audit/export tooling.
* Spring Data JPA repos, application services with full CRUD and the
  invariants below, REST controllers under
  `/api/v1/partners/partners` (+ nested addresses, contacts).
* `partners-init.xml` Liquibase changelog with the three tables, FKs,
  GIN index on `partner.ext`, indexes on type/active/country.
* New api.v1 facade `org.vibeerp.api.v1.ext.partners` with
  `PartnersApi` + `PartnerRef`. Third `ext.<pbc>` after identity and
  catalog. Inactive partners hidden at the facade boundary.
* `PartnersApiAdapter` runtime implementation in pbc-partners, never
  leaking JPA entity types.
* `partners.yml` metadata declaring all 3 entities, 12 permission
  keys, 1 menu entry. Picked up automatically by `MetadataLoader`.
* 15 new unit tests across `PartnerServiceTest`, `AddressServiceTest`
  and `ContactServiceTest` (mockk-based, mirroring catalog tests).

Invariants enforced in code (not blindly delegated to the DB)
-------------------------------------------------------------
* Partner code uniqueness — explicit check produces a 400 with a real
  message instead of a 500 from the unique-index violation.
* Partner code is NOT updatable — every external reference uses code,
  so renaming is a data-migration concern, not an API call.
* Partner deactivate cascades to contacts (also flipped to inactive).
  Addresses are NOT touched (no `active` column — they exist or they
  don't). Verified end-to-end against Postgres.
* "Primary" flag is at most one per (partner, address_type). When a
  new/updated address is marked primary, all OTHER primaries of the
  same type for the same partner are demoted in the same transaction.
* Addresses and contacts reject operations on unknown partners
  up-front to give better errors than the FK-violation.

End-to-end smoke test
---------------------
Reset Postgres, booted the app, hit:
* POST /api/v1/auth/login (admin) → JWT
* POST /api/v1/partners/partners (CUSTOMER, SUPPLIER) → 201
* GET  /api/v1/partners/partners → lists both
* GET  /api/v1/partners/partners/by-code/CUST-ACME → resolves
* POST /api/v1/partners/partners (dup code) → 400 with real message
* POST .../{id}/addresses (BILLING, primary) → 201
* POST .../{id}/contacts → 201
* DELETE /api/v1/partners/partners/{id} → 204; partner active=false
* GET  .../contacts → contact ALSO active=false (cascade verified)
* GET  /api/v1/_meta/metadata/entities → 3 partners entities present
* GET  /api/v1/_meta/metadata/permissions → 12 partners permissions
* Regression: catalog UoMs/items, identity users, printing-shop
  plug-in plates all still HTTP 200.

Build
-----
* `./gradlew build`: 12 subprojects, 107 unit tests, all green
  (was 11 / 92 before this commit).
* The architectural rule still enforced: pbc-partners depends on
  api-v1 + platform-persistence + platform-security only — no
  cross-PBC dep, no platform-bootstrap dep.

What was deferred
-----------------
* Permission enforcement on contact endpoints (P4.3). Currently plain
  authenticated; the metadata declares the planned `partners.contact.*`
  keys for when @RequirePermission lands.
* Per-country address structure layered on top via metadata forms
  (P3.x). The current schema is the smallest universal subset.
* `deletePartnerCompletely` — out of scope for v1; should be a
  separate "data scrub" admin tool, not a routine API call.

Adds the foundation for the entire Tier 1 customization story. Core
PBCs and plug-ins now ship YAML files declaring their entities,
permissions, and menus; a `MetadataLoader` walks the host classpath
and each plug-in JAR at boot, upserts the rows tagged with their
source, and exposes them at a public REST endpoint so the future
SPA, AI-agent function catalog, OpenAPI generator, and external
introspection tooling can all see what the framework offers without
scraping code.

What landed:

* New `platform/platform-metadata/` Gradle subproject. Depends on
  api-v1 + platform-persistence + jackson-yaml + spring-jdbc.

* `MetadataYamlFile` DTOs (entities, permissions, menus). Forward-
  compatible: unknown top-level keys are ignored, so a future plug-in
  built against a newer schema (forms, workflows, rules, translations)
  loads cleanly on an older host that doesn't know those sections yet.

* `MetadataLoader` with two entry points:

    loadCore() — uses Spring's PathMatchingResourcePatternResolver
      against the host classloader. Finds every classpath*:META-INF/
      vibe-erp/metadata/*.yml across all jars contributing to the
      application. Tagged source='core'.

    loadFromPluginJar(pluginId, jarPath) — opens ONE specific
      plug-in JAR via java.util.jar.JarFile and walks its entries
      directly. This is critical: a plug-in's PluginClassLoader is
      parent-first, so a classpath*: scan against it would ALSO
      pick up the host's metadata files via parent classpath. We
      saw this in the first smoke run — the plug-in source ended
      up with 6 entities (the plug-in's 2 + the host's 4) before
      the fix. Walking the JAR file directly guarantees only the
      plug-in's own files load. Tagged source='plugin:<id>'.

  Both entry points use the same delete-then-insert idempotent core
  (doLoad). Loading the same source twice produces the same final
  state. User-edited metadata (source='user') is NEVER touched by
  either path — it survives boot, plug-in install, and plug-in
  upgrade. This is what lets a future SPA "Customize" UI add custom
  fields without fearing they'll be wiped on the next deploy.

* `VibeErpPluginManager.afterPropertiesSet()` now calls
  metadataLoader.loadCore() at the very start, then walks plug-ins
  and calls loadFromPluginJar(...) for each one between Liquibase
  migration and start(context). Order is guaranteed: core → linter
  → migrate → metadata → start. The CommandLineRunner I originally
  put `loadCore()` in turned out to be wrong because Spring runs
  CommandLineRunners AFTER InitializingBean.afterPropertiesSet(),
  so the plug-in metadata was loading BEFORE core — the wrong way
  around. Calling loadCore() inline in the plug-in manager fixes
  the ordering without any @Order(...) gymnastics.

* `MetadataController` exposes:
    GET /api/v1/_meta/metadata           — all three sections
    GET /api/v1/_meta/metadata/entities  — entities only
    GET /api/v1/_meta/metadata/permissions
    GET /api/v1/_meta/metadata/menus
  Public allowlist (covered by the existing /api/v1/_meta/** rule
  in SecurityConfiguration). The metadata is intentionally non-
  sensitive — entity names, permission keys, menu paths. Nothing
  in here is PII or secret; the SPA needs to read it before the
  user has logged in.

* YAML files shipped:
  - pbc-identity/META-INF/vibe-erp/metadata/identity.yml
    (User + Role entities, 6 permissions, Users + Roles menus)
  - pbc-catalog/META-INF/vibe-erp/metadata/catalog.yml
    (Item + Uom entities, 7 permissions, Items + UoMs menus)
  - reference plug-in/META-INF/vibe-erp/metadata/printing-shop.yml
    (Plate + InkRecipe entities, 5 permissions, Plates + Inks menus
    in a "Printing shop" section)

Tests: 4 MetadataLoaderTest cases (loadFromPluginJar happy paths,
mixed sections, blank pluginId rejection, missing-file no-op wipe)
+ 7 MetadataYamlParseTest cases (DTO mapping, optional fields,
section defaults, forward-compat unknown keys). Total now
**92 unit tests** across 11 modules, all green.

End-to-end smoke test against fresh Postgres + plug-in loaded:

  Boot logs:
    MetadataLoader: source='core' loaded 4 entities, 13 permissions,
      4 menus from 2 file(s)
    MetadataLoader: source='plugin:printing-shop' loaded 2 entities,
      5 permissions, 2 menus from 1 file(s)

  HTTP smoke (everything green):
    GET /api/v1/_meta/metadata (no auth)              → 200
      6 entities, 18 permissions, 6 menus
      entity names: User, Role, Item, Uom, Plate, InkRecipe
      menu sections: Catalog, Printing shop, System
    GET /api/v1/_meta/metadata/entities                → 200
    GET /api/v1/_meta/metadata/menus                   → 200

  Direct DB verification:
    metadata__entity:    core=4, plugin:printing-shop=2
    metadata__permission: core=13, plugin:printing-shop=5
    metadata__menu:      core=4, plugin:printing-shop=2

  Idempotency: restart the app, identical row counts.

  Existing endpoints regression:
    GET /api/v1/identity/users (Bearer)               → 1 user
    GET /api/v1/catalog/uoms (Bearer)                  → 15 UoMs
    GET /api/v1/plugins/printing-shop/ping (Bearer)    → 200

Bugs caught and fixed during the smoke test:

  • The first attempt loaded core metadata via a CommandLineRunner
    annotated @Order(HIGHEST_PRECEDENCE) and per-plug-in metadata
    inline in VibeErpPluginManager.afterPropertiesSet(). Spring
    runs all InitializingBeans BEFORE any CommandLineRunner, so
    the plug-in metadata loaded first and the core load came
    second — wrong order. Fix: drop CoreMetadataInitializer
    entirely; have the plug-in manager call metadataLoader.loadCore()
    directly at the start of afterPropertiesSet().

  • The first attempt's plug-in load used
    metadataLoader.load(pluginClassLoader, ...) which used Spring's
    PathMatchingResourcePatternResolver against the plug-in's
    classloader. PluginClassLoader is parent-first, so the resolver
    enumerated BOTH the plug-in's own JAR AND the host classpath's
    metadata files, tagging core entities as source='plugin:<id>'
    and corrupting the seed counts. Fix: refactor MetadataLoader
    to expose loadFromPluginJar(pluginId, jarPath) which opens
    the plug-in JAR directly via java.util.jar.JarFile and walks
    its entries — never asking the classloader at all. The
    api-v1 surface didn't change.

  • Two KDoc comments contained the literal string `*.yml` after
    a `/` character (`/metadata/*.yml`), forming the `/*` pattern
    that Kotlin's lexer treats as a nested-comment opener. The
    file failed to compile with "Unclosed comment". This is the
    third time I've hit this trap; rewriting both KDocs to avoid
    the literal `/*` sequence.

  • The MetadataLoaderTest's hand-rolled JAR builder didn't include
    explicit directory entries for parent paths. Real Gradle JARs
    do include them, and Spring's PathMatchingResourcePatternResolver
    needs them to enumerate via classpath*:. Fixed the test helper
    to write directory entries for every parent of each file.

Implementation plan refreshed: P1.5 marked DONE. Next priority
candidates: P5.2 (pbc-partners — third PBC clone) and P3.4 (custom
field application via the ext jsonb column, which would unlock the
full Tier 1 customization story).

Framework state: 17→18 commits, 10→11 modules, 81→92 unit tests,
metadata seeded for 6 entities + 18 permissions + 6 menus.

Adds the framework's event bus, the second cross-cutting service (after
auth) that PBCs and plug-ins both consume. Implements the transactional
outbox pattern from the architecture spec section 9 — events are
written to the database in the same transaction as the publisher's
domain change, so a publish followed by a rollback never escapes.
This is the seam where a future Kafka/NATS bridge plugs in WITHOUT
touching any PBC code.

What landed:

* New `platform/platform-events/` module:
  - `EventOutboxEntry` JPA entity backed by `platform__event_outbox`
    (id, event_id, topic, aggregate_type, aggregate_id, payload jsonb,
    status, attempts, last_error, occurred_at, dispatched_at, version).
    Status enum: PENDING / DISPATCHED / FAILED.
  - `EventOutboxRepository` Spring Data JPA repo with a pessimistic
    SELECT FOR UPDATE query for poller dispatch.
  - `ListenerRegistry` — in-memory subscription holder, indexed both
    by event class (Class.isInstance) and by topic string. Supports
    a `**` wildcard for the platform's audit subscriber. Backed by
    CopyOnWriteArrayList so dispatch is lock-free.
  - `EventBusImpl` — implements the api.v1 EventBus. publish() writes
    the outbox row AND synchronously delivers to in-process listeners
    in the SAME transaction. Marked Propagation.MANDATORY so the bus
    refuses to publish outside an existing transaction (preventing
    publish-and-rollback leaks). Listener exceptions are caught and
    logged; the outbox row still commits.
  - `OutboxPoller` — Spring @Scheduled component that runs every 5s,
    drains PENDING / FAILED rows under a pessimistic lock, marks them
    DISPATCHED. v0.5 has no real external dispatcher — the poller is
    the seam where Kafka/NATS plugs in later.
  - `EventBusConfiguration` — @EnableScheduling so the poller actually
    runs. Lives in this module so the seam activates automatically
    when platform-events is on the classpath.
  - `EventAuditLogSubscriber` — wildcard subscriber that logs every
    event at INFO. Demo proof that the bus works end-to-end. Future
    versions replace it with a real audit log writer.

* `platform__event_outbox` Liquibase changeset (platform-events-001):
  table + unique index on event_id + index on (status, created_at) +
  index on topic.

* DefaultPluginContext.eventBus is no longer a stub that throws —
  it's now the real EventBus injected by VibeErpPluginManager.
  Plug-ins can publish and subscribe via the api.v1 surface. Note:
  subscriptions are NOT auto-scoped to the plug-in lifecycle in v0.5;
  a plug-in that wants its subscriptions removed on stop() must call
  subscription.close() explicitly. Auto-scoping lands when per-plug-in
  Spring child contexts ship.

* pbc-identity now publishes `UserCreatedEvent` after a successful
  UserService.create(). The event class is internal to pbc-identity
  (not in api.v1) — other PBCs subscribe by topic string
  (`identity.user.created`), not by class. This is the right tradeoff:
  string topics are stable across plug-in classloaders, class equality
  is not, and adding every event class to api.v1 would be perpetual
  surface-area bloat.

Tests: 13 new unit tests (9 EventBusImplTest + 4 OutboxPollerTest)
plus 2 new UserServiceTest cases that verify the publish happens on
the happy path and does NOT happen when create() rejects a duplicate.
Total now 76 unit tests across the framework, all green.

End-to-end smoke test against fresh Postgres with the plug-in loaded
(everything green):

  EventAuditLogSubscriber subscribed to ** at boot
  Outbox empty before any user create                      ✓
  POST /api/v1/auth/login                                  → 200
  POST /api/v1/identity/users (create alice)               → 201
  Outbox row appears with topic=identity.user.created,
    status=PENDING immediately after create                ✓
  EventAuditLogSubscriber log line fires synchronously
    inside the create transaction                          ✓
  POST /api/v1/identity/users (create bob)                 → 201
  Wait 8s (one OutboxPoller cycle)
  Both outbox rows now DISPATCHED, dispatched_at set       ✓
  Existing PBCs still work:
    GET /api/v1/identity/users → 3 users                   ✓
    GET /api/v1/catalog/uoms → 15 UoMs                     ✓
  Plug-in still works:
    GET /api/v1/plugins/printing-shop/ping → 200           ✓

The most important assertion is the synchronous audit log line
appearing on the same thread as the user creation request. That
proves the entire chain — UserService.create() → eventBus.publish()
→ EventBusImpl writes outbox row → ListenerRegistry.deliver()
finds wildcard subscriber → EventAuditLogSubscriber.handle()
logs — runs end-to-end inside the publisher's transaction.
The poller flipping PENDING → DISPATCHED 5s later proves the
outbox + poller seam works without any external dispatcher.

Bug encountered and fixed during the smoke test:

  • EventBusImplTest used `ObjectMapper().registerKotlinModule()`
    which doesn't pick up jackson-datatype-jsr310. Production code
    uses Spring Boot's auto-configured ObjectMapper which already
    has jsr310 because spring-boot-starter-web is on the classpath
    of distribution. The test setup was the only place using a bare
    mapper. Fixed by switching to `findAndRegisterModules()` AND
    by adding jackson-datatype-jsr310 as an explicit implementation
    dependency of platform-events (so future modules that depend on
    the bus without bringing web in still get Instant serialization).

What is explicitly NOT in this chunk:

  • External dispatcher (Kafka/NATS bridge) — the poller is a no-op
    that just marks rows DISPATCHED. The seam exists; the dispatcher
    is a future P1.7.b unit.
  • Exponential backoff on FAILED rows — every cycle re-attempts.
    Real backoff lands when there's a real dispatcher to fail.
  • Dead-letter queue — same.
  • Per-plug-in subscription auto-scoping — plug-ins must close()
    explicitly today.
  • Async / fire-and-forget publish — synchronous in-process only.

Adds the second core PBC, validating that the pbc-identity template is
actually clonable and that the Gradle dependency rule fires correctly
for a real second PBC.

What landed:

* New `pbc/pbc-catalog/` Gradle subproject. Same shape as pbc-identity:
  api-v1 + platform-persistence + platform-security only (no
  platform-bootstrap, no other pbc). The architecture rule in the root
  build.gradle.kts now has two real PBCs to enforce against.

* `Uom` entity (catalog__uom) — code, name, dimension, ext jsonb.
  Code is the natural key (stable, human-readable). UomService rejects
  duplicate codes and refuses to update the code itself (would invalidate
  every Item FK referencing it). UomController at /api/v1/catalog/uoms
  exposes list, get-by-id, get-by-code, create, update.

* `Item` entity (catalog__item) — code, name, description, item_type
  (GOOD/SERVICE/DIGITAL enum), base_uom_code FK, active flag, ext jsonb.
  ItemService validates the referenced UoM exists at the application
  layer (better error message than the DB FK alone), refuses to update
  code or baseUomCode (data-migration operations, not edits), supports
  soft delete via deactivate. ItemController at /api/v1/catalog/items
  with full CRUD.

* `org.vibeerp.api.v1.ext.catalog.CatalogApi` — second cross-PBC facade
  in api.v1 (after IdentityApi). Exposes findItemByCode(code) and
  findUomByCode(code) returning safe ItemRef/UomRef DTOs. Inactive items
  are filtered to null at the boundary so callers cannot accidentally
  reference deactivated catalog rows.

* `CatalogApiAdapter` in pbc-catalog — concrete @Component
  implementing CatalogApi. Maps internal entities to api.v1 DTOs without
  leaking storage types.

* Liquibase changeset (catalog-init-001..003) creates both tables with
  unique indexes on code, GIN indexes on ext, and seeds 15 canonical
  units of measure: kg/g/t (mass), m/cm/mm/km (length), m2 (area),
  l/ml (volume), ea/sheet/pack (count), h/min (time). Tagged
  created_by='__seed__' so a future metadata uninstall sweep can
  identify them.

Tests: 11 new unit tests (UomServiceTest x5, ItemServiceTest x6),
total now 49 unit tests across the framework, all green.

End-to-end smoke test against fresh Postgres via docker-compose
(14/14 passing):
  GET /api/v1/catalog/items (no auth)            → 401
  POST /api/v1/auth/login                        → access token
  GET /api/v1/catalog/uoms (Bearer)              → 15 seeded UoMs
  GET /api/v1/catalog/uoms/by-code/kg            → 200
  POST custom UoM 'roll'                         → 201
  POST duplicate UoM 'kg'                        → 400 + clear message
  GET items                                       → []
  POST item with unknown UoM                     → 400 + clear message
  POST item with valid UoM                       → 201
  catalog__item.created_by                       → admin user UUID
                                                   (NOT __system__)
  GET /by-code/INK-CMYK-CYAN                     → 200
  PATCH item name + description                  → 200
  DELETE item                                    → 204
  GET item                                       → active=false

The principal-context bridge from P4.1 keeps working without any
additional wiring in pbc-catalog: every PBC inherits the audit
behavior for free by extending AuditedJpaEntity. That is exactly the
"PBCs follow a recipe, the framework provides the cross-cutting
machinery" promise from the architecture spec.

Architectural rule enforcement still active: confirmed by reading the
build.gradle.kts and observing that pbc-catalog declares no
:platform:platform-bootstrap and no :pbc:pbc-identity dependency. The
build refuses to load on either violation.

Implements the auth unit from the implementation plan. Until now, the
framework let any caller hit any endpoint; with the single-tenant
refactor there is no second wall, so auth was the most pressing gap.

What landed:

* New `platform-security` module owns the framework's security
  primitives (JWT issuer/verifier, password encoder, Spring Security
  filter chain config, AuthenticationFailedException). Lives between
  platform-persistence and platform-bootstrap.

* `JwtIssuer` mints HS256-signed access (15min) and refresh (7d) tokens
  via NimbusJwtEncoder. `JwtVerifier` decodes them back to a typed
  `DecodedToken` so PBCs never need to import OAuth2 types. JWT secret
  is read from VIBEERP_JWT_SECRET; the framework refuses to start if
  the secret is shorter than 32 bytes.

* `SecurityConfiguration` wires Spring Security with JWT resource
  server, stateless sessions, CSRF disabled, and a public allowlist
  for /actuator/health, /actuator/info, /api/v1/_meta/**,
  /api/v1/auth/login, /api/v1/auth/refresh.

* `PrincipalContext` (in platform-persistence/security) is the bridge
  between Spring Security's SecurityContextHolder and the audit
  listener. Bound by `PrincipalContextFilter` which runs AFTER
  BearerTokenAuthenticationFilter so SecurityContextHolder is fully
  populated. The audit listener (AuditedJpaEntityListener) now reads
  from PrincipalContext, so created_by/updated_by are real user ids
  instead of __system__.

* `pbc-identity` gains `UserCredential` (separate table from User —
  password hashes never share a query plan with user records),
  `AuthService` (login + refresh, generic AuthenticationFailedException
  on every failure to thwart account enumeration), and `AuthController`
  exposing /api/v1/auth/login and /api/v1/auth/refresh.

* `BootstrapAdminInitializer` runs on first boot of an empty
  identity__user table, creates an `admin` user with a random
  16-char password printed to the application logs. Subsequent
  boots see the user exists and skip silently.

* GlobalExceptionHandler maps AuthenticationFailedException → 401
  with a generic "invalid credentials" body (RFC 7807 ProblemDetail).

* New module also brings BouncyCastle as a runtime-only dep
  (Argon2PasswordEncoder needs it).

Tests: 38 unit tests pass, including JwtRoundTripTest (issue/decode
round trip + tamper detection + secret-length validation),
PrincipalContextTest (ThreadLocal lifecycle), AuthServiceTest (9 cases
covering login + refresh happy paths and every failure mode).

End-to-end smoke test against a fresh Postgres via docker-compose:
  GET /api/v1/identity/users (no auth)        → 401
  POST /api/v1/auth/login (admin + bootstrap) → 200 + access/refresh
  POST /api/v1/auth/login (wrong password)    → 401
  GET  /api/v1/identity/users (Bearer)        → 200, lists admin
  POST /api/v1/identity/users (Bearer)        → 201, creates alice
  alice.created_by                            → admin's user UUID
  POST /api/v1/auth/refresh (refresh token)   → 200 + new pair
  POST /api/v1/auth/refresh (access token)    → 401 (type mismatch)
  GET  /api/v1/identity/users (garbage token) → 401
  GET  /api/v1/_meta/info (no auth, public)   → 200

Plan: docs/superpowers/specs/2026-04-07-vibe-erp-implementation-plan.md
refreshed to drop the now-dead P1.1 (RLS hook) and H1 (per-region
tenant routing), reorder priorities so P4.1 is first, and reflect the
single-tenant change throughout.

Bug fixes encountered along the way (caught by the smoke test, not by
unit tests — the value of running real workflows):

  • JwtIssuer was producing IssuedToken.expiresAt with nanosecond
    precision but JWT exp is integer seconds; the round-trip test
    failed equality. Fixed by truncating to ChronoUnit.SECONDS at
    issue time.
  • PrincipalContextFilter was registered with addFilterAfter
    UsernamePasswordAuthenticationFilter, which runs BEFORE the
    OAuth2 BearerTokenAuthenticationFilter, so SecurityContextHolder
    was empty when the bridge filter read it. Result: every
    authenticated request still wrote __system__ in audit columns.
    Fixed by addFilterAfter BearerTokenAuthenticationFilter::class.
  • RefreshRequest is a single-String data class. jackson-module-kotlin
    interprets single-arg data classes as delegate-based creators, so
    Jackson tried to deserialize the entire JSON object as a String
    and threw HttpMessageNotReadableException. Fixed by adding
    @JsonCreator(mode = PROPERTIES) + @param:JsonProperty.

Design change: vibe_erp deliberately does NOT support multiple companies in
one process. Each running instance serves exactly one company against an
isolated Postgres database. Hosting many customers means provisioning many
independent instances, not multiplexing them.

Why: most ERP/EBC customers will not accept a SaaS where their data shares
a database with other companies. The single-tenant-per-instance model is
what the user actually wants the product to look like, and it dramatically
simplifies the framework.

What changed:
- CLAUDE.md guardrail #5 rewritten from "multi-tenant from day one" to
  "single-tenant per instance, isolated database"
- api.v1: removed TenantId value class entirely; removed tenantId from
  Entity, AuditedEntity, Principal, DomainEvent, RequestContext,
  TaskContext, IdentityApi.UserRef, Repository
- platform-persistence: deleted TenantContext, HibernateTenantResolver,
  TenantAwareJpaTransactionManager, TenancyJpaConfiguration; removed
  @TenantId and tenant_id column from AuditedJpaEntity
- platform-bootstrap: deleted TenantResolutionFilter; dropped
  vibeerp.instance.mode and default-tenant from properties; added
  vibeerp.instance.company-name; added VibeErpApplication @EnableJpaRepositories
  and @EntityScan so PBC repositories outside the main package are wired;
  added GlobalExceptionHandler that maps IllegalArgumentException → 400
  and NoSuchElementException → 404 (RFC 7807 ProblemDetail)
- pbc-identity: removed tenant_id from User, repository, controller, DTOs,
  IdentityApiAdapter; updated UserService duplicate-username message and
  the matching test
- distribution: dropped multiTenancy=DISCRIMINATOR and
  tenant_identifier_resolver from application.yaml; configured Spring Boot
  mainClass on the springBoot extension (not just bootJar) so bootRun works
- Liquibase: rewrote platform-init changelog to drop platform__tenant and
  the tenant_id columns on every metadata__* table; rewrote
  pbc-identity init to drop tenant_id columns, the (tenant_id, *)
  composite indexes, and the per-table RLS policies
- IdentifiersTest replaced with Id<T> tests since the TenantId tests
  no longer apply

Verified end-to-end against a real Postgres via docker-compose:
  POST /api/v1/identity/users   → 201 Created
  GET  /api/v1/identity/users   → list works
  GET  /api/v1/identity/users/X → fetch by id works
  POST duplicate username       → 400 Bad Request (was 500)
  PATCH bogus id                → 404 Not Found (was 500)
  PATCH alice                   → 200 OK
  DELETE alice                  → 204, alice now disabled

All 18 unit tests pass.

BLOCKER: wire Hibernate multi-tenancy
- application.yaml: set hibernate.tenant_identifier_resolver and
  hibernate.multiTenancy=DISCRIMINATOR so HibernateTenantResolver is
  actually installed into the SessionFactory
- AuditedJpaEntity.tenantId: add @org.hibernate.annotations.TenantId so
  every PBC entity inherits the discriminator
- AuditedJpaEntityListener.onCreate: throw if a caller pre-set tenantId
  to a different value than the current TenantContext, instead of
  silently overwriting (defense against cross-tenant write bugs)

IMPORTANT: dependency hygiene
- pbc-identity no longer depends on platform-bootstrap (wrong direction;
  bootstrap assembles PBCs at the top of the stack)
- root build.gradle.kts: tighten the architectural-rule enforcement to
  also reject :pbc:* -> platform-bootstrap; switch plug-in detection
  from a fragile pathname heuristic to an explicit
  extra["vibeerp.module-kind"] = "plugin" marker; reference plug-in
  declares the marker

IMPORTANT: api.v1 surface additions (all non-breaking)
- Repository: documented closed exception set; new
  PersistenceExceptions.kt declares OptimisticLockConflictException,
  UniqueConstraintViolationException, EntityValidationException, and
  EntityNotFoundException so plug-ins never see Hibernate types
- TaskContext: now exposes tenantId(), principal(), locale(),
  correlationId() so workflow handlers (which run outside an HTTP
  request) can pass tenant-aware calls back into api.v1
- EventBus: subscribe() now returns a Subscription with close() so
  long-lived subscribers can deregister explicitly; added a
  subscribe(topic: String, ...) overload for cross-classloader event
  routing where Class<E> equality is unreliable
- IdentityApi.findUserById: tightened from Id<*> to PrincipalId so the
  type system rejects "wrong-id-kind" mistakes at the cross-PBC boundary

NITs:
- HealthController.kt -> MetaController.kt (file name now matches the
  class name); added TODO(v0.2) for reading implementationVersion from
  the Spring Boot BuildProperties bean

…er, IdentityApi adapter, unit tests)