Portability inventory¶
Generated from a canonical source
This page is a read-only projection of docs/strategy/portability-inventory.md.
Edit the canonical file, then run npm --prefix tools/project-knowledge-derive run derive.
Companion to: delivery-fork.md Last updated: 2026-05-22
Every artifact in the current bc-subscriptions program is tagged with how it travels across the two delivery paths. The tags are:
- 🟢 survives-both — zero or minimal rework regardless of fork; safe to keep investing in now.
- 🟡 bolt-on-only — meaningful only on Path A; would be replaced by a different mechanism on Path B (often without losing the behavior the artifact encodes).
- 🟣 first-class-only — does not exist today; would need to be created on Path B.
- 🔴 requires-rework — exists today and travels, but the implementation must be rebuilt on Path B even though the design intent persists.
ADRs (64 ratified as of 2026-05-22)¶
| ADR | Topic | Tag | Notes |
|---|---|---|---|
| 0001 | Hive workflow and layered methodology | 🟢 | Process, not mechanism |
| 0002 | Traceability schema | 🟢 | Documentation discipline |
| 0003 | Phase-1 schema + spec consolidation | 🟡 | Specific to our D1 + spec layout |
| 0004 | Access-token storage in stores.metadata | 🟡 | Path B uses internal request context, not OAuth tokens |
| 0005 | Three-surface UI architecture | 🟢 | Surface taxonomy survives; implementations vary per fork |
| 0006 | i18n strategy (react-intl + ICU) | 🟢 | Library-level decision portable |
| 0007 | Merchant uninstall data lifecycle | 🟢 | Behavior portable; mechanism changes (no "uninstall" in native) |
| 0008 | Schema migration sequencing | 🟡 | D1-specific patterns |
| 0009 | Tenant data isolation (single D1 + store_hash) | 🟡 | Path B uses store DB partitioning, different pattern |
| 0010 | Webhook / event egress | 🔴 | Path B uses RabbitMQ Domain Eventing |
| 0011 | Charge idempotency + retry semantics | 🟢 | Behavior is universal; matters in BigPay too |
| 0012 | Merchant admin stack (Vite + React + BigDesign) | 🔴 | Native admin lives inside BC App; rewritten as BC-native pages |
| 0013 | Storefront-components shape | 🔴 | Native ships in storefront-kit directly |
| 0014 | Subscriber-surface auth (magic-link + JWT) | 🔴 | Native uses BC session model |
| 0015 | Observability stack | 🔴 | Path B = Lightstep + Sentry + Prometheus |
| 0016 | Tax engine — defer to BC | 🟢 | Already the right answer in both paths |
| 0017 | Transactional email (Postmark) | 🟢 | Mechanism portable; native may swap provider |
| 0018 | Admin deploy surface (Cloudflare Pages) | 🟡 | Bolt-on-specific |
| 0019 | Hive substrate evolution | 🟢 | Process, not mechanism |
| 0020 | Surface DRI ownership | 🟢 | Organizational pattern |
| 0021 | Epic gating map | 🟢 | Roadmap structure |
| 0022 | Marketplace Merchant-of-Record scope | 🟡 | "Marketplace" framing assumes Path A |
| 0023 | B2B Edition checkout-ownership | 🟢 | Architectural pattern, fork-agnostic |
| 0024 | DeliveryInstance as first-class entity | 🟢 | Domain entity; portable |
| 0025 | Charge sequencing per processor | 🟢 | Behavior portable to BigPay adapters |
| 0026 | Retire /api/checkout/intent | 🟡 | Specific to our API |
| 0027 | Outbox marker + catch-up cron | 🔴 | Eventing mechanism changes on Path B |
| 0028 | Eligibility-engine chokepoint pattern | 🟢 | Domain pattern; portable |
| 0029 | Marketplace-first, native-ready | 🟢 | Encodes the fork posture itself |
| 0030 | BigEng pattern alignment | 🟢 | Explicitly bridges to native standards |
| 0031 | Ops-ledger enhancements | 🟢 | Operational concern, portable |
| 0032 | API versioning + deprecation handler | 🟡 | "Our public API" framing |
| 0034 | Subscriber SDK architecture | 🔴 | Native ships SDK from BC org |
| 0035 | BC Payments MIT endpoint | 🟢 | Becomes more central in Path B (via BigPay) |
| 0037 | Stored instruments as canonical charge rail | 🔴 | Entire vault façade vestigial in Path B |
| 0038 | Capture timing | 🟢 | Behavioral rule; BigPay must respect this too |
| 0044 | Big-blueprint retrofit | 🟢 | Methodology |
| 0045 | Spec-comprehensiveness methodology | 🟢 | Process |
| 0046 | v0.2 processor auto-detection | 🟡 | Specific to our processor adapter layer |
| 0047 | Multi-tenant plan-scoping extension | 🟢 | Domain pattern |
| 0048 | Eligibility-engine chokepoint extension | 🟢 | Domain pattern |
| 0049 | Order bundling architecture | 🟢 | Domain pattern |
| 0050 | CS tool impersonation session model | 🟢 | Behavior portable |
| 0051 | Extension type registry | 🟡 | Specific to our extension shape |
| 0052 | Cycle-scoped discount lock | 🟢 | Domain rule |
| 0053 | Subscription promotion substrate | 🟢 | Domain pattern |
| 0054 | Cloud SQL engine | 🟡 | Path A Phase 2 specific |
| 0055 | Hive proposal lifecycle derived from GH | 🟢 | Process automation |
| 0056 | Structured proposal metadata | 🟢 | Process |
| 0057 | Epic DoD upstream to big-blueprint | 🟢 | Methodology |
| 0058 | Brand identity sign-off | 🟢 | Design |
| 0059 | Per-merchant Storefront API token | 🟡 | "Per-merchant" implies marketplace install |
| 0060 | PCI scope SAQ-A boundary | 🟢 | Compliance posture; matters in both paths |
| 0061 | STRIDE payment flow threat model | 🟢 | Threat model portable |
| 0062 | GDPR data subject rights | 🟢 | Compliance; portable |
| 0063 | Email pipeline event pattern | 🔴 | Eventing mechanism changes |
ADR roll-up: - 🟢 survives-both: 35 (55%) - 🟡 bolt-on-only: 14 (22%) - 🔴 requires-rework: 9 (14%) - 🟣 first-class-only: 0 (would emerge during Path B design)
More than half of ADRs are fork-agnostic. The "bolt-on-only" cluster is almost entirely substrate-mechanic decisions (D1, OAuth client, Cloudflare deploy, our API surface). The "requires-rework" cluster is eventing, observability, payments vault, admin/storefront surfaces — exactly the dimensions where BigEng standards mandate specific mechanisms.
PRD / BRD content¶
| Section | Tag | Notes |
|---|---|---|
| Personas (5 actors) | 🟢 | Identity invariant across paths |
| BRD user stories + AC | 🟢 | Behavioral; survives both |
| PRD product surface area | 🟢 | What it does, not how |
| PRD-COMPANION worked examples | 🟢 | Behavioral |
| APP-ADMIN-SPEC (operator surface) | 🟢 | Behavioral; mechanism changes |
| ARCHITECTURE.md current stack | 🟡 | Documents the bolt-on shape; needs companion native-arch doc on Path B |
| BRD open questions | 🟢 | Same questions in both paths |
| Glossary | 🟢 | Domain language |
Prototype behaviors¶
| Behavior | Tag | Notes |
|---|---|---|
| Subscription PDP widget interactions | 🟢 | Design oracle for native storefront-kit work |
| Cart/checkout subscription affordances | 🟢 | UX behavior portable |
| Account portal flows (manage / pause / skip / cancel) | 🟢 | Shopper UX portable |
| Admin dashboard (plans, instances, dunning) | 🟢 | Operator UX portable |
| Email previews + templates | 🟢 | Template content portable |
| Demos storyboard | 🟢 | Pedagogical asset |
| Connect-your-store flow | 🟡 | Path A only — Path B has no "connect" step |
| Marketplace install onboarding | 🟡 | Path A only |
Hive substrate¶
| Asset | Tag | Notes |
|---|---|---|
| Proposal / synthesis / decision workflow | 🟢 | Process is portable |
hive-meta metadata block |
🟢 | Process |
| Substrate-derived-from-GH (ADR-0055) | 🟢 | Process automation |
| Open proposals (~60+ active) | 🟢 | Each gets reclassified per fork; many survive |
| ADR-Spec pairing rule | 🟢 | Methodology |
| Ratified ADRs catalog | 🟢 | As tagged above |
Tooling¶
| Tool | Tag | Notes |
|---|---|---|
tools/state-derive/ |
🟡 | State derivation depends on our codebase shape |
tools/hive-board-derive/ |
🟢 | Process automation |
tools/epic-progress/ |
🟢 | Process automation |
| Code-review bot v1.3 | 🟢 | Quality discipline |
| Sandbox-scenario CI workflow | 🟢 | Test discipline; rebinds to native test infra |
Aggregate read¶
Of ~120 catalogued artifacts: - ~70% survive both paths (process, behavior, domain rules, methodology) - ~20% are bolt-on-only (substrate mechanics, marketplace economics, our API surface) - ~10% require implementation rework on Path B (where BC's internal standards mandate specific mechanisms — eventing, observability, vault, admin/storefront surfaces)
Practical read: the body of work done to date is overwhelmingly fork-portable. The substrate mechanics — what the project has spent the most engineering hours on in absolute terms — are the smallest fraction by artifact count, but they represent the bulk of the rebuild cost on Path B. Conversely: if Path A is the answer, ~95%+ of investment is on-rails.
This is why the fork is genuinely hard, not obvious. The portability inventory does not collapse the decision; it scopes the rework cost honestly so the decision is made with eyes open.