Build tally

What phase 1 admits, and where each item stands. A subset of leg 1: FedEx Ground and Home Delivery only, US continental 48, zones 2 through 8. Two functions — compare rates, and manage rates (lite). This is also the phase carrying the cross-leg and cross-service foundations, which is why the groups below hold them.

Grouped, not sequenced. Build order is ARCHITECTURE.md's build sequence; this says what and where, never when.

✅ built · 🔲 decided, needs code · ⬜ undecided · ⛔ dropped. A row with no glyph is a task rather than a state — neither code to write nor a decision to take.

Verified at bf36150, by running the suite and reading the tree: 957 passed, 14 skipped, 0 failed. What is built is the repository; this is a reading of it at one moment and never a second master.

Foundational

Internal

Leg 1 service

Compare rates

External, general

Manage rates (lite)

---

Audience: Claude Code, for any task on the application.

Read SCOPE.md first. Where the two conflict, SCOPE.md governs — raise it, amend the documents, then build.

Scope of this file. What the application builds, and how the user experiences it, at high level. What is built is the repository, never a list here; what survives here is the decision behind it.

Out of scope. The website, and the consulting services.

Related but not elaborated here — architecture, style, calculation rules.

The document is evolving.

• The markers are SCOPE.md, the terms. What they mean is defined there and not restated here. In this file a present-tense passage under one is a decision taken before the build, not a report on running code, and it may change as the build lands.
• Do not reject the build if the chat discussion is not aligned with this file — stop and ask.
• The alternatives considered and the options rejected behind a decision are logged in DECISIONS.md where they are needed.
• Work surfaced during a build is added as a section in the respective document, not as a new file.

---

1. Product and phases

1.1 Services and service legs

The four services are defined in SCOPE.md. Their boundaries are §4 to §6 below; which are admitted is §11.

The legs are listed in SCOPE.md, which also settles that a carrier is a section inside a leg's rules rather than a leg of its own.

1.2 Phases

The application is built in phases, and a phase is a decision, not a document. It is defined by the product owner and is not always strictly tied to a leg.

Later phases are decided by the product owner, one at a time. Nothing here is a roadmap; the next phase is written into the build tally when it is chosen.

---

2. Foundations

2.1 Language

SCOPE.md sets the source language for both surfaces and points here for how the application handles it.

Language is per login, not per entity, and it is the only thing held per login. Language covers the UI and the PDF report. Two logins in one entity may differ in it.

A time zone is not held at all. The viewer's zone is the machine's, read by the browser. A stored zone was built on 14 Sep and removed the same day: nothing read the column, so saving one changed nothing a person could see, and a control that stores something invisible reads as broken. logins.time_zone survives unused; dropping it is a migration nobody has written.

A date-only field is not exempt from the one rule. Every date and time is stored UTC and displayed as the viewer's calendar day, zone named, no field exempt. The cost is recorded in home.md, dates and times: the same contract reads a day apart across a zone boundary, and that was accepted as the price of one rule. An earlier edition of this paragraph said a date-only field is a date and does not shift; that is withdrawn.

EN and CN in phase 1. EN is the source of truth and the user is told so. Domain terms follow DICTIONARY.md.

User-facing strings are English and are written to be extracted. The i18n layer does not exist yet. Every string the build renders today sits in the template or the module that renders it, and the modules that carry the most of them say so where they sit. What the layer will do when it arrives is unchanged: one file per locale, identical keys, so adding a locale is adding a file rather than touching a screen. Until then the obligation on a new screen is extractability, not routing — a string is written whole, never assembled from fragments or built by concatenation, because a sentence stitched together at render time cannot be moved into a catalog without being rewritten first.

The browser is the default on first arrival for both; the login's settings govern once one exists. The locale the browser reports resolves to CN where it is any Chinese variant, and to EN otherwise. Traditional resolves to CN. The mapping is rewritten when a locale is added. [UNBUILT] A user may toggle either at any time, and the toggle writes to the login.

The login code email is always EN. It is sent before a session exists, so there is no login to read a preference from.

Layout consequences of length — button sizing, row wrapping, CJK line height — are brand/STYLE.md.

2.2 Ingest

Template. The HappyShip template, maintained by HappyShip, is the supported path and the default. Which file formats the parser accepts is the build's.

The same template and the same parser serve library uploads and comparison uploads alike. One ingest path, two destinations.

Files that resemble the template but do not conform are rejected with a clear reason rather than interpreted.

Non-template files are a service. HappyShip staff may convert a client's non-standard file into the HS template, which then enters through §4.5. In module 1 the handoff is offline, by email. In module 2 the client attaches a file and shares it with HappyShip, and once HappyShip has converted it the client approves the file. In module 3 a recurring non-HS-template file is parsed automatically. At launch, module 1 is sufficient. It is recorded here so nobody builds a second parser.

[UNBUILT] The card-entry path carries a how-to, on the client path and the internal one alike, covering how to fill the template and what is rejected. The internal path exists and carries none; the client's self-serve path is not built.

Column definitions, and the split between what is uploaded and what is entered on the web form, are RULES-<leg>.md.

There is no post-parse edit screen. An entity cannot enter values for lines the file left missing; missing mandatory data is resolved by substitution at comparison time (§5).

A card upload reports two distinct things, and they do not behave the same way. Rejections stop the upload. Confirmations do not. The confirmation set and the plausibility bound are RULES-<leg>.md. This is an act of card upload, not of a run; the substitution acknowledgment of §5 is a different moment.

One grid serves every service the card declares. In the template, service is a column only in the non-grid charge block and never an axis on the weight-by-zone grid; the parser fans that one grid out to the declared services on the way in, so the stored rows carry service in their key (ARCHITECTURE.md, ingest). Where two services within a carrier product group have genuinely different by-zone rates, that is two cards: a card spanning several services is several uploads only when their by-zone rates differ.

2.3 Engineering rules

1. The rate engine is a standalone library with no framework dependencies. Testable without a database or an HTTP server.
2. Explainability is not optional. Every computed charge carries the rule that produced it. A charge that cannot be explained is not returned as computed.
3. Prefer failing loudly over defaulting silently wherever a domain rule is involved.
4. A test asserts behavior, never the repository's content. A count of documents, markers or sections pins what happens to exist rather than what the code does, so an ordinary documentation commit turns the suite red and the assertion has to be lowered rather than fixed. Assert against a fixture the test constructs, never against the repository the code happens to be run over.

2.4 Interface patterns

Written once, instantiated everywhere. A new leg reuses these rather than copying them.

Two surfaces: internal, and clients.

Navigation has one root per surface, and neither leads to the other. A client arrives at its home, which carries the service menu (§9); the internal tool is a separate surface reached only by a login bound to HappyShip (§9).

Entity context and entity identification are different, and the shell must not collapse them. The internal tool reads across entities, so it shows which entity is in view — a context that changes while the login does not. A client login binds to one entity and has nothing to switch to, so what its shell shows is identification. Rendering the client's as a picker holding one option offers a choice that does not exist.

Sign-out sits in the shell, and it is the only control that ends a session. A session also ends on its own, on limits ARCHITECTURE.md sets; no screen states them.

[UNBUILT] Language is set from the navigation band, on every page of both surfaces. No time zone is set anywhere, none being held (§2.1).

The run pattern is upload → validate → acknowledge → run → dashboard → report. A card upload uses the first two stages and stops at stored: nothing about it runs and it produces no report.

• The acknowledgment carries a count, not a policy. A required checkbox stating a consequence in the abstract is agreed blind; the same checkbox beside the number of lines it applies to is a decision (§5).
• The report is the record, because the run leaves nothing behind (§7). A screen implying a result can be reopened is describing something that does not exist.

Exception management. What stopped the work and what was found and did not stop it are both shown for the client's acknowledgment. Card upload, comparison upload and every master-data upload show both, visually distinct.

• Rejection. The blocking column is exhaustive on the first pass, because a fail-fast parser turns a twenty-error file into twenty round trips.
• Non-blocking findings. An apparent deviation from the standard or the norm is highlighted. The test is whether a substitute can be used, or a condition changed, to proceed.
• Empty state. An empty state that is normal must not be dressed as incomplete — a region added but not yet mapped is empty in a way that does mean something is unfinished. The test is whether the empty state is where the thing is meant to rest or a stop on the way somewhere else.

A status change takes a second step, on both surfaces. One click is too little between an intention and a change of state. The step is a panel on the screen the control sits on, opened by a parameter on that screen's own URL, rather than a modal: there is no JavaScript in the application and every screen is a document (ARCHITECTURE.md, stack), so a dialog that cannot open is a control that either does nothing or guards nothing. The panel is a courtesy and never the enforcement — the preconditions live at the database, and a post that skips the panel still meets every one of them. The screen states the consequence concretely rather than asking whether the reader is sure — an abstract confirmation is agreed blind, in the same way the acknowledgment above is.

Deletion takes the step too, though deletion is not a status change. It is the one act that cannot be undone.

Making a card active and publishing it share one review pattern and remain two confirmations. Publishing carries the review obligation — the owner reviews the card's content and conditions once more (§4.5) — so its body is the longer of the two; making a card active states what changes and stops there. What must not happen is one screen doing both: an entity's own buy rates are active and must never enter the pool (§4.4), and a shared pattern is not a shared act.

Loading and long-running work is [OPEN]. Nothing beyond "it may take a few minutes" says how long a run takes, what the screen shows while it runs, or whether a user may navigate away. It waits on the job execution model (ARCHITECTURE.md) and on what session expiry looks like part-way through a run.

2.5 The ID scheme

Three rules, not one. An entityID identifies an entity. A typed ID identifies one record belonging to an entity and embeds the entityID that owns it; those two share an alphabet for their generated characters and share nothing else. A reportID identifies one comparison run and is printed on the report the requesting entity takes away. It is the third form, and it generates no characters at all.

An entityID is four characters — one letter A-Z, then three from the safe set, the one exception being HappyShip's own entities, which carry the reserved HS form and are seeded rather than generated (below). Every other entityID is generated by HappyShip at entity creation, randomized and collision-checked at issue, and never supplied by a user. It never changes, including when the entity's name is later corrected. It is entityID rather than clientID because HappyShip is itself an entity, and clientID would misname the identifier on HappyShip's own record.

A typed ID is eleven characters — an entityID, a hyphen, one type letter, then five from the safe set. It is unique within one entity and one type rather than globally. Stored with the hyphen; a stored value not matching the pattern is a defect, not a variant. The format itself is the build's.

Two alphabets, because two different things are being protected.

• The safe set governs the generated characters only — positions 2 to 4 of an entityID, and a typed ID's five-character suffix. It excludes the characters that confuse visually — 0/O, 1/I/L, 2/Z, 5/S, 8/B — because a machine produces those characters and a person reads them back, and that exchange is what the exclusion protects. That is the reason the set is not wider, and the alphabet itself is the build's.
• The type letter is chosen, not generated. It sits in a fixed position with no generated character beside it, so nobody has to tell it apart from one. It takes any letter or digit, and the confusable exclusions do not reach it.

[UNBUILT] A reportID is eighteen characters — the requesting entity's entityID, a hyphen, the run's date as YYYYMMDD, a hyphen, one type letter, and a three-digit counter. ABCD-20260910-R001. The entityID is the requester's, the buyer's; the date is the run's; the letter is R for a rate-for-rate comparison and S for a shipment-cost one (§5.2); and the counter is that entity's count of that type on that date, fixed at three digits. It is printed on the report the requesting entity downloads, emails or views (§5.4). Nothing carries one yet — comparison_runs.run_id is an internal surrogate, and the column that holds a reportID is a later build.

The safe set does not reach a reportID, because nothing in one is drawn. Every character is determined before it is written: the entityID is already issued, the date is the run's, the letter is chosen from two, and the counter counts. Uniqueness falls out of a constraint on entity, date, type and counter rather than from a collision check, so there is no generated suffix for the confusable exclusions to protect — and those exclusions exist for the one exchange this form does not have, a machine drawing characters a person reads back. 0, 1, 2, 5 and 8 appear in a reportID and are meant to.

R and S are reused here for unrelated meanings, and the reuse is deliberate. The type-letter catalog below carries R live for a rateID and S reserved for a statementID, and neither is what the letter means in a reportID. The two forms are unmistakable — a typed ID is eleven characters with one hyphen, a reportID eighteen with two — so no value of either can be read as the other, and claiming two further letters to avoid a collision that cannot occur would spend the catalog for nothing. Neither letter is added to the catalog for this purpose: the catalog governs typed IDs and what may be minted into a table that stores one, and a reportID is neither.

A reportID names the buyer to anyone holding the report, its first four characters being the requesting entity's own entityID. That is accepted rather than overlooked: the report is the entity's own, and what it shares is its own business. It reaches nothing that isolation protects — the entity named is the report's reader, not a card's owner, and no counterparty is identified in output (§8.1).

This is why S is a type letter while staying outside the safe set: the two alphabets answer different questions, and S is chosen rather than generated. It leaves the HS reservation below untouched — that argument turns on position 2 of an entityID, and position 2 is generated.

HS is reserved as an entityID prefix for HappyShip's own entities, the last two characters being a country code for a branch office — HSUS, HSCN, HSHK. It collides with nothing because S is excluded from the safe set, so no generated ID can begin HS. The reservation is implemented in two places and the generator is not one of them: app_is_entity_id() carries HS as an explicit alternation, because S is outside the safe set and HSUS would otherwise fail the format check every entity_id column reads; and the seed writes HSUS, reseeded rather than migrated, because there is no production data and the migrations are a construction script the fresh-apply test proves. app_roster_create implements no part of it — it draws position 2 from the safe set and nothing more — so a second HappyShip entity would be given a generated ID like any other, and reserving one for it is a change to that function.

The type letters.

Live means a table stores identifiers of that type and constrains the letter — R alone, in rate_cards, whose CHECK accepts an R and rejects every other letter. Reserved means the letter is claimed and no table will accept one. A reserved letter becomes live when the table that stores it is built, and that table carries its own constraint, as rate_cards already does for R.

A table that stores a typed ID constrains its first four characters to the owning entity. rate_cards carries that CHECK beside the letter's own, and every table that goes live with a letter carries the same pair. The rule is what makes a typed ID's uniqueness checkable by the entity that owns it: isolation hides other entities' rows (ARCHITECTURE.md, isolation), so without the constraint a collision could sit in a row the checking session cannot see, and the check would report clear against an identifier already issued. With it, every identifier that could collide belongs to the owning entity and is already visible. A table built without it does not fail loudly — it produces a check that is silently wrong.

R is minted by app_new_rate_id(); no other letter has a generator. It runs under the caller's own binding rather than as a definer, because the owner-prefix rule above makes the collision check answerable from inside the entity's own visibility. It returns a candidate and does not insert, so the write path carries the retry: rate_cards_pkey is the backstop if two sessions draw the same suffix between the check and the insert. A generated entityID is minted separately, at entity creation. A reserved letter has no generator and no table, and gains both together.

The reassignment cost no migration, and the next one will not be so cheap. S and C carried placeholder meanings in the schema — a shipment set and a charge file — but nothing was ever issued under either, so freeing them moved no stored value. That is the whole reason this was safe, and it is not a precedent: once a letter is live, the rule below governs instead.

