# AGENTS.md — OpenVibe.Inventory

## Project Overview

OpenVibe.Inventory is the network-wide inventory for one OpenVibe account (ADR-054): the item kinds a surface can
render, the definitions an issuer publishes, the instances a person owns, the equipped set, the ledger, the community
Workshop and the reviewed cosmetic store. One inventory for every OpenVibe site, the way Steam's works across games.

- **Site:** `openvibe.my/inventory` (base-path aware; API host `inventory.openvibe.network`) · **Port:** 5030 ·
  **Service id:** `inventory` · **Env prefix:** `INVENTORY`
- **Runtime:** Node 22, Express 4, PostgreSQL 18 through `openvibe-sdk/db` (PGlite in development/tests), Valkey 9
  for shared limits.
- **Read first:** [README.md](README.md), [docs/store.md](docs/store.md), [STATUS.json](STATUS.json), ADR-054 in
  OpenVibe.Contracts.

**Network context:** subjects (`usr_…`), usernames, tokens, JWKS and roles are OpenVibe.Network. Image bytes are
OpenVibe.Media (a Workshop image is uploaded to Inventory's Media tenant and referenced by `med_` id). Events are
published through the SDK outbox to OpenVibe.Events; account export/deletion arrives there at `/internal/events`.
Money is OpenVibe.Billing: the store snapshots a reviewed price, Billing authorizes the spend, and Inventory matches
Billing's payment before granting. Inventory never moves money itself.

## Commands

```bash
npm ci                         # install (contracts/sdk/shared pinned by tag)
npm run dev                    # http://localhost:5030 (base path from PUBLIC_URL/BASE_URL)
npm start                      # node server/index.js
npm test                       # every test/*.test.js on temp PGlite, mocked Network/Media/Billing
npm run test:pg                # the same through PostgreSQL + PgBouncer
npm test -- holdings           # only test files whose name contains the word
npm test -- --strict           # a skipped test fails the run
node --check <file.js>         # syntax check (no linter configured)
```

`test/run.js` uses `openvibe-shared/test-runner`; tests use fixtures and never reach the internet. No build step:
pages are server-rendered and assets live under [public/](public/).

## Architecture at a Glance

- **Entry:** [server/index.js](server/index.js) — listener, telemetry retention, the outbox relay and the two account
  subscriptions; graceful stop in `createLifecycle()`. `INVENTORY_DRILL` keeps boot-time work off.
- **App factory:** [server/app.js](server/app.js) — CSP, SSO, `/auth`, `/internal/events`, the `/shared` + static
  mounts, `/api/v1`, discovery/agent twins, pages, 404/error handler.
- **Config and URLs:** [server/config.js](server/config.js) (`load(env)` is pure), [server/urls.js](server/urls.js)
  (the one base-path translation for links, redirects, metadata and discovery — API paths keep their shape).
- **Model/store:** [server/inventory/store.js](server/inventory/store.js) (kinds, definitions, instances, grants,
  equipped, ledger, subject merges), [server/inventory/holdings.js](server/inventory/holdings.js) (stacked public/own
  holdings and cursors), [server/inventory/commerce.js](server/inventory/commerce.js) (store, review, orders,
  Billing), [server/inventory/seed.js](server/inventory/seed.js), [server/inventory/account-data.js](server/inventory/account-data.js).
  Seed data: [server/data/kinds.json](server/data/kinds.json), [server/data/live-definitions.json](server/data/live-definitions.json),
  [server/data/live-grantors.json](server/data/live-grantors.json).
- **Workshop:** [server/workshop/pages.js](server/workshop/pages.js), [server/workshop/people.js](server/workshop/people.js),
  [server/workshop/media.js](server/workshop/media.js), [server/workshop/image.js](server/workshop/image.js); upload JS
  [public/js/workshop-upload.js](public/js/workshop-upload.js).
- **HTTP:** [server/http/api.js](server/http/api.js) (`/api/v1`), [server/http/pages.js](server/http/pages.js),
  [server/http/discovery.js](server/http/discovery.js), [server/http/principal.js](server/http/principal.js)
  (person vs service, `X-OV-Subject`, same-origin cookie writes, capabilities),
  [server/http/wallet-cors.js](server/http/wallet-cors.js), [server/http/router.js](server/http/router.js) (async router).
- **Auth:** [server/auth/sso.js](server/auth/sso.js), [server/auth/keys.js](server/auth/keys.js),
  [server/auth/scoped-session.js](server/auth/scoped-session.js).
- **Frontend:** server-rendered through [server/render/layout.js](server/render/layout.js),
  [server/render/html.js](server/render/html.js), [server/render/markdown.js](server/render/markdown.js) and
  `openvibe-shared/shell|frame|showcase`; assets [public/css/app.css](public/css/app.css),
  [public/holdings.js](public/holdings.js). Every page works without JavaScript.
- **Database:** [server/db.js](server/db.js) and [migrations/](migrations/): `inventory_kinds`,
  `inventory_definitions`, `inventory_definition_aliases`, `inventory_instances`, `inventory_grants`,
  `inventory_equipped`, `inventory_ledger`, `inventory_store_listings`, `inventory_store_purchases`,
  `inventory_subject_merges`, `event_outbox`, `account_data_events`, `telemetry_samples`.
- **Deploy:** [deploy/systemd/openvibe-inventory.service](deploy/systemd/openvibe-inventory.service)
  (`/etc/openvibe/inventory.env`, `/opt/inventory.openvibe.network`) and
  [deploy/nginx/inventory.openvibe.network.conf](deploy/nginx/inventory.openvibe.network.conf). `sudo ovhost deploy
  inventory`; database `ov_inventory`; rollback restores the previous sha when `/api/ready` fails.

## Ownership and Boundaries

Inventory is the authority for kinds, definitions, instances, grants, the equipped set and the ledger, plus its
Workshop definitions, store listings/orders and the receipts of account-export/deletion events. It is **not** the
authority for accounts (Network), file bytes (Media), event delivery (Events), money (Billing), or the host/database/
Valkey (Host). Live's old `user_cosmetics`/`user_equipped` are Live's until
[scripts/import-live.js](scripts/import-live.js) has converted them; since ADR-054 Live reads and writes only through
this API. Account deletion removes a person's items and equipped set but keeps ledger rows without the subject, so
supply counts stay true.

## Auth and Capabilities

- Capabilities (Contracts): `inventory.item.read`, `inventory.item.list`, `inventory.equip.manage`,
  `inventory.item.grant`, `inventory.item.consume`, `inventory.definition.manage`, `inventory.definition.review`,
  and `inventory.store.list` (pins Contracts until released).
- A person acts for themself with their Network token or this site's session; a cookie write must be same-origin. A
  service acting for a person sends `X-OV-Subject: usr_…` and holds the route capability. Public reads need no token;
  a presented token must still hold `inventory.item.read`.
- Public reads (`/kinds`, `/definitions`, `/people/:subject/*`, `/equipped`) answer `Access-Control-Allow-Origin: *`
  with no credentials so any site can render what people wear; every other route stays same-site. Do not add a
  credentialed wildcard.
- Outbound: `events.event.publish` + `events.subscription.manage`, `identity.subject.resolve`, and Media
  `media.object.upload` on namespace `inventory`; store purchases use Billing with the person's own bearer.
- Tokens are audience `openvibe.inventory`. Refusals are RFC 9457 problem+json with stable `inventory.*` codes.

## API

`/api/v1`: `GET /ping`, `GET /kinds[/:id]`, `GET /definitions[/:id]`, `GET /people/:subject/items|equipped|holdings|holdings/count`,
`GET /equipped?subjects=a,b,…`, `GET /me/items|holdings|holdings/count`, `PUT /me/equipped`, `POST /grants`,
`POST /instances/:id/consume|revoke`, `POST /definitions`, `PATCH /definitions/:id`,
`GET /store`, `GET /store/purchases/:id`, `POST /store/:id/buy|list|review`.

Holdings: 60 stacks per page (max 200), filters `issuer|site`, `kind`, `rarity`, `equipped`, `tradable`, `text`; sort
`newest|name|rarity|count`; pass `next_cursor` back with the same filters. The cursor pins the newest instance, so
later grants never move a page. `tradable=true` is empty: there is no trade/transfer operation. Events:
`inventory.item.granted|consumed|revoked|equipped|unequipped`, `inventory.definition.published`.

## Conventions

- CommonJS, 4-space indent, single quotes, semicolons; no linter/formatter. Route handlers via
  [server/http/router.js](server/http/router.js); never leak a raw row or a secret.
- Every browser link goes through [server/urls.js](server/urls.js) so the `openvibe.my/inventory` base path survives
  redirects, discovery and the Markdown twins. API paths never take the prefix.
- New schema = a new `migrations/NNNN_name.sql`; never edit a migration that has run. Keep `inventory_` prefixes.
- CSP: add origins to `helmet` in [server/app.js](server/app.js). Media images come from `openvibe.media`; Billing and
  the wallet's connect-src are already named. Never widen `frameAncestors`/`objectSrc`.
- Phone first: pages must fit 390 px without horizontal scroll; `/me` works with plain forms and no JS.
- Empty states use the shared kit, never bespoke markup; "Calm reduces, only Off removes" applies to any hide
  preference (never delete).
- No Font Awesome; use `openvibe-shared ov-icons` (`KIND_ICON` in [server/http/pages.js](server/http/pages.js)).
- Nothing here sells, buys, trades or converts an item without a reviewed store listing and Billing.

## Key Pitfalls

- **Base path.** The site can be mounted under `/inventory`; a hard-coded `href="/items"` breaks production. Use
  `urls.path()` and `urls.html()`.
- **Store review is mandatory.** A price edit re-enters review; no price may be invented. An order reserves one
  serial under the ordinary grant lock; an uncertain response is recovered by retrying the same item/currency, and
  pending reservations do not expire by themselves.
- **Grants are idempotent per key**; a repeat must not issue a second instance. A capped item answers 409
  `inventory.supply_exhausted`.
- **Public CORS is deliberately credential-free.** `/me` and all writes must stay same-site; wallet-cors is only for
  the named first-party origins in [server/http/wallet-cors.js](server/http/wallet-cors.js).
- **Workshop images** are checked by their own bytes (64–512 px PNG/WebP, ≤200 KB), stored in Media's tenant, and
  never written to the database. On deletion a creator's badges pass to the kind issuer, retired.
- **Drill mode** (`INVENTORY_DRILL`) keeps the outbox relay, subscriptions and timers off; add new background work
  there.
- **Import Live's cosmetics** only with the dry run, `--apply`, then `--verify`; never print Live's URL or secrets.
- **`event_outbox`** needs its rejected partial index ([migrations/0007_outbox_rejected_index.sql](migrations/0007_outbox_rejected_index.sql)).

## Testing

`npm test` runs each file in its own process on a temp PGlite database with mocked Network/Media/Billing:
[test/inventory-api.test.js](test/inventory-api.test.js), [test/holdings.test.js](test/holdings.test.js),
[test/store.test.js](test/store.test.js), [test/workshop.test.js](test/workshop.test.js),
[test/workshop-media-client.test.js](test/workshop-media-client.test.js), [test/public-cors.test.js](test/public-cors.test.js),
[test/base-path.test.js](test/base-path.test.js), [test/import-live.test.js](test/import-live.test.js),
account-data, search-index, SSO, limits, secret-leak/redirect, layout and perf budgets. Run the narrowest file first,
then the suite; `npm run test:pg` for PostgreSQL. Always `node --check` changed files.

## Documentation

- [README.md](README.md) — purpose, ownership, capabilities, model, API, Workshop, pages, Live migration,
  configuration, acceptance, deploy, security notes.
- [docs/store.md](docs/store.md) — the universal store, review, orders and Billing matching.
- [STATUS.json](STATUS.json) — stage, deployed flag, features and not-yet list.
- [.env.example](.env.example) — variable names only; never commit values.
- [CHANGELOG.md](CHANGELOG.md), [SECURITY.md](SECURITY.md).