Design the vendor profile and cross-retailer document vault #13
Notifications
Due Date
No due date set.
Blocks
Depends on
#20 Specify the entitlement and subscription model
christian/helmdocs-proposal-system
#23 Design the app framework — retailer and vendor surfaces
christian/helmdocs-proposal-system
#11 Define the tenancy, identity, and authorization model
christian/helmdocs-proposal-system
Reference: christian/helmdocs-proposal-system#13
Reference in New Issue
Block a user
No description provided.
Delete Branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Question
Research names this the strongest white space: a vendor selling into Walmart, Target, Kroger, and Costco maintains four relationships, four compliance packets, four portals. Nobody offers one profile to many retail buyers.
It is also the most-resented adjacent model when sold as mandatory access (ISNetworld/Avetta), so under the tools-not-access decision the vault is a convenience the vendor buys, never a gate they must pass.
Resolve: what lives in the profile (insurance certs, tax, legal, diversity status, financials, references); how documents expire and get re-verified; who attests to validity; how a retailer requests something the vault does not hold; and how this stays a benefit rather than a toll.
Parent: #1
Resolution
Four decisions. The through-line: we establish facts, retailers make judgements. Every one of
these falls on the same side of that line, and the consistency is deliberate — it is what keeps the
vault a tool the vendor buys rather than a gate they must pass, and what keeps us out of
liabilities we have no business carrying.
1. The vendor attests; we validate structure; retailers accept
The vendor asserts the document is what they say it is. We validate only machine-checkable
facts — expiry date, coverage limits, named insured, issuing carrier, document integrity — and
never assert the underlying claim is true. Each retailer accepts or rejects for their own
purposes, and those acceptances accumulate.
Verification is therefore a graph of retailer acceptances, not a platform assertion.
Why not the ISNetworld model. Certifying documents ourselves is a services business with human
reviewers, not software. It carries liability we cannot price: if we assert a policy is valid, a
retailer relies on that, and a loss follows, we are exposed with no underwriting function. It is
also precisely the model the research found 38% of subcontractors call an enrollment barrier.
What it costs. Weaker than ISNetworld's pitch — the first retailer still does real review work.
The reuse benefit compounds only as acceptances accumulate.
2. Cross-retailer signals are anonymous by default
The reuse benefit and the confidentiality promise are in direct tension: a signal that Target
accepted Acme is a commercial relationship crossing the two-party boundary the product is sold
on.
Resolution: a retailer sees only an unattributed count — "this certificate has been accepted by
3 retailers on the network" — never which. The vendor may opt in to name specific retailers,
because "we supply Walmart" is a credential many vendors actively want to spend.
Disclosure is the vendor's asset to trade, not ours to give away.
Hard requirement, not a nicety. At small network size an unattributed count deanonymises
trivially — "accepted by 1 other retailer" is guessable when there are three retailers on the
platform. The aggregate needs a floor below which no count is shown at all. Data release must
treat the aggregate as its own disclosure class, distinct from both document contents and identity.
3. We curate a deliberately small catalogue
The vault holds typed documents — certificate of insurance, W-9, food-safety certification,
diversity certification, financial statements, references — because structural validation, expiry
parsing, and eligibility rules all key off type. An untyped bag supports none of them.
We own the catalogue. Each type carries a validator and an expiry rule. A retailer needing
something outside it attaches an ad-hoc request to that RFP: the vendor uploads it there, it
never enters the vault, and it carries no eligibility effect. A type is promoted into the
catalogue only when demand recurs across multiple retailers.
Why curation rather than self-service. The catalogue's entire value is that it is small and
shared. A type only one retailer uses delivers zero reuse while still costing a validator, an
expiry rule, and a migration. Self-service converges on six near-duplicate "Certificate of
Insurance" types and fragments the vendor's profile into per-retailer silos — the exact problem the
vault exists to solve.
What it costs. We are a bottleneck, and a retailer with an unusual but genuine requirement waits
on us. The ad-hoc path is the pressure valve that keeps that from blocking a sourcing event.
4. We compute expiry state; retailers configure its consequence
We derive an objective per-document state —
current / expiring-soon / expired— and recomputeeligibility from it. What that state causes is retailer policy, configured per category: block
award, warn the evaluator, or ignore.
Behaviour:
clock.
exposure actually sits.
Why configurable. Retailers genuinely differ — some cannot lawfully award against an expired
certificate, others do not care. A single global rule would have us making a legal judgement on
their behalf across regulatory contexts we do not know.
Structural consequence for the code layout. Eligibility is a derived value that must be
recomputed on a clock, not only on write. Nothing else on the map has needed a scheduler; this
does, and the layout must have a place for it.
Constraints handed to other tickets
k-anonymity floor — neither document contents nor identity.
reconstructable.
under tools-not-access it must remain a convenience the vendor buys — never a gate they must pass
to bid.
each carries — graduated to its own ticket.
Two notes from a skeptical review pass
1. Eligibility for a vendor with no vault is undefined. This ticket makes eligibility accrue
from retailer acceptances of typed vault documents, and makes expiry state feed audience rule
evaluation. The entitlement decision then gave free vendors no vault — they upload per RFP
instead. Nothing says what that upload is.
Read one way it is an ad-hoc attachment, which decision 3 says carries no eligibility effect —
so a free vendor can never become qualified and is systematically absent from every rule-defined
group. That is access-gating by the back door, and it is entitlement gating retailer-facing
correctness, which the entitlement decision explicitly forbids. Read the other way it is typed and
eligibility-bearing, and then expiry has to track documents living outside the vault.
Graduated to Define the eligibility path for a vendor with no vault.
2. Decision 4 predates the category taxonomy decision. "Retailers configure the expiry
consequence per category" must mean the retailer-local category, not the spine leaf —
consistent with eligibility, which runs on the local category.