A letter is registered in the type-letter catalog, and a generator reads it before minting. app_new_rate_id() refuses unless R is live there, so the catalog is what a generator is checked against rather than a record kept beside one. Adding a letter is still a schema change; the catalog remains master data with no write path, and nothing consults it at any other moment.

A reserved letter can be added or removed freely, because nothing carries it. A live letter cannot. The type letter is stored inside the identifier rather than beside it, so changing one rewrites the stored value of every row that carries it — and the foreign keys referencing those values declare no ON UPDATE, so they reject the update outright. Removing a live letter is a data migration, not a deletion.

---

3. Entities and access

3.1 Entities and authorization

There is one entity type. Buyer and seller are not stored roles — they describe what an entity is doing at a moment, and an entity commonly does both.

• No role field on the entity record, and no role enum anywhere in the schema.
• No separate buyer and seller records, and no separate rate storage per role.
• No role-based branches in the data layer, and no role-based permission checks. Access is determined by ownership and publication (§8).

HappyShip creates the entity record with its first login; the client completes it. The identifying fields — entityID (§2.5), company name, nickname, country or territory — are HappyShip's to set and correct. The client maintains its own contact details and its ship-from locations (§3.3). The relationship and commercial fields are HappyShip's and read-only to the client. Which fields exist is the build; what follows are the decisions about them.

• Country or territory is on ISO 3166-1, because separate customs territories are separate rows. A create form defaults to the browser's region, which the operator corrects; the screen must not present it as a detection.
• The country is the entity's headquarters, not a shipping location. Ship-from locations and their regions are §3.3, and the two are unrelated.
• [UNBUILT] Phase 1 offers four values: the US, mainland China, Hong Kong, and Other. Hong Kong is separate from mainland China for the reason above — separate customs territory, separate row. Other is not a country: HappyShip does no business outside the three in phase 1, so the value captures that the headquarters is elsewhere and records nothing further. The build ships the full ISO list today, and a test pins both its length and that Hong Kong, Macao and Taiwan render, so narrowing it is a code and test change rather than configuration.
• The value sets for services subscribed and for profile status are not settled. Services subscribed depends on BL-001 in BACKLOG.md. [OPEN]
• Currency is what the client pays HappyShip in, not what a card is denominated in. Cards are USD in phase 1, so no conversion exists anywhere in this phase.
• A contract either has an expiry date or is declared absent, never both. no_contract is an explicit answer rather than a blank, so a record with neither value is one nobody has filled in yet, and the two together cannot say a contract both expires and does not exist. [UNBUILT] Nothing acts on either today and no screen writes them.

The entity record carries no account email. Every address that can sign in is a login record, and that record is the account (§3.2).

An entity with no logins is a normal state, not an incomplete one.

An entity may be deleted only while it has no logins and no cards. Once either exists, there is history to keep.

Who may become a client, and on what terms. A client may be created only to compare rates or to subscribe to another service.

• Compare rates — in phase 1 HappyShip creates the client; a client with a company email address may self-register in a later phase. The service is free, on conditions that are [OPEN].
• Manage rates — the client must be created by HappyShip staff and must agree to the service terms and conditions. Self-service is a later phase. The same holds for audit invoices and track shipments.

3.2 Identity and access

One login, one workspace. A login belongs to one entity. entity_id and login_id are separate columns from the first migration — the entity is the isolation boundary, the login is the identity. Everything in §8 rests on that split.

One address, one login, one entity. A person needing both an internal and a client login needs two addresses.

Access is by invitation only. HappyShip creates an entity with its first login email address, and that record is the account. The client may add further logins. An address that is not logged cannot log in.

An entity may bind several logins, and they all see the same thing. [UNBUILT] Each entity is permitted up to three; no limit is enforced today. No per-login view, no per-login permission, nothing one login can do that another cannot — that would be a role system under another name, which §3.1 forbids. Language is the only thing held per login (§2.1).

Passwordless. A six-digit verification code is emailed to a pre-registered address. No stored passwords and no reset flow. There is no sign-up — the first visit and every later one are the same two screens, an address then a code. Code expiry, resend cooldown and wrong-attempt limits follow industry standards; nothing here needs inventing. An unregistered address gets a page with a link to the website's contact form, and a delivery failure has one recovery path: contact us.

A session survives a browser close and ends on its own, on the limits ARCHITECTURE.md sets. Signing out is the only way a user ends their own. What expiry looks like part-way through a run is [OPEN].

Internal access is entity binding, not a role. HappyShip is itself an entity; a login registered against it is internal. The address is never inspected — no domain match, no list, no role field. Two conditions must both hold: the internal surface was reached (§9), and the login is bound to HappyShip.

Recording which login acted is not a permission. Publication and withdrawal record the acting login and a timestamp (§4.4). The record answers who, not who may.

There is no edit on a login's identity. The address is the account, so correction is delete and recreate.

• Deleting a login ends its session immediately, checked per request rather than at expiry. Delete serves both a typo and someone who has left a company, and only immediate termination serves the second.
• A deleted address is free to be logged again.
• Cards that login published stay published. Publication binds the entity, not the login (§4.4).

An address is matched without regard to case, and stored lowercased. Ops@x.com and ops@x.com are one account: the create path lowercases on the way in and the lookup lowercases what it is given, so no two addresses differing only in case can both exist. This is a decision, not a normalization detail — it decides whether a person who capitalizes their address reaches their own account or a page saying there is none.

Logging an address sends a welcome email; deleting a login sends a notification. Both are sent outside a session, so both are EN. A delete-and-recreate correction sends both within moments, and the wording must survive that. There is no suppression window.

The mechanism is ARCHITECTURE.md — how a session is established and how the entity is bound to it. This section states only what must be true of it: the entity comes from the login record, never from a request.

3.3 Regions and locations

Regions are master data maintained by HappyShip (§9): one list, each row carrying an active flag, and no region nested inside another — a region holds ZIP prefixes, never other regions. HappyShip may add a region and re-map afterward.

[UNBUILT] A US region may hold three-digit ZIP prefixes, single or as a range, and a prefix belongs to one region, so a ZIP resolves to exactly one. Others is where a ZIP matching no prefix lands: it holds no prefixes by definition and cannot be deactivated. No prefix is stored today and nothing resolves a region — a location's region is declared directly.

The list is cross-leg, not one per leg — which is what filing regions under platform vocabulary already means in §9, a tier defined by not being scoped to a carrier and a leg.

An entity may hold several ship-from locations, and the client maintains them. ZIP is required. The entity's own address is not a ship-from location. Holding none is a valid state.

[UNBUILT] Each location maps to a region, and the ZIP is what resolves it. [UNBUILT] The seller may declare a region and is not required to. The schema requires one today — ship_from_locations.region_code is NOT NULL — so the optional case is a column change, not configuration. HappyShip audits the declarations and may remap. app_entity_remap_location works today and no screen can call it: app_entity_locations returns the declared region under both names, so the detail screen's two columns always agree and the Remap control is never offered. The resolution the audit compares against does not exist, so a declaration cannot yet disagree with anything. The declaration is a hint, never the answer — a must-met condition tested against a seller's own unverifiable claim is not much of a test, and resolving from the ZIP makes the same condition checkable. The screen must not present a declared region as the answer.

The warehouse service leg will add attributes to this object; they are not admitted — carried as placeholders under §11, deferred as BL-008.

---

4. Rate cards — manage rates

Lite — upload, conditions, lifecycle, publication, all below. Conditions are evaluated per run, so lite is not "no rules." A client's rates are stored in the HappyShip database once standardized.

Full — derivation of sell rates from buy rates, L1 to L4. Not admitted. Its rules are unwritten: margin structure, rounding, minimums and accessorial carry-through are all undecided, and until they are written no estimate of the work is meaningful. [OPEN]

4.1 Definitions

RateTable is leg-specific. Templates are defined by RULES-<leg>.md.

A card names the reference standard it is compared against, chosen at entry from master data (§9).

A reference standard may be converted from a carrier-published rate card or declared by HappyShip as a template. It may or may not have published rates tied to it; with none tied to it, it is the same as a rate template. A reference standard is not versioned. [OPEN]

Rate classes.

Two kinds of rate card.

• Library cards — stored, owned by an entity. Each carries an internally generated rateID, conditions, and a lifecycle.
• Comparison uploads — a file uploaded to run one comparison. Transient, purged after the run (§7); no rateID, no nickname, no lifecycle.

Shipment sets follow the same split, but only the transient half is admitted. A comparison shipment set is a file uploaded to run one comparison, purged after the run. A stored shipment set owned by an entity would serve invoice audit, which is not admitted — named so the symmetry is on record, and not built or scaffolded for (§11).

How a card is identified, last mile. Reference standard → rate group → rateID → nickname.

• Reference standard is the carrier's published rates. A carrier publishes official rates once a year and continues to issue edits, conditions, new rates and seasonal charges through it. Example: FedEx Ground & Home Delivery 2026.
• Rate group is assigned by HappyShip when a reference standard is selected. It drops the year and keeps the carrier's main services. Example: FedEx Ground & Home Delivery.
• rateID is a rate with a set of conditions defined on the web form. One of the first selections is the rate group, which is how the two are mapped.
• Nickname is user-defined per rateID and shows on the user's dashboard.

4.2 Conditions

A card may carry conditions, and each is marked must-met or prefer-met by whoever sets it. The distinction decides what a non-qualifying entity sees.

• Must-met — a card whose must-met conditions the requesting entity does not meet is excluded from that run. It is not in the pool and cannot be the recommended card. It may still be surfaced as an alternative — priced, and naming the condition types it fails; where it is not, the entity sees only a count and a reason (§8.1).
• Prefer-met — the card enters the pool and is costed, and the result carries an unmet-condition flag. A seller wanting $10k of monthly spend is compared for an $8k buyer, who sees the rate and sees that a condition is unmet.

Prefer-met is lead generation, and is written down so it is not "fixed." A buyer seeing a rate they do not yet qualify for is exactly what drives the consultation CTA. Filtering those cards out would look like a bug fix and would remove the mechanism.

The flag names the condition type and never its value. "Minimum spend not met," never "minimum monthly spend of $10k not met" — the threshold is a term of an anonymized card. Must-met exclusion reasons read identically, so the two cases cannot be told apart by their wording.

A rate card declares one or more regions, or the value meaning all regions, which is exclusive of any specific region. A published card must declare at least one. The card references a region, not a location (§3.3), and that is deliberate — the declaration is coarse on purpose.

The requesting entity states a set of regions per run, or none (§5.1). A card qualifies where its declared regions intersect the requester's set, or where it declares all regions. Stating more regions widens the pool rather than narrowing it.

RateCondition is evaluated per run against the requesting entity's serviceability facts (§5.1). What a condition can express, and how it is evaluated, is RULES-<leg>.md. The region list as it stands, and the condition's evaluation, are written in RULES-LAST-MILE.md.

Multiple conditions set by the rate seller are an AND: the buyer must meet all of them. Multiple conditions set by the rate buyer are an OR, with AND as the perfect match.

4.3 Lifecycle

The lifecycle states are the build's, and the set is closed. An expired card cannot generate a new quotation, but can still compute a comparison or an invoice validation.

Lifecycle is set by the user, not computed. A card is created as draft and the owner promotes it; the owner archives it when finished with, and un-archives it to take it up again. Expiry is the one exception, being the only transition no owner performs. [UNBUILT] The sweep exists and nothing runs it — app_cards_expire() is a callable waiting on the job execution model (ARCHITECTURE.md), so no card reaches expired today. The pool excludes a past-dated card whether or not the sweep has run, which is why the gap costs the pool nothing while it lasts; the card itself still reads as active and published until the sweep runs.

Archiving is not final. Un-archiving returns a card to plain active and does nothing else. It does not republish: a card re-entering the pool goes through the ordinary publication act with its own consent (§4.4), for the same reason that restoring an entity's authorization republishes nothing. Archive exists so a card carrying history can be put away, not so it can be put beyond reach.

Un-archiving renames on a collision, and only then. A nickname is unique among an entity's active cards, so a card archived under a name another active card has since taken cannot return under it. The card being un-archived is the one renamed, never the incumbent, which is in use. A card with no nickname never collides, and an un-archive that collides with nothing asks nothing.

A card may be deleted only if it has never been used or linked. Once it has been, it is archived, never deleted. Deletion exists to stop unused drafts accumulating, not to remove history.

4.4 Publication

Public or private. Publication is a flag on an active library card, not a lifecycle state, and the two are orthogonal.

This separation is load-bearing. An entity's own buy rates are active and used for its own comparisons, and must never enter the pool. If activation implied publication, every stored card would be exposed the moment it went live, turning a lifecycle transition into an isolation leak.

• Off — private — by default. A draft cannot be published.
• Three conditions must all hold to publish: the entity is authorized, the owning entity sets the flag, and the owner accepts the terms. Authorization is an entity-level setting HappyShip controls, and it exists so that entering the pool can be charged for. Only the client may authorize publishing: the owner reviews the card's content and conditions once more and clicks I agree to HappyShip's policies before publishing, which is the legal condition of entering the pool. Separately, a published card must declare at least one region (§4.2). That precondition is different in kind — the three above are consent, the region declaration is completeness — so the rule is not exhaustive of what a card needs before it can be published.
• Clearing the flag withdraws the card from the pool and returns it to plain active, still the owner's to use for their own comparisons.
• The flag clears three ways and they are distinct events. The owner withdraws it. The card expires. Or the entity's authorization is removed, which withdraws every card that entity has published. Only the first is a decision by anyone at the entity. [UNBUILT] Two of the three operate today: expiry clears the flag only when the sweep runs, and nothing runs it (§4.3), so a past-dated card keeps its flag while the pool already excludes it.
• Restoring authorization does not republish anything. The owner republishes, card by card. Publication is the consent record, and a card re-entering the pool because an invoice was paid would make the payment the consent rather than the person.
• Setting and clearing the flag record the acting login and a timestamp. Any login of the entity may do either (§3.2), and the act binds the entity either way — the record says which login, not which was allowed. This is the one place a login is recorded, because publication is the consent that makes a card comparable to strangers, and "someone at your company did" is an assertion where "this login, at this time" is a record. It is cheap here and nowhere else: library cards persist (§7), so the event has something to attach to, while the one thing a comparison run leaves behind is the run record (§7), which names the entity and no login.
• Expiry clears the flag without a login, when the sweep runs (§4.3), being the one transition no person performs. The record distinguishes the two.
• Sharing a card by rateID is not admitted. Publication is the only way a card becomes comparable to others.
• A single status label may be derived from lifecycle plus flag for display, never stored. The label set is the build's. No control may turn publication on as though it were a status step: an entity's own buy rates are active and must never enter the pool, and that separation must not sit one misclick from going active.
• Publishing must be explained where it is offered, because the word suggests display and that is not what happens: a published card is comparable to other entities, never visible to them.
• "You have not published this" and "your entity cannot publish" must be distinguishable. An unauthorized entity meeting a dead control with no explanation concludes the product is broken. What that state offers is [OPEN].
• The three ways a card leaves the pool must not be presented as one event. Only one is a decision by anyone at the entity.

Card versioning is [OPEN] — how a replacement card supersedes its predecessor, and whether conditions and the publication flag carry forward. Whatever is decided has to hold against the rule above that publication is the consent record.

4.5 Who writes a card

