Retail RFP transmission system — v1 layout

A distribution and evaluation layer for retail sourcing. Large retailers issue RFPs and evaluate bids for free; vendors pay for the workspace that helps them win. This repository is the v1 code layout: directory and module structure, the domain model as real schema files, permission boundaries expressed as code, and typed seams where the undecided parts will land.

It is not a running product. It is the skeleton a build can start from without being redesigned.

Decisions live on the issue tracker, indexed by the map. Nearly every file here carries a comment naming the ticket that fixed it — if a choice looks arbitrary, the ticket says why, and what it cost.

The four structural requirements this layout exists to satisfy

Four resolutions handed requirements to a layout that did not exist yet. They are the reason this repository is shaped the way it is.

Requirement	Where it lives	From
A single database entry point that makes bypassing actor context awkward	src/db/index.ts — the pool is not exported	#11
A scheduled-job entry point establishing actor context with no request	src/scheduler/	#13
An entitlement assertion helper carrying the convenience-not-correctness principle	src/auth/entitlement.ts	#20, #34
An explicit, reviewable list of privileged RLS bypasses	src/db/privileged.ts — three of them	#33

Layout

src/
  db/
    index.ts         THE database entry point. withActor() is the only way in.
    actor.ts         ActorContext; SET LOCAL discipline
    privileged.ts    the enumerated RLS bypasses — keep this short
    schema/          the domain model, with RLS policies beside their tables
  auth/
    entitlement.ts   assert per feature; its call sites ARE the paid-feature list
  release/
    matrix.ts        the release matrix, mirrored from SQL so screen and policy agree
  scoring/
    routing.ts       what a model may decide. Two lanes of six.
    rank.ts          ranking over committed scores only
  extraction/
    index.ts         ONE module used twice — RFP and response
    completeness.ts  the second, INDEPENDENT pass. Must share nothing with the above.
  scheduler/         jobs, with actor context and no request
  http/
    context.ts       request -> actor context; entitlement resolved once
    routes/          two capability-scoped nav trees, plus a public pre-auth surface
  pricing/           rate function evaluation — deterministic, no model fallback
  audit/ integration/ helmdocs/ kickoff/ claiming/     seams
migrations/
  0000_*             SQL functions, hand-authored — must precede the policies
  0001_*             generated schema, with RLS policies beside their tables
  0002_*             the release matrix seed, hand-authored
docs/
  seams.md           what is open, and what is deliberately closed
  migrations.md      why policies sit beside tables and the matrix is a data migration

Three invariants worth knowing before you touch anything

Permissions never resolve against an org alone. Always (org, capability, resource). An org may hold both the issuer and vendor capability, and those are two authorization contexts that cannot see each other — a dual-role company's vendor vault is invisible to its own issuing side. This is enforced in Postgres, not in application code, because the invariant that a vendor's bid is never reachable by another vendor is the one failure that would destroy the product's credibility.

Entitlement is not row visibility. RLS answers whose row is this; a lapsed vendor still owns every row they owned yesterday. Policies must not reference entitlement at all. Entitlement gates what a vendor may newly undertake, never what a retailer has already come to rely on.

Bids are sealed until the deadline, then the whole field opens at once. Bid shopping is structurally impossible rather than discouraged. A surprising amount depends on this: it is also what makes mid-flight amendments safe, since the retailer has read nothing and cannot tailor one to advantage a response they have already seen.

Working on a seam

yarn seams

Every seam throws with the ticket that owns it. Replace the body; the signature is already the handoff. If you find yourself changing a seam's types, check the ticket first — the shape usually came out of a resolution rather than out of convenience.