Specimen report — a worked example of a SHPBL integration report for a synthetic repository named orbital-freight-api.
In 60 seconds
This is a specimen, not a delivered audit: the host is synthetic. It shows the shape a real run produces. Against orbital-freight-api, the library's strongest claim is combinatorial — three components that exist in neither the catalog nor the repository until named parts are combined.
Makes a disputed shipment replayable exactly as accepted, instead of reconstructed from rotated logs.
seal-chain-writer + idempotent-command-gate → src/dispatch/accept.ts
Each claim above is carried, with its basis, in the numbered steps below. Nothing may appear here that is not derived from a row in Step 4, Step 5A or Step 5B. Licence gate: specimen run, no purchase record consulted; every figure below is illustrative.
Survey — formed blind
A TypeScript freight-dispatch API: HTTP surface, carrier adapters behind a registry, Postgres for shipments, a worker for delivery events. Written before any catalog row was consulted.
| Files inventoried | 412 |
|---|---|
| Archive entries (directories included, never counted as files) | 3 |
| Bytes | 1.8 MB |
| Languages | TypeScript (94%), SQL (4%), Shell (2%) |
| Spine | src/dispatch/, src/carriers/, src/events/worker.ts |
| Risk signals | Duplicate dispatch on client retry; carrier rate limits discovered at failure time; delivery disputes argued from rotated logs. |
Blind order: this account was written before any catalogue or vault row was read. Binary fixtures and the vendored carrier SDKs were not read; nothing in this report rests on them.
Own library — checked before SHPBL
Specimen: no prior harvest exists for this host, so no own-library reuse is claimed.
| Own library present | None — no .shpbl/ directory in this repository. |
|---|---|
| Rows reused before SHPBL adoption | None. |
| Rows that did not answer this host | Not applicable in a first run. |
Do not touch
No hands-off path was modified, and none needed to be for the work proposed here.
| Protected paths observed | .env, .github/workflows/, infra/terraform/ |
|---|---|
| Reason | Secrets, CI authority and infrastructure state are never agent-writable. |
| Any modification attempted | 0 |
Step 0
Run before any file is copied. A STOP here ends the evaluation; it is not a defect to work around. The gate runs before any component is proposed. In a specimen it is shown, not decided.
| Host licence (SPDX) | Apache-2.0 |
|---|---|
| Where it was found | LICENSE |
| Purchase or grant record | None — specimen run. |
| Licence | Evaluation only |
| Verdict | Evaluation is permitted; integration of any component named here requires a library licence. |
| Clause that drove it | Components remain under the SHPBL library licence; the host's Apache-2.0 terms govern the host's own files only. |
| Scope limits imposed | No component may be redistributed as part of this repository without a licence that permits it. |
Sub-package exceptions — workspaces published under a different licence than the repo root, e.g. an npm-published package that must stay permissive: Vendored carrier SDKs carry their own terms and were not touched.
Verdict
A worked example, shipped so the template can be read as a finished report.
Were orbital-freight-api a real host, the recommendation would be to build the Sealed Dispatch Ledger first: it removes the dispute-reconstruction problem outright and the two later composites attach to the same acceptance path.
Step 5A — the section that sells
Each entry below is a component that does not exist in the catalog and does not exist in this repository. It comes into being only when the named ingredients are combined — library parts with each other, or library parts with this host's own modules. Three composites, highest value first.
A dispatch path that writes every accepted shipment as a hash-chained entry, so a disputed delivery can be replayed exactly as it was accepted rather than reconstructed from logs.
| Composition | catalog seal-chain-writer + catalog idempotent-command-gate + host src/dispatch/accept.ts |
|---|---|
| Problem it removes | Disputed shipments are currently argued from application logs, which are rotated at 14 days and carry no ordering guarantee. |
| Runtime behaviour | Accept writes the command, its inputs and the prior entry hash before the carrier call; a retry with the same key returns the first sealed entry instead of dispatching twice. |
| New because | The catalog seals arbitrary records and the host accepts dispatches; neither one, alone, produces a replayable dispatch history. |
| Attachment point | src/dispatch/accept.ts |
| Leaves untouched | carrier adapters, pricing, the public REST contract |
| Effort | 3–4 days |
| Verified (weakest ingredient, verbatim) | Designed and reasoned from read files. Ingredient behaviour executed and observed in the catalog's own suite; the combination was not run against this host. |
POST /dispatch | v [idempotent-command-gate] --replay--> prior sealed entry | first time v [seal-chain-writer] --> entry(n) = H(entry(n-1) + command) | v carrier adapter (unchanged)
A standing comparison between what each carrier promised at quote time and what it actually did, surfaced as a per-carrier drift figure rather than a support ticket.
| Composition | catalog claim-versus-observed-differ + catalog rolling-window-scorer + host src/carriers/*/quote.ts |
|---|---|
| Problem it removes | Late deliveries are handled per shipment; nothing in the system accumulates them into a carrier-level fact anyone can act on at renewal. |
| Runtime behaviour | Each quote is retained with its promise; each terminal delivery event is differenced against it and folded into a 30-day rolling score per carrier and lane. |
| New because | The differ compares two structures and the scorer keeps a window; the carrier promise ledger they need did not exist until the host's quote path was included as an ingredient. |
| Attachment point | src/carriers/registry.ts |
| Leaves untouched | the quote API shape, customer-facing tracking pages |
| Effort | 4–5 days |
| Verified (weakest ingredient, verbatim) | Designed and reasoned from read files. No delivery-event stream was executed in this run. |
quote(promise) ─┐
├─> [claim-versus-observed-differ] ─> delta
delivery(event)─┘ |
v
[rolling-window-scorer]
|
carrier / lane drift %
A router that spends each carrier's remaining API quota deliberately, degrading to the next carrier before a hard 429 rather than after it.
| Composition | catalog budgeted-rate-governor + catalog fallback-ladder + host src/carriers/http.ts |
|---|---|
| Problem it removes | Carrier rate limits are discovered by hitting them; a burst of bookings turns into failed dispatches during exactly the hours that matter. |
| Runtime behaviour | Every carrier call draws from a per-window budget; at the configured threshold the ladder routes new work to the next eligible carrier and records why. |
| New because | The governor meters one dependency and the ladder reorders candidates; routing by remaining quota required the host's carrier client to be part of the component. |
| Attachment point | src/carriers/http.ts |
| Leaves untouched | authentication, retries inside carrier SDKs |
| Effort | 2–3 days |
| Verified (weakest ingredient, verbatim) | Designed and reasoned from read files. Governor behaviour executed and observed in the catalog's own suite. |
dispatch ─> [budgeted-rate-governor] ── under budget ──> carrier A
|
at threshold
v
[fallback-ladder] ─> carrier B ─> carrier C
|
reason recorded
| Composite | Ingredients | New behaviour | Effort |
|---|---|---|---|
| Sealed Dispatch Ledger | seal-chain-writer + idempotent-command-gate + src/dispatch/accept.ts | Replayable, duplicate-proof dispatch acceptance | 3–4 days |
| Carrier Drift Watch | claim-versus-observed-differ + rolling-window-scorer + host quote path | Per-carrier promise-versus-reality drift | 4–5 days |
| Quota-Aware Backpressure Router | budgeted-rate-governor + fallback-ladder + host carrier client | Quota-led carrier failover before hard limits | 2–3 days |
Build this composite first: Yes — the roadmap's first phase depends on it
A composite inherits the weakest verification claim of its ingredients and never a stronger one. Where an ingredient reads “Not claimed”, the composite reads “Not claimed”.
Step 5B — new single-component designs
Single-purpose components designed for this repository, built from named catalog components plus named host files. Read them after the composites in Step 5A, which are the higher-value half of this step. One new single-source component, designed for this host.
A read-side that reconstructs any shipment's accepted state from the sealed chain, for support and for dispute response.
| Built from | catalog seal-chain-writer |
|---|---|
| Plus host | src/dispatch/accept.ts |
| New because | The catalog writes chains; it does not read them back as domain state. |
| Unlocks | Support answers a dispute from the record instead of from inference. |
| Evidence path | src/dispatch/accept.ts:88 |
| Effort | 2 days |
| Constraints | Must not read the carrier tables; the chain is the only source. |
| Confidence | Designed and reasoned from read files. |
sealed chain ─> [replay reader] ─> accepted state at time T
Build this one first: After the Sealed Dispatch Ledger
Scoreboard
Every figure below carries the basis it was derived from. A number without a basis is a defect in this report.
| Measure | Value | Basis |
|---|---|---|
| Host files read | 412 | Counted during the blind survey |
Step 1
The host modules that participate as ingredients.
| Host unit | Path | Exported surface | LOC | Job it does |
|---|---|---|---|---|
| dispatch acceptance | src/dispatch/accept.ts | POST /dispatch | 214 | Validates and accepts a shipment, then calls a carrier |
Step 2
Every candidate carried forward from the catalog, scored on the five axes before ranking. Rows that fail an axis stay in the table with the reason — a silently dropped candidate is a defect. Nine candidate rows were screened on five axes; six were carried.
| Candidate (ID) | Direct fit | Combinatorial | Value | Cost / risk | Novelty | Carried forward? |
|---|---|---|---|---|---|---|
| cat-0184 | High — attaches to the acceptance path | High — ingredient in two composites | High — removes dispute reconstruction | Low — 3–4 days | New to this host | Carried |
Candidates screened: 9 · carried forward:
6 · rejected: 2. Rows flagged
⚠shared-entry in the catalog were not scored from their
catalog columns; how they were handled: 1
Step 3
What the host's runtime, build, licence and release shape forbid, independent of whether a component is attractive. Constraints read from the repository, not assumed.
| Constraint | Source of truth | What it rules out |
|---|---|---|
| Node 20, ESM only | package.json:engines |
Any component requiring CommonJS-only dependencies |
Every recommended component's Verified column, quoted
verbatim with Not claimed left in those words:
Verification axes are quoted verbatim from AGENT-HANDOFF-CATALOG.md.
Governed runtime: Not present in this host; not proposed in this specimen. — any
component whose runtimeRequirements.requiresGovernedRuntime is
true must ship with its listed slices or not at all.
Adapter ports that must be implemented before first call: carrier registry (src/carriers/registry.ts), event worker (src/events/worker.ts)
Step 4
Ranked by expected value to this product — not by catalog prestige. Ranked by value removed per day of effort.
| # | Item | Catalog IDs | Host paths | Effort | Value | Confidence |
|---|---|---|---|---|---|---|
| 1 | Sealed Dispatch Ledger | cat-0184, cat-0391 | src/dispatch/accept.ts |
3–4 days | 412 | Designed and reasoned from read files. |
A retried POST /dispatch with the same client key dispatches twice; nothing dedupes at acceptance.
| Gap | Evidence in host | What addresses it |
|---|---|---|
| No idempotency at the acceptance boundary | src/dispatch/accept.ts:88 — no key lookup before the carrier call | Sealed Dispatch Ledger |
Low effort, high confidence, nothing on a critical path.
Add the idempotency key column before the ledger lands; it is an hour of work.Items that would duplicate, undermine or dilute systems already trusted here. A report with no entries here evaluated nothing.
Carrier SDKs, CI workflows, Terraform state.Step 6
Three buckets, never merged. (A) is hard, (B) is counterfactual, (C) is conditional. Illustrative arithmetic, shown so the shape of the section is clear.
| Bucket | Engineer-weeks | US$ (range) | Basis and assumptions |
|---|---|---|---|
| (A) Cost avoided — work already planned | 2.0 | $16,000 | Ledger + replay reader at one engineer, blended rate |
| (B) Capability acquisition — would never have been built | 1.0 | $8,000 | Drift watch |
| (C) Portfolio and future reuse — conditional | 0.6 | $4,800 | Backpressure router |
| − Integration cost (ports, wiring, security review, learning) | 0.8 | $6,400 | Integration, review and tests |
| = Net against the applicable tier | 2.8 | $22,400 | Sum of the three composites less integration cost |
One engineer, $200k fully loaded, no parallelism.
Written in-house, the same three composites are roughly six weeks.
Buy the combinatorial parts; write the host-specific glue.
What would change this answer: If the delivery-event stream turns out to be lossy, the drift watch drops to a diagnostic and its figure comes out of the total.
Step 7
| Phase | What ships | Why here | Gate to proceed | Effort | Cumulative |
|---|---|---|---|---|---|
| 0–30 days | Sealed Dispatch Ledger + Dispatch Replay Reader | Removes duplicate dispatch and dispute reconstruction together | Replay of 100 historical dispatches matches the shipment table | 5–6 days | 5–6 days |
| 30–60 days | Carrier Drift Watch | Turns per-shipment lateness into a renewal-time fact | Drift figure reproduces for one carrier over a known month | 4–5 days | 9–11 days |
| 60–90 days | Quota-Aware Backpressure Router | Stops discovering rate limits by hitting them | A synthetic burst degrades to carrier B with no 429 recorded | 2–3 days | 11–14 days |
Phase 2 and 3 both attach to the acceptance path that Phase 1 seals.
Do not start Phase 3 before the quota figures are read from carrier headers.
src/dispatch/replay.ts (new file)
Seal the dispatch path.
Capacity assumption: One engineer, three weeks.
Discovery Vault — provisional, kept out of every total
Screened from DISCOVERY-VAULT-INDEX.md rows only. Pre-purchase
the vault source does not ship, so no API surface, LOC figure or verification
verdict is stated here and nothing in this section is carried into any
savings, effort or net total above.
| Discovery id | Capability (index row) | Host concern it may touch | Status | What to read first post-purchase |
|---|---|---|---|---|
| vdisc-specimen | Lane-level promise ledger | No component in the catalog holds a per-lane promise history | PROVISIONAL — index row only, source not read (pre-purchase) | Recorded as a gap; nothing was invented to fill it in this report. |
The gap ledger is demand-pull: a concern is recorded when a run needs it, not manufactured in advance. If this section is empty, say in one line why the vault produced no candidates rather than deleting the section.
Step 8 — appended, never merged into the body
| Claim above | Re-check result | Estimate change |
|---|---|---|
| Sealed Dispatch Ledger removes dispute reconstruction | Held — acceptance path re-read, no existing seal found | None |
Appended after the body was written; the body was not edited to match.
Claim ceiling
Extracted from systems the author has run in production since August 2025. Operationally exercised, not independently security-audited.
In pre-purchase evaluation, verification axes quoted in this report come
verbatim from the generated AGENT-HANDOFF-CATALOG.md, which is
the pre-purchase source of truth; in a full delivery,
artifacts/<ID>/artifact-manifest.json is authoritative and
overrides it. Every component
records testCoverage: Not claimed, and no component has had an
independent third-party security review. Static scan results and adversarial
test suites are the author's own.
Verification axes cited in this report: Executed and observed; Designed and reasoned from read files.
| Claim state | What it means | Where used in this report |
|---|---|---|
| Executed and observed | A test suite or command was run in this run and its result was read. | Ingredient behaviour in the catalog's own suite. |
| Designed, not executed | The work is written out and reviewable, but nothing was run against it here. | All three composites and the single-source design. |
| Not assessable from the material supplied | The material in scope does not answer the question either way. | Delivery-event completeness; no stream was read. |
These three states are the only vocabulary this report uses for verification. No synonym is permitted: “verified” and “designed” read alike in prose and mean different things.
1,117 components · 1,116 source files · measured per artifact in artifact-manifest.json lines. Free under LicenseRef-CMPSBL-Perpetual-1.0 when this host's own source ships under the perpetual licence. Otherwise: Keep is US$499 once per company, perpetual commercial rights to every release published during a one-year update term, 30-day full refund. Borrow is US$39 per month for practitioner access while the subscription runs. Offline delivery, no account, no telemetry.