Reference standards, including carrier-published rates, are held by HappyShip and are internal only. Held is custody, not ownership of the rates: the rates are the carrier's, and what HappyShip holds is the row — which entity it belongs to under row-level security, and therefore who may read it. HappyShip does not legitimize a rate or stand behind one (SCOPE.md, what HappyShip does not do).

For a client's rate card there are two paths. The owning entity uploads it, or HappyShip enters it on the entity's behalf — including a file HappyShip converted under §2.2. A card HappyShip enters lands as draft, and the owner is emailed when it lands, so a transcription can be checked before anyone stands behind it. Only the owning entity publishes, regardless of who entered the data, and that act is the consent record. HappyShip cannot publish on an entity's behalf.

The internal path diverges from the client's at two points. At the start it asks what kind of card — client, or carrier published — and names the entity the card belongs to; a client has neither, the entity coming from the session. At the end a client's card lands as a draft in that client's library, while a carrier-published card becomes a HappyShip-owned card. [UNBUILT] The designation that names it a reference standard is a second act and is not written by this path (BL-023); the only designation in the database is the seeded one.

The order of what is asked is the same on both paths, and it is this:

1. What kind of card — client, or carrier published. Internal only.
2. Rate owner — the entity the card belongs to. Internal only.
3. The reference standard, from those already designated. It names the carrier, the service group and the leg, so choosing it settles all three and they are read rather than asked for. A carrier-published card branches here: it has no standard to name because it is the carrier's own published rates, the card a designation turns into a standard — an act this path does not yet perform (above) — so it asks for carrier and service group directly, those being what determine the template's shape.
4. Describe the card — nickname, dim factor, FSC discount, currency and weight unit, notes.
5. Thresholds — the conditions, each marked must-met or prefer-met with no default (§4.2). [UNBUILT] The built entry screen takes exactly one condition and at most one region, and requires the one; the schema admits three conditions and several regions, so the plural is a screen change and not a migration.
6. Download and fill. [UNBUILT] Nothing generates a template today — the filled file is produced out of band and the built form goes from thresholds straight to upload.
7. Upload, then declare which services the card covers, after the parse.
8. Saved as draft.

The card's details are settled before the file is downloaded, and the effective dates sit in the file's header block rather than on the form. No reason is recorded for the ordering beyond that it was chosen during design (DECISIONS.md).

4.6 The library dashboard

The output of manage rates is the user's dashboard, showing the state of the rate cards the entity maintains.

---

5. Comparing — compare rates

5.1 Serviceability facts

What the requesting entity tells the system about itself for one run — where it ships from and to, what volume, what service level, and whatever else a leg's conditions test. The full set per leg is RULES-<leg>.md.

Three properties matter and are easy to lose:

• Supplied per run, through the web form. Not stored on the entity, not remembered between runs.
• They are the only input the pool is filtered on.
• They are the entity's own claim. Nothing verifies them, and a false claim produces a comparison against cards the entity cannot actually use.

5.2 The two comparisons

• Rate-for-rate — when two cards have exactly the same structure, the numerical differences can be normalized and compared. The result is "who is cheaper for each line item."
• Shipment-cost — when an actual shipment profile is presented, each card produces the cost for that shipment set, whether or not the two cards share a structure. The result is "shipping cost."

The two are chosen first, because they take different inputs. Serviceability facts are then supplied on the web form (§5.1), and the rates or shipments either uploaded on the HS template or — for rate-for-rate — selected from the entity's own library. An uploaded file here is transient and nothing may offer to keep it.

One upload, one run. No appends and no accumulation.

Comparing against your own card. An entity using manage rates may run a comparison against one of its own stored cards, by reference, and against the standard that card names. A comparison never promotes a comparison upload into a stored card.

5.3 The run-time pool

A comparison runs against every published card, filtered by the requesting entity's serviceability facts (§5.1) against must-met conditions (§4.2). The pool is computed fresh for each run and does not persist. No stored relationship governs who compares against whom, and a newly published card is comparable immediately; there is no review step.

Missing mandatory data. Where an uploaded card lacks mandatory data for a line, the standard the card names is substituted for that line; the line is not excluded. The entity acknowledges this at upload through a required checkbox, shown alongside the count of affected lines. Every substituted line is marked in the report. Results also report the count of the entity's own priced lines that exceed the standard the card names. The alternative considered was excluding the line from both sides. Substitution is the product owner's decision.

5.4 Output

The output is a dashboard result, with the option to download an executive summary. It renders once and is not reachable again, and nothing stores it for retrieval. This is acceptable rather than hostile because nothing is destroyed: a buyer who loses the result re-uploads and runs again, and is answered against the pool as it stands that day. The reason is written down because renders-once reads as an oversight without it, and the repair a later reader reaches for is persistence. The output does not list a counterparty's rateID, entityID or any other identifier, the requesting entity's own reportID excepted — that one is printed on the report deliberately (§2.5) and is the entity's own. Where a client is happy with a rate, the next step is to contact HappyShip, and the reportID is what it quotes when it does.

What the dashboard and the report must both carry, constrained by §8.1. Layout is [OPEN].

• An executive summary — where the entity's card stands in the pool, against the reference standard and against the recommended card; and where a shipment profile was supplied, the total cost difference against both.
• Counterparties unlabeled — a row carries its figures and nothing that names the card or persists across runs (§8.1). The reference standard is named outright, being public.
• Marked substitutions — every line priced at the reference standard because the card lacked mandatory data.
• The count of the entity's own priced lines above the reference standard.
• The recommended card — the cheapest published card meeting every must-met condition, where it beats the entity's own. How cheapest is determined is RULES-<leg>.md.
• Alternatives — published cards cheaper than the recommended, each blocked by one or more must-met conditions, priced individually and ordered cheapest first. Each names the condition types it fails and nothing else about itself (§8.1).
• Excluded cards as a count and a reason, naming the condition type only. This covers every published card ruled out and not surfaced as an alternative.
• Prefer-met flags, with the rate and the condition type.
• The measure's caveat — rate-for-rate ranks on an average, across a weight band and across zones. Every rate-for-rate output carries this and points to shipment-cost (§5.2) as the more accurate answer. It qualifies the recommended, every alternative and the competitive result alike rather than sitting on one of them, and it belongs to rate-for-rate only: shipment-cost averages nothing.
• The competitive result — where there is neither a recommended card nor any alternative, the output states that the entity's rate is competitive and offers to publish it. That offer is the call to action in that case; the consultation CTA below is the one everywhere else.
• The consultation CTA.

After the run the screen must be honest that the result renders once rather than implying it can be reopened. What it offers is the download and the option to email it. Where the buyer asks for the email, a failed delivery costs a re-run — which is why the download sits beside the email on the view rather than after it. The buyer is reminded of that before leaving the view, so that a buyer who wanted a copy is not told after the fact. Neither artifact is required and taking neither is a choice the screen allows.

---

6. Audit invoices and track shipments

[OPEN] — filled when the two are scoped. Neither is admitted (§11).

---

7. Retention

Library cards are stored and persist (§4).

Comparison uploads, computed results and run detail are not. The uploaded file is purged once parsing succeeds, and result detail is purged once the run ends. The buyer has no run history and no result is reachable a second time (§5.4). HappyShip keeps a run record, the third durable class below. The two are a distinction rather than a caveat on one another: what does not exist is a buyer-facing history, and what does exist holds no rates, no results and no losing cards.

What survives a run is a small set of durable records that hold no rates, no results and no shipment data. Three classes:

• The issued-ID ledger. An ID that appears on a delivered PDF is never reissued, even after the file it named is purged. The ledger holds an ID and the date it was issued. It is not run history and does not make a purged run retrievable. [UNBUILT] Which ID types the ledger covers follows the revised scheme at §2.5. No ledger exists: issued_ids was dropped in migration 0015, and nothing had ever been issued under it, so a ledger is new work rather than a migration of stored identifiers.
• The per-entity counters — rates compared, rates published — which survive a run where results do not.
• The run record. One per run, holding the requesting entity, when the run happened, the winning rateID, and whether that winner satisfied every must-met condition. The place and HappyShip's read are built; nothing writes one yet — comparison_runs is append-only, the buyer has no read of it at all (no SELECT policy and no SELECT grant), and app_runs() returns every entity's runs to an internal caller and to nobody else. [UNBUILT] The writer waits on the run itself. It does not hold the losing cards. Storing them would accumulate a record of which sellers were undercut by which others, which is the accumulation isolation exists to prevent, and nothing in the product wants them. It is HappyShip's record, not the buyer's, and it is what resolves a later consultation back to a run (§8.1). The same comparison run twice produces two records, correctly — the pool moves between runs as cards are published and cards expire, so the same upload on a different day is a genuinely different answer. A run record is a snapshot claim against the pool as it stood, never a standing fact.

What the buyer keeps is whatever artifact it chose to take. The result renders once (§5.4); the buyer may download it, email it to itself, both or neither. Email is not mandatory and there is no BCC to HappyShip. What resolves a later consultation is the run record above, not a copy of the report.

Purge is configuration, not a hardcoded code path, and defaults to on. The tables carry an owning entity and timestamps from the first migration, so a later phase can enable retention without a rewrite.

The client-facing wording of this is open, tracked as BL-005 in BACKLOG.md. It constrains website copy as well as application copy.

---

8. Isolation and visibility

8.1 Visibility classes

Reference standards are public, and clients are not blinded to them. A client's rates and shipments are always compared against the standard its card names, and that standard is named in output. What qualifies as a reference standard is §9.

Everything a client owns is private unless published — rate cards, uploads, comparison results.

Card identities are never revealed in comparison output. A counterparty is unlabeled: a row carries its figures and nothing that names the card, nothing that identifies its owner, and no handle that holds from one run to the next. The standard the card names is identified, being public. The requesting entity's own card is the one exception: it stays in the pool like any other published card, and it is labeled as the entity's own. Anonymity buys the entity nothing against itself, and an entity holding two published cards would otherwise meet one of them as a competitor it could not tell from a stranger's. The rule stands unchanged for every other card in the run.

No identifier of a counterparty reaches output at all. The rateID never could: it is stable, identical for every viewer, and its first four characters are the owning entityID (§2.5), so it names the owner to anyone who has read the ID scheme. Nothing stands in for it either — a per-run substitute was the previous answer and is superseded (DECISIONS.md). What stops two entities discovering, by comparing reports, that they were quoted by the same seller is that neither report carries anything to match on.

HappyShip resolves a consultation through the run record (§7), which names the requesting entity, when the run happened and the winning rateID. An entity arriving to ask about the rate it was shown is answered from that record.

What HappyShip cannot do is re-run the comparison. The entity's uploaded rates are gone (§7), so a consultation that means modeling rather than introducing needs the entity to upload again. What it can do without a re-run is name the winner, which the run record holds. The limit on what the CTA can promise is real and is narrower than it was: introducing the winning seller needs no upload, and modeling anything still does.

[UNBUILT] Rate-for-rate output has four row shapes, and what a row may carry depends on which one it is. A single rule for all four would be either too tight for the entity's card or too loose for an alternative, so the bound is stated per shape.

An alternative carries those two things and nothing else. The output layer that emits this shape is not built. The fields are rank_value and unmet_condition_types; they are named here so the bound can be checked against the build rather than only agreed with. run_ref was a third and is gone with the reference code it carried. What exists is pool.PoolCard.unmet_condition_types, which already names types and never values, and engine.rate_for_rate's Headline — one card, one blocking condition, an aggregate — which is the superseded single-headline answer and not the flat list this section and RULES-LAST-MILE.md now require. What a matrix would add is the card's line detail, which is why the shape has none.

A card excluded by a must-met condition may be priced and shown as an alternative (§5.4). [UNBUILT] It appears as a price and the condition types it fails, unlabeled like every other counterparty — never a card identity, never an owner, never a threshold value, never line detail and never a matrix. A reason names a condition type, never a value (§4.2).

The count-and-reason rule still governs every published card not surfaced as an alternative. [UNBUILT] A comparison reports how many were ruled out and a brief reason, and for those cards that remains the whole of what a run produces.

This reverses a rule, and the sentence that justified it no longer decides the case. The rule was that a breakdown isolating an excluded card is forbidden, because a reason specific enough to identify a card is a leak carrying a helpful label. That claim is about a reason, and it still holds of one: a reason narrow enough to pick out a single card would name a value or an owner, which is why neither may be shown. An alternative does not carry such a reason. The condition types it fails are the requesting entity's own serviceability facts read back to it (§5.1), so every entity failing the same condition sees the same words, and the words identify the entity's position rather than the card.

What is conceded is the price, one card at a time rather than in aggregate. That is a real widening of what a non-qualifying entity learns, and it is taken deliberately: an entity cannot know in advance which of its own must-met failures is worth relaxing, so the lever and the prize have to appear together or neither is actionable. The trade and the option rejected are DECISIONS.md.

Must-met still decides whether a card can be recommended, and it no longer keeps that card's price from an entity that does not qualify. What it never did was hide the card's existence — the count already reported that.

None of this is seller-facing. A seller learns nothing about who was shown its card, or how often, and no output runs in that direction.

Publishing a card is a deliberate act by its owner (§4.4), and it is what makes the card comparable to other entities. It does not reveal the card, the owner's identity, or any relationship between the two. Only computed results reach another entity.

8.2 Enforcement

Isolation is enforced at the data layer, not in application code, so a missing filter fails closed rather than leaking. The entity comes from the session, never from a request (§3.2). The mechanisms are ARCHITECTURE.md.

Any path that reads across entities requires an explicit test asserting that entity A cannot read entity B's resources. It requires the positive assertion beside it — that the permitted party can — and a third asserting the bound itself, so widening the reachable column set fails a test rather than passing silently. Both directions or neither counts: a suite asserting only the negative passes when the exemption is broken, missing, or was never built, because the negative is satisfied by the feature not existing, and only the positive tells a correctly bounded exemption from one that has silently failed closed. Those tests extend to the run-time pool (§5.3), where two distinct layers are asserted separately, because they test different mechanisms and merging them hides which one failed:

• Publication state — whether the flag is set at all. A comparison must not surface an unpublished card, a draft, an expired card, or a card whose entity's authorization was removed (§4.4).
• Per-run filtering — of cards legitimately in the pool, excluded for this requester. A card whose must-met condition the requesting entity does not meet must not surface (§4.2).

[UNBUILT] The content path asserts five things. Positive: an internal session reads another entity's card contents. Negative: a client session cannot, by any route. The bound: the reachable column set is named, so widening it fails a test rather than passing silently. The audit: the action writes its row, a failed audit write fails the action rather than letting it proceed unlogged, the row cannot be altered or deleted through the path, and the application role cannot read the table at all. The boundary: the roster path cannot reach card contents, because two exemptions with no test between them become one mechanism sooner or later.

Neither layer returns card content as opposed to computed output.

A third assertion covers the act rather than a run: removing an entity's authorization clears the publication flag on every card that entity has published, not merely on some (§4.4).

---

9. The internal surface

A separate, HappyShip-only surface. Not a client feature and never exposed to clients. Access is §3.2: the internal surface, plus a login bound to the HappyShip entity.

The client surface's home carries a menu of the four functions, labeled exactly as SCOPE.md names them — one vocabulary across the documents and the interface. A function not admitted is inert: a label, not a route, a stub, or a screen that explains itself.

