01 · Purpose and capabilities
What this system is for.
Product Resolver exists so a comparison can say “same exact product,” “different product,” or “not yet known,” and can show why. This chapter stays above the schemas.
The problem
Merchant pages describe offers. They do not describe a stable product identity. Titles drift. A URL is one seller’s page. A pack of two is not the same item as a larger single unit. A model can notice a heatsink and still be wrong. Stock that was true at dawn is a different fact by afternoon.
The people who need the answer are buyers of the comparison, operators who correct a bad match, and engineers who have to explain a change months later. The design keeps those jobs apart.
Business outcomes the design aims at
- Keep the original bytes and the time they were seen, so a later correction can be checked.
- Separate the exact product from each merchant’s offer, including packs and variants.
- Let a person decide when the evidence is not deterministic, and keep that decision.
- Show the public only an authorized release that the product service has applied.
- Keep recurring service spend inside the one confirmed ceiling: USD 50 a month.
Human review time is a separate proposal. The worked example imputes 7.84 hours a month. That is effort, not cash, and it is not confirmed.
Figure
Who is outside Product Resolver, and which part of the system serves them?
Takeaway. Collectors only acquire evidence. The resolution service is the only place that accepts facts. The product service only presents an authorized, applied release.
Text equivalent
- Source sites and feeds are external. Collectors fetch them with their own egress.
- Collectors submit captures to the resolution service and stop there.
- Operators send human decisions to the resolution service.
- The resolution service emits accepted-change events to the product service.
- Public readers query the product service, never the resolver database.
Capabilities, and where they live
Each row is a capability already in the workbench design. Status words match that design. Nothing in the table is a deployed service.
| Capability | Who | Owns | Connection | Status |
|---|---|---|---|---|
| Fetch a source without letting the resolver browse it | Collector | Local cursor only | Source fetch | Established in design |
| Store bytes once and return a receipt | Intake, inside the resolver | Artifact, capture, receipt | Upload, capture | Proposed flow |
| Parse with a versioned adapter before any model | Extraction module | Claims and unmapped fields | Resolution job | Established order |
| Propose or advise without deciding | LLM extractor and reviewer, as actors | Nothing of their own | Extract, review | Proposed calls |
| Accept a fact and remember the decision | Review and identity modules | Items, mappings, outbox | Decision | Proposed transaction |
| Apply that fact for readers | Product service | Projections only | Accepted change | Established shape |
| Release it in public | Operator, then product service | Publication record | POST /v1/publications | In the OpenAPI contract |
| Refuse to guess shipping | Policy module | Versioned policies | Shipping | Proposed evaluator |
| Stay inside the monthly ceiling | Admission gate | Reservations and forecast | Budget | Ceiling confirmed. Bands proposed. |
Authoritative write-ups live in the local reference: ADR-001 through ADR-010, the decision ledger, the budget controls, and the unapproved implementation plan.
What is in scope, and what is not
In scope for the design: one tenant’s catalog, collectors that only acquire, a resolution service that accepts facts, and a product service that presents an applied release. Local development is proposed with no recurring fee. A hosted shape is proposed and not authorized.
Out of scope until Jonathan decides: a second real source, shared catalogs, which model provider to pay, which database host to pay, and whether the launch is two scrapers. This guide does not pick those.
Principal limitations
- Only USD 50 per month of recurring services is confirmed.
- Workbench screens are prototype demonstrations. They are not production.
- PostgreSQL concurrency, identity-provider cryptography, live source access, invoices, and rendered browser layout were not established.
- Pantry & Pour, including cap_pp_feed_1011, is a fictional fixture. It does not prove a source can be collected.
- The plan is unapproved. The architecture baseline remains 0.4.0.