Above the menu, the client surface shows the entity's own account at a glance. Three counts, each of something that persists (§7): rate cards held, rate cards published, and ship-from locations. A reference standard is readable by every bound session and is not the entity's own card, so it is subtracted from the first. Comparisons run, revenue and invoices audited are not among them and are not stubbed — results are purged, so each would need a durable counter that does not exist (BL-006), and a panel showing something true but unactionable is decoration.

The internal tool covers five areas:

• Manage clients — create, delete and archive an entity, authorize an entity to publish, set the document link. The terms on which a client is created are §3.1. A client is responsible for its own locations; mapping them to regions is optional for the client and may be overwritten by HappyShip staff.
• Manage master data — countries and territories, regions, rate groups, the published national fuel surcharge index.
• Manage rates — create reference standards, define HappyShip charge codes, publish carriers' published rates, draft a client's rates.
• Manage billing — view a client's account, record ACH payments manually, issue coupons.
• Reference documents — rules, vocabulary.

9.1 Master data and the reference standard

Master data has three tiers, cut by whether a carrier owns it — the cut that decides what adding a second carrier costs.

9.2 Internal reference views

The rule report is the internal reference view, and its master is a code module rather than a governance file — which is why it serves the application alone rather than both surfaces, and SCOPE.md does not carry it, under the anti-drift rule every view here holds to: regenerated from its master, never edited in place, or the page becomes a second one. The handbook was the other one and is no longer on this surface at all (SCOPE.md), so it is neither internal nor hosted by the application, and it is looked for there rather than here.

An internal control tower for auditing work performance is intended and is not admitted (§11).

---

10. Billing and metering

HappyShip never processes payments between buyers and sellers (SCOPE.md).

[UNBUILT] Billing covers HappyShip's own clients for HappyShip's services. Stripe is the payment path. ACH and wire are expected later and are managed manually. An entity sees its own account balance; the internal team sees every client's.

[UNBUILT] Coupon codes are stored value in USD. Single-use, expiring three months from issue. An entity may hold several; they draw down first-expiring-first. Invitation and coupon codes are single-purpose and independently redeemable. Invitation is §3.2.

[UNBUILT] Metering is per run. The unit price is master data set by HappyShip, defaulting to $0 in phase 1. The deduction path is real and runs on every job regardless of price, so the block-at-exhausted-balance state is exercised rather than stubbed. What is unsettled is the price, not the mechanism — plan structure, pricing and entitlements are BL-001 in BACKLOG.md.

[UNBUILT] The account surface shows the balance and each coupon held with its expiry, rather than one merged number. Stripe is the path; ACH and wire are instructions rather than a form that submits. An exhausted balance blocks a run and leaves the account reachable so the entity can pay — what that blocked state looks like at the point of running is [OPEN].

What HappyShip charges and how it is computed is RULES-HS-CHARGES.md.

---

11. Not admitted

The boundary. What phase 1 admits, and where each item stands, is the build tally.

Anything not in the build tally is not in scope. If you are asked to build it, stop and ask — and only start work on it after it has been added to the tally.

A dropped item stays in the tally as a ⛔ row with the date it was dropped, never deleted, so this rule keeps a stable referent and nobody has to reconstruct why something is out.

A placeholder is allowed, to remind us of a future build. It must be greyed and not clickable, it carries no value set, and it stores nothing. The deferred work it names must be recorded — as a BACKLOG.md row, or by being named in the not-admitted list below — so the placeholder is a reminder of something recorded rather than the only record of it.

Retention shaping is admitted deliberately, because it would otherwise read as the scaffolding this section governs. Phase 1 purges.

Named explicitly, because each is described somewhere and could be mistaken for admitted: derivation of sell rates from buy rates (§4) · invoice audit (§6) · shipment tracking (§6) · stored shipment sets (§4.1) · card sharing by rateID (§4.4) · the internal control tower (§9.2), which the run record (§7) does not admit — a record is data and the tower is a view over data, and the view is built when it enters the build tally and not before · any leg but the first and any carrier but FedEx (SCOPE.md).

This boundary is the application's alone. The website has its own at WEBSITE.md; neither admits nor forbids anything on the other.

Audience: Claude Code, when a task touches structure.

Scope of this file. How the parts fit together and where new legs attach. Not a schema mirror — the database is the source of truth for schema, and this file records what is not visible from reading the code: why the boundaries sit where they do.

Read SCOPE.md first, then APPLICATION.md. SCOPE.md governs the shared ground — what HappyShip is, the service legs, the source language, and where a commit goes. APPLICATION.md is the authority for the application: what it does, and what the current phase builds. This file says how that is achieved. Where it conflicts with either, they govern and this file is what changes.

---

0. Status

Written before implementation, and parts of it have been overtaken since. The schema gap was filled from what step 0 built (§4.3); the rest of §13 is still open. The markers are SCOPE.md, the terms. An [OPEN] here is not permission to decide — stop and ask.

---

1. Shape

Four layers, one deployable service.

No microservices. No message bus. One service, one database, one object store.

---

2. Stack

Why Python. The engine is numeric and rule-heavy, the XLSX libraries are strongest here, and pricing rules read close to plain sentences — which matters because the product owner reviews logic, not implementation.

Why server-rendered, and why Flask. Every screen is a document — tables, forms that submit, uploads and downloads, a dashboard looked at once and then purged — so a separate front end would be two codebases in two languages for the same screens, with an API contract neither half can change alone: roughly double the build, and more than double the cost of a change, because one new field moves a response shape, a type, a component and everything that read the old shape. Flask rather than FastAPI or Starlette, because both are async, which buys nothing over a synchronous driver in front of a CPU-bound engine and costs a boundary through every handler, and FastAPI's validation and generated OpenAPI describe JSON bodies that no longer exist here. What the choice rules out is a screen assembled in the browser from data an endpoint hands it, not every request that is not a page load. Every page is rendered on the server. One request today returns something other than a page: the company-name check on the internal entity page posts to /entities/name-check when the field is left, and is answered with a status code and no body — held or free — so the page learns one fact and renders nothing from data. This is the reversible direction: a screen that later needs to behave like an application can be built that way on its own, where React everywhere and then simplifying is a rewrite.

Vendors are named in §7 and are deliberately replaceable. Nothing above the vendor line depends on which vendor is chosen.

---

3. The rate engine

A pure function. Given a shipment and a rate card, it returns computed charges. No database access, no network calls, no framework imports. Reference data is passed in, never fetched.

This is the one hard architectural constraint in the system. It exists so the engine can be tested without infrastructure, and so its correctness can be established independently of everything built on top of it.

The template parser (§9) is under the same constraint, for the same reason, and a test asserts it for both: neither module imports a database driver, a network client or a framework. The parser reads a file and returns rows and findings, and nothing in it writes.

Explainability is not optional (APPLICATION.md, engineering rules). It is what makes the engine's output auditable rather than merely correct.

Selecting which rate card applies happens outside the engine. A single upload or invoice may span multiple rate cards. Resolution rules live in RULES-<leg>.md.

---

4. Data

4.1 Database vs object storage

Files never touch local disk. Uploads go to object storage on receipt. Hosted filesystems are ephemeral, and a file written to disk disappears on redeploy. This is one of two constraints that make the local-to-hosted move trivial (§6).

This is a rule about the code path, not about the machine. The application always writes through the object-storage API; where that API points is configuration (§6). Local development points at the object store's free tier — no cost, no emulator, and the same code path as production. It does not mean "no local development"; it means no ./uploads directory.

Results. A costing run produces one result record per shipment per scenario.

Dashboards sort, filter, and display the full result set, so result detail lives in Postgres, indexed for those queries. Object storage holds the generated file for download, not the queryable copy. Results land in Postgres during a run and the dashboard reads them from there; they do not survive delivery.

Because comparison data does not survive a run, the database is small and steady, and library rate cards are the largest permanent thing in it.

Purge triggers. The comparison upload is purged from object storage once parsing succeeds. Result detail is purged from Postgres once the report is delivered. Whether purge is configurable, and what it defaults to, is APPLICATION.md.

Library cards are exempt from purge — they are stored and persist by design (APPLICATION.md, rate cards).

4.2 Limits

Dataset ceilings and append behavior no longer apply in phase 1 — there is no dataset model, and each run is one upload.

A per-upload row limit is still unset. [OPEN]

4.3 Schema decisions from step 0

The database is the source of truth for the schema; the migrations under app/db/migrations/ carry the tables, keys and constraints, and the rule each implements is a comment beside it. This section records only what a reader could not recover from them: why the boundaries sit where they do.

Entity scoping and forced row-level security sit on every table, including the public ones. Regions, the reference-standard designations and the standard's own rows are readable by every entity, and they still carry an owning entity (HappyShip) and forced policies. The alternative, an unscoped table for public data, would be the one table a missing filter could not fail closed on, and the rule that every table carries an owner is worth more than the exception. Forcing binds the migration role too, so the owner cannot be the leak. Two consequences follow, for whoever writes the next migration: a data migration that touches rows must bind its transaction to the entity that owns them, since the migration role sees nothing otherwise; and creating or acting on an entity today is done by a session bound to that entity, until the internal tool's separate logged path exists.

A typed identifier's owner prefix is a CHECK, and the collision check depends on it. rate_cards constrains the first four characters of rate_id to entity_id. Forced row-level security means a session sees only its own entity's rows, while a unique constraint is enforced beneath those policies and sees every row — so a SELECT-based collision check inside a bound session can report clear against a row it cannot see, and the INSERT then fails on a constraint the check never consulted. The prefix CHECK removes that gap by confining every identifier that could collide to the owning entity, which is the session's own visibility. It is a precondition of the ID scheme (APPLICATION.md, the ID scheme), not a local nicety, and a table minting a new type letter without it inherits the gap.

A reference standard is a rate card held by HappyShip plus a designation naming it, not a table of its own. The owning entity on the row is custody and isolation — which entity the row belongs to, and therefore who may read it — never ownership of the rates, which are the carrier's. Its rows have exactly a card's shape, a client's card compares against it cell by cell, and the parser validates a filled template against its structure, so a parallel table would be the same shape twice. The cross-entity read this needs is an explicit, tested policy on the card and row tables, opened only for a designated card, read-only, and beside the two surfaces §5 names. It is not an exception to isolation: an undesignated card HappyShip holds is as private as anyone's, and a test asserts both directions.

A login's key is its email address, and a publication event snapshots that address rather than holding a foreign key to it. The address is the account (APPLICATION.md, identity and access), so nothing else identifies a login. Login deletion is a hard delete and a deleted address may be logged again, while the publication record must keep "this login, at this time." A foreign key would either block the delete or lose the record; the snapshot does neither.

Charge rows carry a sequence; per-zone charge rows do not. Structure is which charges exist, in what order (RULES-LAST-MILE.md), so the order is part of a standard's identity and must be stored, and one charge code recurs across dated rows and brackets, so the row itself does not carry its position. The four per-zone rows are one row per code in an order the doc fixes, so the code alone places them.

[UNBUILT] The fuel rate is scoped by service family — Ground and Home Delivery share one percentage while express is jet-fuel-based — so the table carries that column before a second carrier arrives rather than after. Every row of the fuel series carries its effective date from the first migration, since every read of the series is by governing date and a row without one cannot be placed in it.

The 24 charge codes are a check constraint rather than a table, deliberately. The set is code on purpose (APPLICATION.md, master data and the reference standard): an open catalog is a door to uncontrolled codes, and a constraint a deploy is the only way to widen is what stops the set drifting. A second carrier does not weaken this — it arrives as its own coded set rather than as rows someone types into a catalog, so the constraint is not the thing a second carrier forces open.

[UNBUILT] The rule report will read these same constants (APPLICATION.md, internal reference views) — generated from them rather than describing them, so the constraint, the engine and the page a staff member reads cannot disagree. It arrives at step 5.

Migrations must apply, in order, to an empty database. The test fixture drops and recreates the schema and applies every migration, then seeds, rather than truncating and re-seeding: a truncate cannot restore rows that a NOT NULL data migration populated, since the seed that re-inserts them predates the column. The first data migration failed on a fresh apply and had been masked on the dev database, where the seed had already run before the migration existed; the shape will recur whenever a migration depends on seeded data, and the fresh apply is the only check that catches it.

---

5. Isolation

APPLICATION.md requires isolation at the data layer so a missing filter fails closed. Four mechanisms, in order of what they buy:

1. Every table carries an owning entity, from the first migration. This is the single most expensive thing to retrofit — it touches every table and every query.
2. Postgres row-level security. Policies live on the table, not in application queries. A query missing its filter returns nothing rather than everything.
3. Entity comes from the session, never from the request. Not a URL parameter, not a body field. Set once at authentication; every query inherits it.
4. Adversarial tests, at the data layer and the view layer. A view cannot skip scoping by being written: the lifecycle that binds an entity runs before every request, so there is no per-view opt-in to forget, and a test asserts every rule in the url_map is served under it. What the tests must assert is APPLICATION.md. Nothing runs them automatically. The repo has one workflow and it runs no tests — it regenerates the handbook (SCOPE.md). So the suite gates whoever runs it and nobody else, and a commit reaches main with no test gate, including the bot's. A workflow that runs the suite on every push is wanted rather than built. [OPEN]

Two surfaces reach across entities, and no others. The mechanisms beneath them are listed rather than counted, because the count has been wrong twice — once when the login and session lookups arrived, once when the roster did — and a list gains an entry where a number needs correcting. The list carries no count for the same reason, that being the third time:

• The reference-standard policy. A card designated as a reference standard, and its rows, are readable by any session bound to an existing entity, because reference standards are public (APPLICATION.md, visibility classes) — explicit, read-only and tested in both directions (§4.3).
• The login and session lookups (§10), which no binding could answer, because resolving them is what produces one.
• The roster functions, which return the entity list and create and delete entities (APPLICATION.md, the internal surface).
• The entity-record functions, which read and write one entity's record at a time — its fields, counters, ship-from locations and card metadata, never contents (APPLICATION.md, the internal surface).
• The login-address functions, which read every address across every entity, and create and delete them.
• The content path, below, which is the only one that logs. [UNBUILT]
• The card-entry function, which writes a card and its rows into another entity's library on HappyShip's behalf (APPLICATION.md, who writes a card). It is the only one that writes card contents; the roster, entity-record and login-address functions above it write too. [UNBUILT] It does not log.

What bounds an exemption is the shape of what it returns, never a predicate. A predicate bounds which rows and says nothing about which columns, so a role-scoped policy with USING (true) on a table yields every column of every row — the internal-only ones included — and nothing stops a caller selecting one nobody intended. That is a convention, not a ceiling. Every cross-entity exemption is therefore bounded by its return shape — a definer function's return type, a view's columns, or column grants — so that widening it takes a migration somebody can see. The two lookups above are an instance of this rule rather than an exception to it: each takes one value and returns one entityID, and the signature is the ceiling.

A write exemption is bounded by what it may write, since a return type bounds nothing when the point of the call is its effect. app_card_create_for returns one identifier and writes a card and its rows into another entity's library, so the return type is no ceiling at all. What bounds it instead is the set of tables it touches, its parameter list (there is no parameter for an entity other than the target, nor for a rateID), the values it fixes rather than accepts — a card it writes is always a draft and never published — and the grant that lets it run, held by one role the internal surface alone uses. Widening any of the four takes a migration somebody can see, which is what the rule above is for. [UNBUILT] It does not yet log, and the audit write described below is where that belongs: no cross-entity write logs today, and a write into another entity's library is the one that most obviously should.

The internal management tool (APPLICATION.md) goes through a separate, logged path — never a flag on the normal path.

[UNBUILT] The audit write happens inside the function that returns the contents, in one transaction. Reading another entity's private card contents without logging is not possible because they are one operation, and a failed audit write fails the read. That is structural rather than procedural: nobody has to remember a log line, because the only path to those contents runs through the thing that records it — a designated reference standard is public and readable without a log, which is what the audit is not for. That function meets the bounding rule in the ordinary way — its return type is the ceiling — and the write path is the same shape, the audit row landing in the transaction that creates the card.

[UNBUILT] The application role will hold INSERT and not SELECT on the audit table. It writes and can never read back, which is what makes the table an audit rather than a log the audited surface can read: an internal session can be made to write a row and cannot be made to show one. It inverts the lookup role — that one exists so the application can read what it otherwise could not, this one so it can write what it cannot. Reading the audit is out of band, by whoever holds the migrate credential. Every table carries an owning entity, and here that is the acting entity, HappyShip, because the action is HappyShip's; the target entity is a separate column doing a separate job, and merging the two would file the row under the entity it was written about.

The run-time pool (APPLICATION.md) is the second. It is not an exception to the isolation rules there: it reads only cards whose publication flag is set, and it returns computed results, never card contents. The flag is what the pool tests, never the owner's act. The pool distinguishes none of the ways the flag came to be set or cleared, so a card withdrawn because its entity lost authorization is as invisible as one the owner withdrew. The adversarial isolation tests required by APPLICATION.md extend to it.

Identity is not authentication. Entity scoping exists from step 0 and sessions from step 1; sign-in exists from step 2 (§8). Step 0 runs against a seeded entity with nobody logging into it, and step 1 runs against a real session that nobody has signed in to.

---

6. Portability

Two constraints make the hosting choice reversible. Both cost nothing now and are expensive to undo:

• All configuration through environment variables. No connection strings, paths, or keys in code.
• All files in object storage. Never the local filesystem.

Additionally: run the same Postgres major version locally as in hosted environments, and confirm any extension exists on the target before depending on it.

The move from local to hosted is a few hours' work — provision, dump and restore, repoint environment variables, deploy. The difficulty is never the move; it is data you cannot afford to lose. Move before there is data worth protecting (§8).

---

7. Hosting

Selection rule: every vendor must have a usable free tier and a reasonable paid tier on the same platform. Start free, upgrade in place, never migrate. A vendor that is cheapest at zero but forces a move at scale is disqualified — the migration costs more than the savings.

Each row is one platform from free through production. Upgrading is a plan change, not a move.

Auth is not a vendor and has no row: passwordless sign-in, sessions and entity binding are application code against Postgres (§10), so there is nothing to select, no free tier to outgrow and no user-count threshold to watch, and what auth stores is covered by the Postgres row above.

The application needs no static host of its own, and that is deliberate. It renders its own HTML and serves its own assets from the one service of §1, so nothing of the application's is deployed apart from it and there is no second thing to point a domain at. Two static surfaces do exist beside it and neither is the application's, which is why neither takes a row above: the public website, SCOPE.md's to name and WEBSITE.md's to describe, and the handbook (SCOPE.md). Both sit on Cloudflare, already a named vendor here, so neither adds a platform to select or outgrow.

Prices and tier limits change; verify before committing.

Free-tier compute sleeps when idle. Cold starts are acceptable while testing on internal data and not acceptable once an external user might arrive, so compute is the first upgrade — at the §8 gate.

Point-in-time restore is the one thing not to economize on. Free-tier Postgres generally lacks it. Acceptable for data that can be regenerated; not acceptable once real client rate cards are stored.

Do not introduce Kubernetes, microservices, additional datastores, or a message broker.

Even with upgrade-in-place, §6's portability constraints hold. They are what makes the selection rule a convenience rather than a dependency.

---

8. Build sequence

All steps deliver phase 1 as defined in APPLICATION.md.

Step 0 is not finished, and later steps have run ahead of it. What exists is the schema, the reference-data seed and the parser, plus rate-for-rate comparison — which compares two cards and is not what §1 and §3 define the rate engine as. Step 0 owes two things:

• [UNBUILT] The costing engine. Given a shipment and a rate card, compute charges with an explanation per line (§1, §3). Nothing in app/engine/ accepts a shipment.
• [UNBUILT] Accessorial behavior. The 24 charge codes carry prices and nothing else. No trigger test, no minimum billable weight, no highest-wins evaluation and no fuel evaluator exists, so a code can be priced and cannot be applied.

The invoice verification in step 0's row waits on both, and stays where it is. Nothing is rescheduled and the gate does not move: it is step 0's obligation because the reason below has not changed.

The internal portal moved ahead of everything but the schema. Nothing can be seeded without its screens and nothing can be compared without seeded data. Step 0 still runs against a seeded entity with nobody logging into it (§5); step 1 no longer does, for the reason below.

The session moved into step 1 with the screens, because the two were waiting on each other — sign-in authenticates against pre-registered addresses, nothing can be registered until the logins screen exists, and that screen needs a session to know which entity is acting. What identifies the acting entity is what the row-level security policies read (§5), so a stand-in for it is not cosmetic: it reaches every query written in step 1 and every test around them. Building the seeding screens against a real session and real entity binding from the first line costs less than threading a placeholder through them and pulling it back out in step 2.

The dev-only route that mints a session is temporary work toward admitted work, not scaffolding. What APPLICATION.md's not-built rule forbids stubbing and scaffolding for is work phase 1 does not admit, and auth and login are admitted — so the rule does not reach this, and step 2 carries the obligation that makes it temporary rather than permanent: the route is deleted when sign-in lands.

The route sits inside the entity-binding rule rather than being an exception to it, which is what lets it exist inside the security boundary at all: it supplies an address, finds the login record and mints a session the ordinary way, skipping the code and nothing else, so the entity is still read from the login record and never from the request (§10). It cannot run before a login exists, so the first internal login is seeded alongside the HappyShip entity — the same seed, one row wider.

The first cut is the seeding screens only — create an entity · log an email address against an entity · upload a carrier-published card and name it a reference standard · enter a card on an entity's behalf · the values the card fields read (carrier list, entity list, currency, weight unit, ships-from regions) — not one tier and not all master data, so what step 1 owes each is that it is present, not that it has a page (APPLICATION.md, master data and the reference standard) · authorization to publish. Out of it: coupons, payments, activity metadata and the rule report, all of which stay at step 5. The HappyShip entity is a seed rather than something created through the portal, because internal logins bind to it.

The handbook is not in this sequence at all, and did not move within it. It needs no application running (SCOPE.md), so no step waits on it and it waits on none. It was listed at step 5 while it was a screen of the internal tool, and stopped being one.

Auth moved ahead of self-serve card upload, and not ahead of the whole library. Self-serve upload is an authenticated act by a card's owner (APPLICATION.md), so auth and entity binding cannot sit after it — and that reason reaches upload alone. The rest of step 3's library work depends on a session rather than on sign-in, which the dev-only route supplies, so it ran before step 2 instead of after it: the library dashboard, one card's detail, the lifecycle transitions and the publication act with its consent record are built while auth is not. Email delivery arrives with auth, which is where email infrastructure first exists.

Authorization arrives before the billing it exists to serve, and that is deliberate. It is a setting from step 1, while what makes granting it a paid decision waits for Stripe at step 6. Step 1 asks only whether the flag may be set, never why — which is what lets the pool run locally, before there is anything to charge for entering it.

Report generation lands with the comparison steps, at step 3.

The gate

Steps 0–4 run entirely on the product owner's own data, on the local machine, at no hosting cost. "Local" here means no deployed compute and no paid tier — files still go to the object store's free tier per §4.1, never to local disk.

Before step 5 and before any external user, three checks:

1. Is the engine right? Real invoices, line by line, matching. If this fails, nothing downstream matters.
2. Is the template usable by someone else? The owner will fill it correctly because he knows what every column means. That is exactly what an outside user will not do.
3. Does the output say something the reader did not know?

Expect ingest rejection handling to get its first real test after the gate, not before — internally produced files are unrepresentatively clean.

Step 0 is the load-bearing step

Its cost is not code volume; it is writing down the calculation rules precisely and verifying output against known-correct invoices. If those rules are ready when step 0 begins, the step holds its estimate. If they are discovered through wrong invoice totals, it does not.

---

9. Ingest

Single sheet. HappyShip supplies the template. Which formats it comes in, and what happens to a file that does not conform, are APPLICATION.md. An XLSX with more than one populated sheet is rejected, so the two formats stay interchangeable and the parser has one shape to handle.

The template is generated from a reference standard, with structure locked to it (RULES-LAST-MILE.md). The parser knows the expected structure before opening the file, so conformance is a comparison against that structure rather than an inference from what the file contains.

Input is split between the uploaded file and a web form. Which fields go where is decided by the product owner, not derived. The split is recorded in RULES-<leg>.md, and those two are the whole input surface.

The file is a grid for humans; the database is one row per zone, weight, and service. The parser transposes. Nothing downstream sees the grid.

Template column definitions live in RULES-<leg>.md.

---

10. Auth

Passwordless — a verification code emailed to a pre-registered address (APPLICATION.md, identity and access). No stored passwords, no reset flow, nothing to breach.

The code is six digits. The sign-in screen takes it in six separate fields, one per digit, grouped in one fieldset (home.md, sign-in). Six was decided at the build — the sign-in shell landed with it at 53a57ff — and is written here after the fact: on this point the code led the document, not the other way round. Nothing generates, sends, stores or checks a code yet. [UNBUILT] The sign-in pages are a shell with no code lifecycle, and /dev/session is the only way a session is minted today.

Whether a code is single use is not stated anywhere. [OPEN] home.md names single use among the mechanics this section owns without deciding it, and no code path exists that could make it true or false.

Three more of the code's mechanics are undecided, and none is stated in this file or in home.md:

• How long a code stays valid. [OPEN]
• How soon a code may be resent, and how many times. [OPEN]
• What a wrong code does — whether it costs an attempt, how many attempts one code allows, and whether the screen says how many remain. [OPEN]

Entity binding. The entity is bound at session establishment, read from the login record — never from the request (§5).

Session length. Two limits, and the session ends at whichever arrives first. An absolute lifetime of 7 days from establishment, which no amount of activity extends. And an idle timeout of 24 hours, which every request resets, capped by the absolute — an active user is signed out at 7 days, not sooner.

The cookie is persistent, not a session cookie, so closing the browser does not end the session.

Sign-out ends a session, and it is the only way a user ends their own (APPLICATION.md, identity and access).

Why the limits are this long. Re-authentication here is an email round trip, so every expiry is one more chance for a delivery failure to sit between a client and their own work — and email is infrastructure rather than a convenience, not a property this design can shorten its way out of (§10.1). What a short session would otherwise protect against is a session outliving the right to it, and that is already handled by a stronger mechanism than a timer: deleting a login ends its session immediately, checked per request rather than at expiry (APPLICATION.md, identity and access). Shortening these limits therefore buys little, and is paid for in email round trips.

The login code email is always EN (APPLICATION.md). The code-sending path has no locale to resolve against (§11).

Consequence: email becomes infrastructure rather than a convenience. Every login depends on delivery, which is stricter than password auth where email only matters at reset. It is stricter still now that email carries more than the login code — the welcome email, the delete notification and the owner notification depend on delivery too (§10.1).

10.1 Email is infrastructure rather than a convenience

Email is no longer only the login path. It is infrastructure, not a convenience, and four things depend on delivery: the login code, the welcome email when an address is logged, the notification when a login is deleted, and the notification to an owner when HappyShip has entered a card on that entity's behalf (APPLICATION.md). The report of a completed run is not among them.

---

11. Building for translation

The language policy is APPLICATION.md, language in the application — which locales, per-login selection, how a user-facing string is written while the i18n layer does not exist, and the login code email always EN. This section is only what that policy costs architecturally.

CN is in from step 1, not added at the end. Layout breaks appear per screen; retrofitting means re-reviewing every screen.

The step 1 portal follows the login, since a step-1 session carries a login record and a login record carries a language preference; the browser rule governs only before a session exists, which in step 1 means before the dev route runs (APPLICATION.md, language in the application).

Length is the constraint, and buttons are where it bites. Buttons are fixed-position elements in a row, so one long label displaces its neighbors. Paragraphs reflow and tables wrap — neither is a structural problem.

Detailed styling rules belong in brand/STYLE.md.

---

12. Known future work

Recorded so it is not rediscovered as a surprise. None of this is phase 1. This section holds the architectural consequences of work not yet admitted, not deferred decisions — those are BACKLOG.md.

Cross-carrier zone normalization. A FedEx zone 5 is not a UPS zone 5. Rate-to-rate comparison across carriers needs a common basis — a normalization problem one level above the grid. Does not bite while phase 1 is FedEx-only.

Legs beyond last mile. Warehouse, drayage, and global mile attach at the rate table: the charge model is shared, the table shape is leg-specific.

Higher upload volumes. Present limits are set well below what the design supports. Raising them affects worker memory and result handling, not structure.

---

13. Gaps

Where an open decision lives is SCOPE.md, the terms. This table holds the architectural consequence of one, never the decision itself.

---

14. Running the suite

The test database is named in app/README.md, supplied by nothing and checked by nothing. The suite reads two variables, and app/tests/conftest.py stops the run when either is unset:

There are two roles because the suite tests grants. The migration role builds the schema and binds test data; a grant is tested by connecting as the role it is granted to, and that role is happyship_app. One connection could build the schema or test the grant, never both.

No committed file sets either variable — no dotenv, no shell profile, no default in the fixture — so every run supplies both inline. From app/:

``bash HAPPYSHIP_TEST_DATABASE_URL=postgresql://happyship_migrate@localhost/happyship_test HAPPYSHIP_TEST_APP_DATABASE_URL=postgresql://happyship_app@localhost/happyship_test ../.venv/bin/python -m pytest -q -rfE -p no:cacheprovider ``

The rate card specimen needs no variable: it defaults to the committed fixture.

The fixture drops schema public. It rebuilds from nothing (§4.3): DROP SCHEMA public CASCADE, every migration, then the seed. Nothing in it looks at which database it was given. Pointed at happyship, it destroys dev — the owner's walk entities, and every applied migration with the hash it was verified against — and dev is never rebuilt.

The guard is a precondition on every run, not a step in it. A run does not start unless both hold:

1. Both strings end in /happyship_test. Either one ending anywhere else, and the run does not start.
2. No other run is active. On macOS the interpreter lists as Python -m pytest, capital P, so a case-sensitive match misses it: pgrep -if "python -m pytest" finds a run, and pkill -if "python -m pytest" ends one. There is no timeout command on this machine.

The absence is the defect. A destructive command whose only safeguard is the operator typing carefully is not safeguarded. The warning in app/README.md is that same safeguard, written down.

• Whether the two variables get a committed configuration. [OPEN]
• Whether the guard moves into the harness, out of the operator's hands. [OPEN]

Process lives in tiers, by ownership:

• CLAUDE.md — universal working rules, every project. Part A (behavioral), Part B (code discipline), Part C (universal how-tos).
• SCOPE.md — the project's index: what it is, its terms, which document to open, where a commit goes. It declares every other file the project has.
• XYZ.md — project-specific files, in the repo, each declared in SCOPE.md.

Precedence. SCOPE.md governs project-specific matters. Where the two genuinely conflict, stop and ask.

Part A — Behavioral (applies to all work)

Read the governance files first. SCOPE.md at the start of every task — in Code, from origin/main; in a chat, the project-folder copy, treating its line-1 stamp as a claim. CLAUDE.md Parts B and C when the task touches the repo or governance. Then only the docs the task touches, from the set SCOPE.md lists. Read once per chat at the first task; after a prompt lands, check line 1 of each governance file and re-read only those whose version changed.

Governance files are not permanent. When a discussion produces a claim that conflicts with one, amending is a decision that waits for my go: the rule and its reason go into the doc that owns them. Raise it, agree it, amend the file — then build. Never build to a decision a document still contradicts.

If a required governance file is missing, stop and ask. If SCOPE.md itself is missing, ask whether it was not uploaded or this is a new project (Part C).

Discussion mode by default — wait for the go. No prompts, code, or files until I say so. Surfacing options and recommending one is always fine. Do not draft until all your own questions are answered.

Be concise and direct. Push back when you disagree. Do not explain your reasoning unless asked.

Match the mode. Not every chat is about code; if unsure, ask.

Don't guess. If something is missing, ambiguous, or uncertain, stop and ask. When you agree with a proposal of mine, restate it more concisely without drifting toward your own phrasing; if you still see a problem, say so.

Flag once, then comply. A conflict with a governance file or an earlier decision is said once in the chat, then the work proceeds as asked and the amendment lands in the same batch. Once I have given a reason and said settled, the point is logged with its reason and is not raised again.

Don't add what wasn't asked for. No inventing, extrapolating, or writing conclusions into a governance file without my go. Do not invent local folders — ask where temporary files go.

State a limitation only where it qualifies the answer, never as a standing disclaimer.

Write US English, unless SCOPE.md sets otherwise. Identifiers, file paths, CSS custom properties, quoted third-party text, and files synced in from another repo keep the spelling they have.

The repo is the source of truth. Git main is authoritative — not another conversation, not memory, not an attached or synced copy. On conflict, flag, stop, and ask.

Show a draft in its own format. A governance doc as a markdown file, a page as HTML, a deck as slides. A prompt for Code stays in a code block.

Prompts are for Claude Code. Clear, scoped, based on what we discussed, always in a code block. An amended prompt is regenerated in full.

One prompt at a time. Give me the first, wait for the result, then the next.

Handoffs are for a new chat. Suggest one when a conversation drifts, runs long, or a session closes. Written in a code block.

Part B — Code discipline (projects with a git repo)

Clauses referencing origin/main, pushing, or PRs apply only where the repo has a remote; the rest apply to local-only repos too.

Read governance docs from origin/main. git fetch origin first, then git show origin/main:<file> — never the working tree, never the project folder. The folder copy's line-1 stamp may be read for the sync audit.

Sync audit. At the start of every repo-touching task, compare line 1 of every governance file SCOPE.md lists (plus CLAUDE.md, SCOPE.md, and any stamped non-.md governance file) between origin/main and the project folder. Code reads git; the chat reads the folder; each supplies its half. Where they differ, the higher version is current — flag it and sync to it.

Verify the git identity before pushing. gh auth status at the start of any task that will push; confirm it matches the account in SCOPE.md. Never run gh auth switch or gh auth login — on a mismatch, stop and give me the command.

Governance docs go direct to main, pushed immediately. No branch, no PR. Exception: a governance file SCOPE.md declares publicly served keeps branch and PR for an authored change. A generated file is never branch-and-PR; its generator and sources are. Sources first, then the regenerated file in its own commit on top. Never one commit, never an amend.

Governance docs carry a version stamp. Line 1 is exactly v### | yyyy-mm-dd | #### lines — nothing above it. A file whose format forbids bare text at the top carries the same stamp on the first line of its opening comment. Bump v### once per commit, not per revision. Date and line count come from the machine (date +%F, wc -l), local timezone, never typed.

Correcting a claim means correcting what justified it. After an edit to a governance doc, run the reason check (it prints every because, since, which is why, so that, the reason, this means sentence in the touched sections) and put its output in the recap. Each hit that no longer follows is fixed in the same commit.

Protect main when it deploys from main. Branch and PR for anything on a deploying surface that nothing validates; direct to main for anything the build validates before publishing, plus governance docs. The test: does a bad commit reach readers with nothing catching it? If unclear, ask. Where the project does not deploy from main, commit direct and branch only for isolation.

PR flow: one feature branch per task from an up-to-date main → commit locally → push the branch. When I say PR, Code opens it, merges it, and cleans up (git checkout main, git pull origin main, git branch -d <branch>, git remote prune origin) in one run, no stop between. I look at the result on main. Name it type/short-description; type is one of feat, fix, docs, refactor, chore, style, test, perf, build, ci, uat.

Style changes get their own commit. When a UI/UX decision applies project-wide, ask whether STYLE.md and/or the token file should change. Any change to either is its own commit.

A bug found in a task is fixed and tested in that task. It becomes a tracker row only when it is outside the task's scope and I say so.

Show client-facing changes on localhost before commit, with caching disabled or a cache-busted URL. Every URL handed to me — localhost or live — is a full link I can copy-paste, requested by Code first and confirmed to answer 200, and it goes in the recap. A live URL is checked after the deploy confirms, never before.

A run that commits, bumps a stamp, or raises a finding ends with a recap (Part C).

Part C — Universal how-tos

how-to: keep CLAUDE.md in sync

The master copy lives on local disk at /Users/swai/sw805206/CLAUDE.md. Every project repo holds a copy and reconciles against the master.

Publishing a change (project A). Edit the copy in project A's repo, commit to main, copy the file back to the disk master. Not finished until both.

Reconciling a copy (any project). At the start of a task, compare line 1 of the repo copy against the disk master; sync to the later version automatically and report it. Disk master later: copy in, commit, push. Repo copy later: copy out.

Human steps after any change. Re-paste Part A into Claude's global settings; upload the current file to each Claude project folder.

how-to: start a new project

1. Bootstrap. I create a Claude project folder, upload CLAUDE.md, and describe the project. Finding no SCOPE.md, the chat asks whether one is coming or whether this chat authors it.
2. Author SCOPE.md. Discuss, then write v001 beside CLAUDE.md. It declares the project type, the files it requires, whether it deploys from main, and its branch/PR discipline.
3. The repo, where the project is git-related. Path recorded in SCOPE.md. Before the first commit, git config user.email in the fresh clone must match the account the project owns. Use the clone URL form belonging to that account.
4. Scaffold every file SCOPE.md names, at v001, direct to main with SCOPE.md — except a file declared publicly served, which takes branch and PR from creation. Copy CLAUDE.md from the disk master, byte-identical. Ignore local tooling directories at creation.

SCOPE.md v001 is hand-stamped; the first Code commit corrects it.

how-to: write a handoff

A handoff transfers what a chat knows to a new chat in the same project. It is never written to a file. The old chat stays open until the new one has picked up the work; anything needed beyond that window belongs in the repo.

It must carry:

1. What was done, and what is open, in enough detail to act on.
2. Provenance on every claim — verified against the repo this session, or inherited from the last handoff.
3. The repo, precisely — HEAD commit, tree state, suite numbers, open PRs, anything waiting on me.
4. Which .md files are stale, and the version each should be.
5. Every open tracker row touched this session, by ID.
6. Next steps in order, marking which is a discussion and which is a prompt.
7. What was dropped, and why.
8. Environment landmines no governing doc records.

how-to: write a recap

Code's last output of a run that committed, bumped a stamp, or raised a finding. A code block, for paste-back to chat.

1. Outcome — executed, or stopped and why (misalignment, error, bug), and what is needed from me.
2. Done — what changed, with commit SHAs.
3. Tested — what and how; a user action counts only if the test performed it. The URL to look at, localhost or live, confirmed answering.
4. Found — findings and misalignments, each with its tracker ID.
5. Stamps — every file bumped, with its new version. This is the chat's half of the next sync audit.
6. Suggested next, if any.

Every table and field in the application database, and who writes and reads each. The schema in the repository — app/db/migrations/ and app/db/migrate.py — is the truth, and this file describes it. It is rendered in the handbook.

---

schema_migrations

entities

logins

sessions

regions

ship_from_locations

rate_cards

reference_standards

rate_card_conditions

rate_card_regions

rate_card_grid_rows

rate_card_zone_charge_rows

rate_card_charge_rows

publication_events

entity_counters

type_letters

comparison_runs

Audience: anyone implementing or quoting what HappyShip bills.

What HappyShip charges its own clients, and how it is computed. It spans every phase and every leg, and it covers HappyShip's own fees only — never charges between a buyer and a seller.

Contents are [OPEN].

Audience: Claude Code, for any task touching leg 1 rating, the rate card template, or comparison.

Scope of this file. One leg, all of its carriers. Leg 1 is last mile (SCOPE.md, service legs).

In practice, this file is FedEx Ground and Home Delivery. §2 through §7 are written against that carrier throughout — the charge code set, the 139 divisor, the trigger thresholds and the grid shape are all FedEx's, not the leg's. A second carrier arrives as its own sections under §8 rather than as a new file (SCOPE.md, service legs), and §8.2 records what it will need.

Read SCOPE.md first. Where the two conflict, SCOPE.md governs.

What else this work needs.

---

1. Status

Settled: the rate card template (§2), rate conditions (§3), and rate-for-rate comparison (§5).

Not settled: shipment-cost calculation order (§6) and the shipment template (§7), each marked on the section that owns it · the aggregate presentation of comparison output [OPEN], which owns no section and is marked here.

---

2. The rate card template — phase 1

2.1 The template is generated, not blank — phase 1

• A template is generated for one reference standard, chosen before download, which is why the standard is not a post-upload form field (APPLICATION.md, ingest). The standard is named in the file's header block.
• Structure is locked to that standard: which charges exist, in what order, with what unit and what brackets. The client supplies amounts, and dates where theirs differ.
• Two cards naming the same standard cannot differ in shape. The structural-equality requirement of §5.5 is therefore a backstop against edited files rather than a routine outcome.
• Language follows the login (APPLICATION.md, language in the application). It is not a download option, and the file is never bilingual.

2.2 File shape — phase 1

• One populated sheet. CSV and XLSX are interchangeable (APPLICATION.md, ingest), and a CSV has no sheets — that is the reason.
• Two blocks in one rectangle. The weight-by-zone grid on the left; the charge block to the right of the last zone column, separated from it by one empty column. Placed right, every column means one thing from top to bottom. Stacked below, a value column would mean "zone 2 rate" for the grid rows and "amount" for the rest, and a column that changes meaning mid-file is a silent wrong answer.
• A header block travels with the file, carrying the reference standard, carrier, service group, leg, template version, and the card's effective from and to. It is what lets the parser read a filled file standalone and what satisfies the export-complete rule (APPLICATION.md, output is whole).

2.3 The FedEx Ground & Home Delivery charge code — phase 1

• Every charge row carries a code in a hidden, locked column. HappyShip assigns it; a client never types it.
• Why it exists: the label is translated, so the label cannot be the key. Position alone would work while the structure is locked, but fails silently if a row moves, and it leaves an exported file uninterpretable without HappyShip's mapping — which the export-complete rule exists to prevent.
• The code is hidden rather than removed so it survives a CSV round trip and the file stays self-describing.
• The set, closed: AHS-D, AHS-W, AHS-P, OS, RESI, DAS-C, EDAS-C, RDAS-C, DAS-R, EDAS-R, RDAS-R, ADDR, SIG-A, SIG-D, SIG-I, DATEC, UNAUTH, HAZMAT, INS, DMD-RESI, DMD-AHS, DMD-OS, DMD-UNAUTH, DMD-RESIPK. The marker row's code BASE (§2.4) is a structural code, not a charge: it is not in this set and never appears in the charge block.
• Naming convention, so a second carrier follows it: the modifier precedes the base (EDAS-C, RDAS-C), and DMD- prefixes the code of whatever it modifies.
• One code, many rows. A row is identified by its code plus its effective-from date, plus its bracket where one exists. UNAUTH appears twice because FedEx renamed the charge mid-year; INS twice for two brackets; each DMD- code three times for three windows.
• Grid rows below the BASE marker row carry no code. A row is identified by its code, or by its numeric Item where the code is blank — a weight is already language-independent.

2.4 The grid — phase 1

• Rows are weight in whole pounds, 1 through 150, contiguous — no gaps and no bands. A file with gaps or bands is rejected.
• 150 lb is FedEx Ground's per-package ceiling, not an arbitrary limit.
• Columns are zones 2 through 8.
• AHS Dimension, AHS Weight, AHS Packaging and Oversize are per-zone but not weight-indexed. They sit in the same grid under the same zone headers, above the weight rows, separated from them by a required marker row.
• The marker row carries the code BASE in the hidden code column, like every other structural row. Its visible cell is display text and is translated; the parser reads the code, never the label. The label is translated, so the label cannot be the key — the same reason the charge code exists (§2.3). A file missing the code is rejected rather than read as weight rows. Formatting does not survive CSV, so the marker cannot be a fill color either.
• The grid takes its effective dates from the header block, not per row. A base grid changes once a rate year; 150 identical date pairs would be 300 cells that always agree.

2.5 The charge block — phase 1

Columns: Code (hidden), Charge, Charged as, Value from (hidden), Value to (hidden), Effective from, Effective to, GD, HD.

• Charged as carries the unit and, where one exists, the bracket, as display text — "flat", "flat, $100.01~$300", "per $100, when $300+", "105~125%". This is not a parsing hazard: the column is locked and generated from the reference standard, so the client cannot type into it, and the machine reads the bracket from Value from and Value to. The cell only has to be legible to a person.
• Value from and Value to hold a bracket's boundaries as numbers. Both are hidden and locked, like the code column. Both exist because the prose is legible and the numbers are parseable, and neither can be typed into — the same arrangement as the code column, machine-readable underneath and legible on top. Both are blank on a charge that carries no bracket. Insurance is the only bracketed charge in this leg; the columns exist for the shape rather than for the count.
• Effective from and Effective to are per row, so a dated surcharge window is rows and a new one is new rows rather than a new file format. A blank Effective to means open-ended.
• A renamed charge is two dated rows under one code, not an edit. Recorded so an invoice from either side of a rename stays explainable.
• GD and HD are per-service columns. Service is a column only in this block, never an axis on the grid (APPLICATION.md, ingest).
• A blank Charge name means the row continues the charge with the same code above it.
• Blank rows separate charge groups. The parser skips them; a blank row does not terminate the block.
• Demand — Residential Delivery Charge is excluded, and the exclusion is stated in output. FedEx computes it weekly from the client's own shipping volume against a peaking factor with a two-week lag, and no contracted discount applies to it, so it cannot be expressed as a priced row. The peaking-factor tier table is carried as reference only under DMD-RESIPK and is not costed.

2.6 The form — phase 1

Fields entered on the web form, not in the file:

• Nickname.
• Rate owner — the owning entityID. Not shown when a client uploads its own card, since the entity comes from the session (APPLICATION.md, identity and access). Selectable from the entity list only when HappyShip enters a card on an entity's behalf.
• Dim factor.
• FSC discount.
• Currency and weight unit, displayed but locked — they come from master data.
• Notes, free text, never parsed.
• Conditions, per §3.

The effective dates are not on the form. They are in the file's header block (§2.2).

The governing test: the file holds anything with one uniform row shape, however many rows. Anything carrying parameters of its own goes on the form.

2.7 Dates — phase 1

• Every date is a real date, rendered YYYY-MM-DD.
• A CSV must carry ISO dates. Any other format is a rejection, not a guess — Excel exports a date in the system locale's format, so the same file saved on two machines produces two different CSVs, and one of them reads May as January.

2.8 Prefilling — phase 1

• A template ships prefilled with the reference standard's published values. It is not offered blank.
• A blank file gives the filler no reference for what a valid entry looks like. Clearing is one action for the rare client who wants to start empty.
• The hazard this creates is handled at upload, not download. A client who overwrites the grid and forgets the accessorials ships a file whose accessorial rows still hold published values, which parses clean and reports a 0% difference. §2.10 covers it.

2.9 Reading the file — phase 1

The parser cannot trust the file's formatting. Paste replaces format, so a pasted cell may hold a number as text, a date as a serial, or a currency-formatted string.

• Normalize what has one reading: strip currency symbols, thousands separators and whitespace including non-breaking space, normalize full-width digits, then coerce.
• Reject what has two. A value whose decimal separator is ambiguous is a rejection naming the cell, not a guess.
• Check type before coercing. A numeric cell holding a string is recorded as coerced even where coercion succeeds, so it reaches §2.10.
• A date cell holding a number is a serial only within a plausible range; otherwise it is a rejection.
• The hidden code column cannot be pasted over, being locked, so it is the anchor the parser reads structure from, whatever happened to the amounts beside it.

2.10 Conformance, rejection and confirmation — phase 1

• A file that does not conform is rejected with its reasons before anything is stored. There is no post-parse edit screen (APPLICATION.md, ingest).
• The reason list is exhaustive on the first pass. The parser does not stop at the first error. A fail-fast parser turns a twenty-error file into twenty round trips.
• A header block that contradicts the form is a rejection, not an override.
• Separate from rejections, the upload reports what it read and does not block. Rejections stop the upload; confirmations do not, and mixing them either blocks what should not or lets through what nobody looked at. The report:
• rows still matching the reference standard exactly, as a count
• cells at or above the published value, listed
• cells below the plausibility bound, listed
• cells coerced from text, as a count
• empty amounts, as a count
• The plausibility bound is master data set by HappyShip, one bound for every block. It flags where the client value divided by the published value is below 0.10. It is recorded as a ratio, not a percentage, because "10% of published" reads two ways.
• Zero and blank are different findings and are not counted together. A typed 0.00 means waived; an empty cell means no rate and renders n/a.

---

3. Rate conditions — phase 1

Each condition is marked must-met or prefer-met by whoever sets it (APPLICATION.md, rate cards). The seller marks each condition explicitly, per card. There is no default.

The set is closed at three:

1. Minimum spend per month.
2. Ships from — one or more regions, or the value meaning all regions, which is exclusive of any specific region. Regions are cross-leg master data (APPLICATION.md, regions); the list as it stands is §3.2.
3. Fulfillment combo — the rate must be used together with the seller's fulfillment service.

Each is evaluated against a serviceability fact the requesting entity supplies per run (APPLICATION.md, serviceability facts). The three facts are: stated monthly spend, a stated set of regions or none, and stated fulfillment stance — willing to use the seller's fulfillment, or keeping their own.

• An unstated fulfillment stance means open to it. The alternative silently shrinks the pool.
• Fulfillment cost is never modeled. The condition includes or excludes a card and nothing more. This is a boundary: the warehouse leg is not built (APPLICATION.md, phase 1).

Several conditions on one card are an AND. The buyer must meet all of them. Several regions or facts stated by the buyer are an OR, with a full match being the perfect one — which is why stating more widens the pool rather than narrowing it (§3.2).

3.1 How a card is identified — phase 1

Reference standard → rate group → rateID → nickname. That a card names the standard it is compared against, and what a reference standard is, are APPLICATION.md, rate cards.

• The reference standard is the carrier's published rates. A carrier publishes official rates once a year and continues to issue edits, conditions, new rates and seasonal charges through it. Example: FedEx Ground & Home Delivery 2026.
• The rate group is assigned by HappyShip when a reference standard is selected. It drops the year and keeps the carrier's main services. Example: FedEx Ground & Home Delivery.
• The rateID is a rate with a set of conditions defined on the form (§2.6). One of the first selections is the rate group, which is how the two are mapped.
• The nickname is user-defined per rateID and shows on the user's dashboard.

3.2 Ships from — phase 1

The region list as it stands — one list across every leg (APPLICATION.md, regions), written here because last mile is the only leg built: Southern California; New York / New Jersey; Houston / Dallas; Chicago; Savannah / Atlanta; Others; and the all-regions value.

• A seller never selects Others. Where a seller's ship-from location falls outside the list, HappyShip adds a region to master data (APPLICATION.md, regions). A seller's declaration is always a reference, never free text.
• A requesting entity may select Others and supply free text. That text matches nothing, so a card cannot satisfy a must-met test against it; it flags and reaches the consultation.
• The requesting entity states a set of regions per run, or none. A card qualifies where the two sets intersect, or where the card declares all regions. Stating more regions widens the pool rather than narrowing it.

---

4. Reference data this leg needs — phase 1

Not on a card. Some of it is master data HappyShip maintains; the rest is code, and which is which is APPLICATION.md, master data and the reference standard. The markers are SCOPE.md, the terms.

• ZIP to zone lookup — audit-era, not phase 1.
• The trigger definitions for AHS Dimension, AHS Weight, AHS Packaging, Oversize and Ground Unauthorized — code, not master data. Each is an engine test rather than a value a row could carry, and the values are §4.1. A FedEx amendment to one is a deploy.
• Minimum billable weight rules — code, not master data. They arrive with the trigger that imposes them, so they are coded where the trigger is; the values are §4.1.
• Weekly published fuel surcharge rates, dated. HappyShip consumes FedEx's published weekly percentage and not the diesel bands it derives from: loading the bands would mean ingesting the diesel index weekly and reproducing FedEx's lag for the same answer, with drift producing a wrong number silently, and they earn their place only for invoice audit, which is deferred. The shape is an append-only weekly series — effective from, effective to, the percentage, and the index date it derives from — so history is the table and it needs no versioning.
• The set of charges the fuel surcharge applies to — code, not a boolean on a maintained catalog. The accessorial catalog is itself code, so the flag is a property of the coded set rather than a column someone edits; declared value is not on FedEx's list. FedEx publishes this list and may amend it, and an amendment is a deploy.
• DAS ZIP lists — audit-era, not phase 1.
• Insurance bracket structure. [OPEN]

Neither zone list is phase 1 work: a shipment profile carries the zone, so shipment-cost never resolves ZIP-to-zone and rate-for-rate compares zone 5 against zone 5, which leaves both to invoice audit.

The accessorial catalog is not a page. The question this file used to hold open — whether a fuel-bearing charge needs engine behavior attached, or is only a priced line that gets summed — was asked because it decided whether the catalog could be a maintenance page at all. It cannot, and the reason is the one that made the question urgent: the engine has to know what each charge does, and a name it has never seen can be parsed but not applied. The catalog is code (APPLICATION.md, master data and the reference standard), so a charge and the behavior attached to it are added together or not at all, and the question no longer has a decision resting on it.

The asymmetry, which runs through this whole file: a card supplies the PRICE of a charge; the TEST that decides whether the charge applies is never on the card. A card says what an oversize package costs and never what makes a package oversize. The test lives in code, not in master data — which changes who amends it and how, and not the asymmetry itself.

A card may override a default where a client has negotiated one, whether that default is master data or code. The dim factor is the known case: the divisor default is coded, and the card carries a form field (§2.6) where a client enters its own — so a negotiated dim factor is still data, and coding the default did not make it a deploy. A negotiated insurance bracket boundary is not supported in phase 1: Value from and Value to are locked and generated from the reference standard (§2.5), and no form field carries them, so a client cannot overwrite the threshold. Admitting it later is unhiding those two columns, not a format change.

4.1 FedEx published values — phase 1

Sourced from FedEx's published 2026 rules. Every value below requires verification against the FedEx service guide before any code depends on it.

• Dimensional weight is volume with each dimension rounded up to the whole inch, divided by 139 for US domestic. Billable weight is the greater of dimensional and actual, rounded up to the whole pound.
• AHS Dimension: longest side over 48 in, second-longest over 30 in, cubic volume over 10,368 in³, or length and girth over 105 in. Minimum billable weight 40 lb.
• AHS Weight: actual weight over 50 lb domestic.
• AHS Packaging: not fully enclosed in a corrugated container. Tests a description, not a measurement, so it must be declared on a shipment row.
• Oversize: length over 96 in, length and girth over 130 in, cubic volume over 17,280 in³, or actual weight over 110 lb. Minimum billable weight 90 lb.
• Ground Unauthorized: over 150 lb, over 108 in length, or over 165 in length and girth. Applies to Ground, Home Delivery and International Ground at one amount.
• Highest wins. Where a package qualifies for more than one of the above, only the highest applies, assessed after discount. The engine evaluates all of them and returns one line.
• The AHS Dimension minimum billable weight applies even where the AHS Dimension charge itself is suppressed by the highest-wins rule.
• Demand surcharges are additive, not highest-wins. The two families behave oppositely.
• Fuel is assessed on the net package rate plus a named subset of surcharges, not on the base rate alone. Insurance is not in that subset.

---

5. Rate-for-rate comparison — phase 1

5.1 What it is and is not — phase 1

• It compares two cards cell by cell and returns a percentage delta matrix plus an aggregate. It is a price-list comparison, not a computation.
• No triggers are evaluated, because there is no package to test.
• It cannot produce a total. Which card is cheaper overall depends on the package mix, which rate-for-rate does not have. Summing a price list looks like an obvious improvement to whoever finds it later; it is not one.
• Highest-wins is unavailable here. AHS Dimension, AHS Weight, AHS Packaging and Oversize compare as four separate rows.

5.2 The pairings — phase 1

[UNBUILT] Three, fixed:

The pairings are fixed because the anchors are what make the output interpretable. A user-supplied pairing has no anchor.

The anchor follows the pairing and never moves with the arithmetic. An anchor that moved would mean the entity's card to the reference standard read one direction this month and another the next.

The reference standard anchors every pairing — the entity's own card, the recommended and every alternative alike — so every figure in the output is a percentage below one published rate. Because the reference standard is public and named in output (APPLICATION.md, isolation and visibility), it is a base both parties can see, and the figures can be read against each other. A figure against the entity's own card is private to that entity, cannot be read against the other figures in the same output, and means something different for two entities holding different cards. What the entity is deciding is still whether to move off its own card, and that reading is the difference between its own figure and the recommended's, on one scale.

5.3 The recommended and the alternatives — phase 1

• The recommended is the cheapest published card satisfying every must-met condition, shown where it beats the entity's card. It is drawn from the serviceable pool. Where nothing in that pool beats the entity's card, there is no recommended.
• A prefer-met failure is a flag on the card and nothing else. It does not filter and it does not rank (APPLICATION.md, conditions). A card carrying one can be the recommended.
• Alternatives are published cards cheaper than the recommended, each with one or more must-met conditions unsatisfied. Where there is no recommended, the test is cheaper than the entity's card.
• Cheapest first, one flat list — no cap, and no grouping by condition type. A card can fail two conditions at once, so a list grouped or capped per type would present a card under one lever while a second still blocks it.
• Each alternative shows the condition types it fails — never the threshold value, never the owner, never line detail, never a matrix. Where a card fails two, both are named.
• Where there is neither a recommended nor any alternative, the output states that the entity's rate is competitive and offers to publish it. That is the whole result in that case: nothing in the pool beats the entity's card, so there is nothing to rank.
• APPLICATION.md (isolation and visibility) permits an excluded card to be priced as an alternative and holds the limits on what may be shown beside it. The count-and-reason rule still governs every published card not surfaced as one. Must-met still decides whether a card can be recommended, and it no longer keeps that card's price from an entity that does not qualify — the trade is DECISIONS.md.

5.4 Determining cheapest — phase 1

• [UNBUILT] Evaluated after divisor mapping (§5.6), anchored on the reference standard. Ranking on raw card rates first produces the wrong card, because the divisor reorders the ranking.
• The requesting entity may nominate its most important weight band, chosen from the list and never entered as a weight; if it does, cheapest is cheapest in that band. The bands are the 15 the grid implies — 10 lb each across rows 1 through 150, so 1-10, 11-20, through 141-150 — the same bands the heat map uses (§5.7).
• If it does not, cheapest is the unweighted mean of the base grid, excluding AHS and all other accessorials.
• Where a divisor mapping truncates (§5.6), cheapest is computed over the anchor rows that resolve. Two candidates with different divisors may therefore be ranked over different row sets, and a candidate whose heaviest rows fall off the grid is measured without them. This is a limit of the measure, not a correction to it, and the truncation is reported alongside the ranking rather than left implicit.
• The ranking is an average — over a weight band and over zones — and every rate-for-rate output says so. It points to shipment-cost comparison (APPLICATION.md, the two comparisons), which prices an actual shipment profile, as the more accurate answer. This is the same principle as the truncation sentence above, applied to the whole measure rather than to one mapping: it qualifies the recommended, every alternative and the competitive result alike, and is not a footnote on one of them. It belongs to rate-for-rate alone — shipment-cost averages nothing, and the same sentence there would be false.

5.5 Structural equality — phase 1

Both cards must share a structure or the comparison is rejected: same zone set, same weight ceiling, per-pound rows. Non-standard weight banding is rejected — the HappyShip template is the supported path.

5.6 The row axis is volume — phase 1

• The invariant is the box, not the weight row. Two cards with different dim factors put the same package in different rows.
• For each anchor row w, volume is w multiplied by the anchor's divisor; the comparison card's row is that volume divided by its own divisor, rounded up.
• Where divisors are equal this degenerates to row-for-row. One rule, not two.
• The mapping is not one-to-one, so the matrix reads in one direction.
• Where the mapped row exceeds the comparison card's grid, those rows have no counterpart and are reported as such rather than omitted silently.
• The matrix compares dimensional weight on both sides, so it holds for dim-dominant packages. A dense package bills at actual weight on both cards and the divisor advantage does not apply. This is stated on the output, not footnoted.

5.7 Output — phase 1

• A heat map. 15 weight bands of 10 lb each, zones 2 through 8.
• A band's figure is the unweighted mean of that band's computed cells, the same rule the aggregate uses. A cell that is n/a or not computed is not in the mean. This is a second averaging layer above the aggregate's, and a band mean can hide a spike inside it.
• The aggregate is the straight unweighted mean across all computed cells — grid, per-zone charge and flat alike. It is unweighted and therefore structural — not what any shipper pays. Rate-for-rate has no volume profile by definition, and naming this stops someone later adding a weighting nobody supplied. This is not the measure cheapest is ranked by (§5.4): that one is the unweighted mean of the base grid alone, accessorials excluded. Two populations, two purposes — the aggregate describes the whole matrix, cheapest ranks cards on the grid.
• Computation is exact rational arithmetic throughout, rounded once at the boundary. Summing a thousand already-rounded cells drifts, and the mean of a thousand identical deltas then differs from the delta itself. This was observed, not anticipated.
• AHS Dimension, AHS Weight, AHS Packaging and Oversize appear as rows inside the zoned matrix, because that is how the file supplies them.
• Flat charges appear as a single cell.
• Where the reference card carries a value and the entity's card does not, the cell renders n/a. The engine cannot distinguish an omission from a deliberate absence, and n/a claims only that there is nothing to compare, where "data missing" makes a claim about the file. No substitution, and no conclusion drawn either way — an omission and a deliberate absence cannot be told apart from the file.
• Where the anchor's value is zero, no percentage is returned. The cell reports not computed and shows the anchor value. A percentage of zero is not a figure, and returning one would be a number nobody could explain (APPLICATION.md, engineering rules). This is a different finding from n/a: n/a is nothing to compare, not computed is nothing to divide by.
• A cell still holding the reference standard's published value is not distinguishable from a negotiated rate that matches it. That is why the count of such cells is reported at upload (§2.10) rather than inferred at comparison.
• Substitution of the reference standard for missing mandatory data (APPLICATION.md, compare rates) applies to a costing run. Rate-for-rate computes no cost, so nothing is substituted and a missing value renders n/a.
• The dim factor advantage and the FSC discount are stated in the report, not folded into the map.
• Colors, banding and layout are brand/STYLE.md. They are not restated here.

---

6. Shipment-cost comparison [OPEN]

Not yet written. It needs: calculation order, the interaction between minimum billable weight and the base rate, and the shipment template (§7).

---

7. The shipment template [OPEN]

Not yet written. What is settled: a shipment row carries length, width, height, weight, origin, destination, service and ship date, plus declared flags for residential or commercial, AHS Packaging, hazardous materials, signature option and declared value. DAS is derived from master data, not declared.

---

8. Carriers — phase 1

8.1 FedEx — Ground and Home Delivery (phase 1)

§2 through §7 describe it. No carrier-specific variation beyond what is already stated.

8.2 Other carriers — not admitted

UPS, USPS, Amazon and OnTrac are names in the coded carrier list and are not built — the name is there, the reference set behind it is not (APPLICATION.md, master data and the reference standard).

A second carrier in this leg needs a normalization layer before anything compares across the two. Recorded here so it is not discovered at build time; nothing acts on it now.

• Zones do not correspond. A FedEx zone 5 is not a UPS zone 5, so a zone-indexed grid cannot be read across carriers without a mapping (ARCHITECTURE.md, known future work).
• Charge codes do not correspond. The set at §2.3 is FedEx's, closed and coded. A second carrier arrives as its own coded set, so comparison needs a mapping between the two — and where a charge exists on one side only, an absence rather than a zero.
• Trigger definitions and minimum billable weights do not correspond. §4.1's thresholds are FedEx's published values. Another carrier's AHS equivalent tests different measurements at different limits, so a package can be surcharged on one card and not the other for reasons the comparison must state rather than net out.
• Structural equality (§5.5) currently rejects what it cannot compare. That is the right behavior while one carrier exists; across carriers it would reject everything, so cross-carrier comparison is a different mechanism rather than a loosened check.

---

9. Open items [OPEN]

Audience: Claude Code and Claude chats, at the start of every task.

What this file holds. What HappyShip is, the terms, which document to open, where a commit goes, what the handbook renders. The index: a file not declared here does not exist.

---

0. Rules for using this document

1. Open the one document for the surface you are working on (§5) and follow it onward.
2. The terms are §0.1, the one place they are defined.
3. A rule written for the website or the application does not carry to the other unless it says so.
4. A reference that crosses a file names the file and the topic, never a section number. A restructure searches the other files for the old names before it lands.

0.1 The terms

Markers, in any markdown document:

Square brackets mark these two and nothing else. Anything not done is a TRACKER.md row, never a note in the prose. Built things carry nothing; the repository is the evidence.

The tracker row: | T-### | Phase | Status | Item | Evidence |. Phase names the phase in §3.3, or is blank for work belonging to none.

A row walks open → unbuilt → built → done. A revision sends it back to open or unbuilt on the same row, with one line appended saying why.

IDs are assigned when the row is raised, in sequence, never reused.

---

1. What HappyShip is

HappyShip provides logistics rate analytics and advisory. The analytical services are rate comparison, rate management, invoice audit and shipment tracking; the advisory services include rate negotiation and rate sourcing. It is a control tower: it holds the analytical picture, it does not hold the commercial relationship, and it does not profit from rate arbitrage.

Sells: rate and invoice analytics; consultation on rate optimization and carrier negotiation. Both charged to clients.

Does not do: direct contract negotiation · rate legitimization · dispute execution · payment processing between entities · adding margin to any rate.

---

2. Project scope

Two surfaces: the HappyShip website, and the HappyShip application (SaaS). The product definition will keep evolving; the website carries the public statement as it stands, and is not where the plan is published.

---

3. Product description

3.1 Services

For says what an entity is doing, never what it is. There is no stored role. This table is the full set of functions, not the built set.

3.2 Service legs

Rates are organized by leg. Each leg has its own rate table shape and its own RULES-<leg>.md. Carriers vary within a leg; a new carrier is a section in that leg's rules, never a new file.

Near term is legs 1 and 2 only. Legs 3–5 have no phase and no RULES- file until one is assigned.

3.3 Phases

A phase is a decision, not a document. It is defined by the product owner, one at a time, and is not always tied to a leg. The next phase is written here when it is chosen; its work is TRACKER.md rows carrying the phase, and the two must agree.

Phase 1a:

1. All foundational builds
2. Last mile — Compare rates (rate-for-rate), Manage rates
3. Carrier and carrier services — FedEx Ground & Home Delivery

Phase 1b: shipment-cost comparison — the shipment profile template, the zip-to-zone list, and the shipment upload and outputs.

Out of scope — Audit invoices, Track shipments. Design is not started. [OPEN] T-075

---

4. Language

Source language is American English on both surfaces. Simplified Chinese is the first target language; Spanish and Vietnamese are candidates — [OPEN] T-076. DICTIONARY.md holds the EN–CN pairs for key terms, and is two-way: pairs are pulled from what is built, and pairs added by hand — usually where one side is missing — are pushed back to the application. Key terms end consistent across both surfaces; filler words are not governed. [UNBUILT] T-077

---

5. Documents

Shared by both surfaces.

The website.

The application. Durable files describe the whole application, every phase and leg, and are not rewritten when a phase advances.

Subject files are working files. One per module, spec-heavy before the build. Its rules move to the durable file that owns them; its tests are in the suite; its open items are TRACKER.md rows. When the module is built and tested and its rows are done, the file is committed and the module is closed. A new issue reopens it as a draft in chat.

The header states the default: everything is [UNBUILT] unless marked. Each section heading names its row (## 2.3 Contract — T-0##); a paragraph carries a marker only where it differs from its section.

Retired, kept as record. BACKLOG.md and DECISIONS.md are no longer written. Their BL-### and DEC-### IDs stay valid where cited.

---

6. Repository

6.1 Where it lives

Subject files are live files. TRACKER.md and DATA.md are not: they are governance docs like any other — master in the repo, direct to main, in the sync audit, rendered in the handbook. A chat reads them from the handbook.

1. Drafted in chat, for discussion.
2. When ready for Code, the chat writes the prompt and asks for the file to be saved to HStemp.
3. Code reads it there, builds, and reports the outcome and the URL to test. Code never edits a file in HStemp.
4. The test result comes back to chat; rebuilds and confirmations return to step 1.
5. The file is committed when its module closes — every rule moved out, every build tested, every open item a row — and reopened in chat when a new issue hits. Until then it is declared here, present in HStemp, absent from main, and outside the sync audit.

6.2 Where a commit goes

brand/tokens.css is a publicly-served governance file (CLAUDE.md Part B). The app/ row holds only while app/ has no deploy from main; it is rewritten before the first commit under any new arrangement.

---

7. The handbook

Public and ungated at handbook.happyship.us. A view, never a source.

What this holds. Every not-done thing, every finding, and every settled reason, in one list. A row is raised here and walks its statuses on the same row; nothing not done lives anywhere else. The master is this file in the repository, committed in every run that changes it. It is rendered in the handbook.

---

1. Build tally

2. Rows

Audience: Claude Code, when a task touches the public website.

Scope of this file. The public site at happyship.us, end to end: what it is for, what it may and may not contain, and how it is built and published. A task touching the website reads this file and needs no other, with two exceptions below.

Read SCOPE.md first; where the two conflict, SCOPE.md governs. Two things stay there because neither is the website's alone: deploy discipline for web/ and brand/ — every change under either takes a branch and a PR — and the product the site markets.

The website has no further documents of its own. The shared ones — visual, dictionary, backlog, conventions — are listed in SCOPE.md under Which document to open, and are deliberately not repeated here.

Not the application. That is APPLICATION.md, and nothing here reaches it.

---

1. Purpose

A public landing page introducing HappyShip: what it is, who it is for, and how to make contact. It is marketing for the product of SCOPE.md, not part of that product.

Published in two languages, English and Simplified Chinese, which are the same page in translation rather than different content.

The site performs no authentication, carries no application functionality, and holds no client data. The "Sign in" link of §2 is a signpost toward the application, not a login.

The website is not where the plan is published. It carries the public-facing statement as it stands at any moment. SCOPE.md carries both the internal and the external view, and both the short-term and the long-term design. The two are not expected to match.

1.1 Sharing a repo is not sharing a surface

The site links to the application and describes it; it does not share code with it. Nothing under web/site/ may import from, or depend on the contents of, app/.

That is a prohibition rather than an impossibility. A build step exists (§5) and could be pointed at app/ as easily as at brand/. It is not, and must not be — build.sh copies from brand/ and from nowhere else.

What the two surfaces do share is the brand, deliberately and in one direction: both read brand/, and neither reads the other. One repository, two deployments, two boundaries.

---

2. In scope

1. The landing page, in two language versions: English at / and Simplified Chinese at /zh/, sharing one stylesheet and one set of assets
2. Contact route — a published address, no form handling in v1
3. A "Sign in" link in the site navigation. It goes to the application, but has no destination for now — the application has no deploy
4. Cloudflare Pages deployment from main, running ./build.sh and serving web/site/
5. Apex and www DNS, www redirecting to apex

Content is [OPEN]. The client-facing wording of the retention rule (APPLICATION.md, tracked as BL-005) constrains it.

---

3. Out of scope

Anything not in §2 may not be in scope for the website. Do not build it, stub it, or scaffold for it. Stop and ask — and only start work on it after it has been added to this document.

Specifically not in v1: forms that submit anywhere, analytics, blog, pricing pages, any link into the application other than the "Sign in" link of §2.

This boundary is the website's alone. Work admitted to the application at APPLICATION.md is not admitted here, and the reverse.

---

4. What the site is

A static site, hand-authored. No generator, no framework, no package.json, no dependency install. No server and no database.

The rule is not "no automation" — it is that nothing has to be installed before the site can be seen. A cp clears that bar. A build system does not: it brings a dependency tree, a lockfile, a toolchain version, and a site nobody can render without installing something first.

---

5. The build step

There is one, and it is a file copy. build.sh at the repo root copies brand/assets/ and any brand/*.css into web/site/brand/. It transforms nothing: no file's contents are read, rewritten, minified, bundled or compiled, and the bytes that land under web/site/brand/ are the bytes in brand/. Plain POSIX shell, no dependencies, safe to run repeatedly.

build.sh exits non-zero when:

• the repo root looks wrong;
• brand/ or brand/assets/ is missing;
• brand/tokens.css is missing from the source, or has not reached web/site/brand/ after the copy;
• any brand/*.css fails to copy;
• the number of files copied does not match the number found, counted separately for the assets and for the stylesheets.

A broken copy therefore fails the deploy rather than publishing a partial one.

5.1 The tokens.css guard

brand/tokens.css is checked by name on both sides — in brand/ before the copy, in web/site/brand/ after it — never by asking whether the *.css glob matched anything.

web/site/styles.css carries no hex value at all: every color, space, radius, weight and font stack resolves against tokens.css. A tokens.css that does not arrive therefore does not degrade the site, it unstyles it — and a copy step that reported success while doing that would be the worst form of the failure.

A glob test starts passing the moment any other stylesheet exists, which is a guarantee about the wrong file. A count proves how many stylesheets arrived and never which.

The same reasoning is carried as a comment block in build.sh, beside the check. It is written twice on purpose: here for whoever is deciding what the build does, and there for whoever is about to delete a line that looks redundant.

5.2 Why a copy rather than duplication

This project publishes only web/site/, so a file above it has no URL on the website and the site cannot reference it. That is a fact about this project rather than about the repo: a second Pages project publishes handbook.html from the repo root (SCOPE.md), so a file above web/site/ can have a URL — just never one the website serves. The application has no such constraint either — it builds, and can read anything in the repo.

That left three ways to share the brand: duplicate the assets in git, move the published root up and expose the governance docs along with it, or copy. Duplication is two masters for one thing, which is a whole class of drift — the class that ends in a logo, or a token value, differing between the site and the app with nothing to say which is right. One shell command removes that class.

The copy now carries the entire visual system rather than a folder of images, which does not change the reasoning above but does change how much rides on the copy succeeding. That is why it is verified file by file rather than trusted to have run.

---

6. What the build carries

brand/assets/ and brand/*.css reach the live site, at /brand/….

Nothing else above web/site/ does. app/, brand/STYLE.md and the governance docs at the repo root are not copied and have no URL on this site — handbook.html has one from a project of its own, which this build neither produces nor knows about. That holds for anything added at those paths later, without a rule per file — and it does not hold for anything added to brand/assets/ or a new brand/*.css, which the build step picks up and publishes by design.

The copy is mechanical and runs at deploy with nobody reviewing it, which is what makes the branch-and-PR rule on brand/ load-bearing rather than cautious.

web/site/brand/ is generated output, not a source. It is gitignored, never edited by hand, and never committed. brand/ is its only master: an edit made to the copy is overwritten by the next build without warning, and a copy committed to git is the second master this arrangement exists to remove.

---

7. The published tree

web/site/ holds index.html, styles.css, robots.txt, site.webmanifest, assets/, zh/, and the generated brand/.

A root-relative path resolves against the output directory, not against the repo root. Pages publishes web/site/ as the URL root, so the web/ prefix never appears in a URL: /styles.css is web/site/styles.css on disk, and the same path works from /zh/ without a second copy of the file. How deep the output directory sits in the repo is invisible to the URL space.

---

8. Pages

Adding a page is adding a file. The build step copies assets; it does not generate pages, so no page passes through it and nothing has to be rebuilt to add one. Pages serves the file tree under web/site/ directly, so a subdirectory does not change that either.

The Chinese page is that property in use: one more HTML file, sharing the one served stylesheet and the one copy of assets/.

styles.css is never forked per language. Language-specific rules are scoped within it by :lang(). Two copies of the same rules drift. brand/tokens.css is not that fork — it holds values where styles.css holds rules, which is a split by kind rather than a second copy of anything.

There is no custom not-found page, and that is a decision rather than a gap. Pages resolves a single top-level /404.html and does no per-directory lookup, so a per-language copy is reachable only by typing its own URL. Pages serves its own default instead. Restoring a custom 404 is an amendment to §2 first, not a file someone puts back because they noticed it missing.