cgalo5758
ac2760a0fe
Write the eight domain-model cards under `docs/models/`, mark M10 10i Done, and update the design docs to v16. Also records Doc 44, which ratifies Decisions 129-133 as amended, and the Doc-39 conformance check that satisfied its gate.
19 KiB
19 KiB
Document Manifest
Generated: 2026-03-06
Total documents: 52 (+ 2 live canonical in modules/)
Curation method: Three-agent review of all 86 extracted artifacts (main branch + off-branch) across 14 conversations, plus incremental curation of new conversation artifacts.
Relationship to
modules/. Themodules/directory (seemodules/README.md) decomposes the data model into six navigable modules, each with anarchitecture.mdsynthesized from the numbered documents below. Module architecture files are adapted and restructured for module-scoped navigation; the documents in this directory remain as the authoritative historical design artifacts.
Canonical Reference (repository root — not copied)
These two files are the live canonical documents. They are maintained at the repo root and are the authoritative source of truth.
| File | Description |
|---|---|
../data-model-v8.0.md |
Data Model Reference v8.0 — 48 tables, full schema, constraints, indexes |
../v8_companion.md |
Development Companion v8.0 — 84 decisions, open issues, policy index, version history |
Numbered Exploratory Documents
The numbered document series records each major design exploration. These are the primary design artifacts. Latest version only; superseded revisions are archived in artifacts/ but not curated here.
| File | Document | Source artifact | Decisions |
|---|---|---|---|
doc-01-service-accounts-actor-model.md |
Doc 1: Service Accounts & Actor Model | service-accounts-and-actor-model_20260211-0850.md |
12–15 |
doc-03-roles-permissions-design.md |
Doc 3: Roles & Permissions Design | roles-and-permissions-design_20260211-0924.md |
16–19 |
doc-05-workspace-vs-billing-resource-model.md |
Doc 5: Workspace-Centric vs. Billing-Centric Resource Models | workspace-vs-billing-centric-resource-model_20260207-0329.md |
1 |
doc-05.1-multi-billing-account-entitlement.md |
Doc 5.1: Multi-Billing-Account Entitlement Resolution | multi-billing-account-entitlement-resolution_20260208-0853.md |
1–2 |
doc-05.2-metered-usage-patronage-scope.md |
Doc 5.2: Metered Usage and Patronage Attribution Scope | metered-usage-and-patronage-scope_20260209-0653.md |
3–4 |
doc-06-subscription-purchase-product-access.md |
Doc 6: Subscription, Purchase & Product Access Semantics | document-6-subscription-purchase-product-access-semantics_20260209-2155.md |
5–10 |
doc-06.1-subscription-access-revisions.md |
Doc 6.1: Document 6 Revisions — Semantic Precision and Structural Corrections | document-6-revisions_20260210-1016.md |
5–10 |
doc-07-polymorphic-relationship-audit.md |
Doc 7: Polymorphic Relationship Audit and Pattern Decision | polymorphic-relationship-audit_20260214-1405.md |
20–24, 29 |
doc-07.1-polymorphic-audit-reconciliation.md |
Doc 7.1: Polymorphic Audit — Reconciliation of Two Independent Analyses | polymorphic-audit-reconciliation_20260214-1628.md |
24, 29 |
doc-09-soft-delete-terminal-state-exploration.md |
Doc 9: Issue 14 Exploration — Soft-Delete and Terminal State Policy | issue-14-exploration_20260215-0449.md |
31–33 |
doc-10-retention-requirements-analysis.md |
Doc 10: The Obligation to Remember — Retention Requirements Analysis | document-10-retention-analysis_20260215-2210.md |
36–38 |
doc-11-invitation-state-machine.md |
Doc 11: Issue 2 Exploration — Invitation State Machine | document-11-invitations_20260216-0322.md |
39–41 |
doc-12-temporal-modeling-strategy.md |
Doc 12: Issue 8 Exploration — Temporal Modeling Strategy | document-12-temporal-modeling_20260216-0446.md |
42–45 |
doc-13-entitlement-quota-architecture.md |
Doc 13: Entitlement & Quota Architecture | document-13-v2_20260217-0945.md |
46–51 |
doc-14-cross-org-collaboration.md |
Doc 14: Cross-Organization Resource Sharing | document-14-v2_20260217-0948.md |
52–54 |
doc-15-invoice-line-items.md |
Doc 15: Invoice Line Items | document-15_20260217-1052.md |
55–59 |
doc-16-discount-promotion-model.md |
Doc 16: Discount and Promotion Model | document-16-v2_20260218-0124.md |
61–66 |
doc-17-billing-lifecycle-pending-charges.md |
Doc 17: Pending Charges and the Billing Lifecycle Pipeline | document-17_20260218-0411.md |
67–70 |
doc-18-prepaid-credits-grants.md |
Doc 18: Prepaid Credit Balances and the Credit Grant Model | document-18_20260218-0433.md |
71–76 |
doc-19-payment-arrangements-reference.md |
Doc 19: Payment Arrangements and Billing Topology Reference | document-19_20260218-0801.md |
— (reference, no new decisions) |
doc-20-audit-log-architecture.md |
Doc 20: Audit Log Architecture Integration | Session 001 (integration analysis of reference-audit-log-architecture.md) |
77–84 |
doc-21-integration-schema-architecture.md |
Doc 21: Integration Schema Architecture | integration-architecture_20260227-0739.md |
— (proposed; not yet resolved into companion) |
doc-22-resource-pool-architecture.md |
Doc 22: Resource Pool Architecture Deep-Dive | CLI session (2026-03-01) | — (synthesis document, no new decisions) |
doc-23-billing-strategy-assessment.md |
Doc 23: Billing Layer Strategic Assessment | billing-strategy-assessment_20260301-0335.md |
— (resolves Issue 18; no new companion decisions yet) |
doc-24-billing-value-architecture.md |
Doc 24: Billing & Value Domain Deep-Dive | CLI session (2026-03-02) | — (synthesis document, no new decisions) |
doc-25-org-access-architecture.md |
Doc 25: Organization & Access Domain Deep-Dive | CLI session (2026-03-03) | — (synthesis document, no new decisions) |
doc-26-identity-credentials-architecture.md |
Doc 26: Identity & Credentials Domain Deep-Dive | CLI session (2026-03-03) | — (synthesis document, no new decisions) |
doc-27-module-boundary-proposal.md |
Doc 27: Module Boundary Proposal | CLI session (2026-03-06) | 94–97 |
doc-28-grants-module-placement.md |
Doc 28: Grants Module Placement — Are Grants a Billing Concern? | CLI session (2026-03-19) | 106 |
doc-29-product-entitlement-rules-placement.md |
Doc 29: Product Entitlement Rules Module Placement | CLI session (2026-03-19) | 107–108 |
doc-30-schema-per-module-adoption.md |
Doc 30: Schema-Per-Module Adoption | CLI session (2026-03-31) | 113–115 |
doc-31-plan-enrollment-recommendation.md |
Doc 31: Plan Enrollment Architectural Recommendation | CLI session (Issue 23, Phase 4) | — (proposed; Issue 23) |
doc-32-plan-management-framing.md |
Doc 32: Plan Management — Terminology, Requirements, and the Shape of the Recommendation | CLI session (Issue 23, Phase 5) | — (framing memo) |
doc-33-architectural-investigation-process.md |
Doc 33: Architectural Investigation — Process | CLI session (2026-04-17) | — (methodology; reusable process reference) |
doc-34-trial-handling-recommendation.md |
Doc 34: Trial Handling Architectural Recommendation | CLI session (Issue 25, compressed pipeline run) | — (resolves Issue 25 with no structural change) |
doc-35-product-kind-taxonomy.md |
Doc 35: Product Kind Taxonomy — Why product_type and product_kinds Coexist |
CLI session (2026-05-12) | — (explanatory reference; codifies the discipline established by Doc 31 Amendment #3) |
doc-36-subscription-change-economics-recommendation.md |
Doc 36: Subscription-Change Economics — Architectural Recommendation | CLI session (2026-05-25; Issue 26, full pipeline run) | 123, 124, 125, 126 |
doc-37-subscription-change-economics-framing.md |
Doc 37: Subscription-Change Economics — Framing Memo | CLI session (2026-05-25; Issue 26) | — (framing memo for Doc 36) |
doc-38-subscription-module-extraction.md |
Doc 38: Subscription Management Module Extraction — Recommendation | CLI session (2026-05-29; Issue 24, full pipeline run) | 127, 128 (resolves Issue 24: keep collapsed, internal seam; confirms Doc 36 placements) |
doc-39-provider-extension-contract-recommendation.md |
Doc 39: External-Service Provider / Extension Contract — Recommendation | CLI session (Issue 28, Stage 4; member-console Milestone 9) | 129–133 (ratified as amended 2026-08-21 — Doc 44; resolved Issue 28) |
doc-40-provider-extension-contract-framing.md |
Doc 40: External-Service Provider / Extension Contract — Framing Memo | CLI session (Issue 28, Stage 5; member-console Milestone 9) | — (framing memo for Doc 39) |
doc-41-product-kind-taxonomy-recommendation.md |
Doc 41: Product Kind Taxonomy and Grant-Issuance Uniformity — Architectural Recommendation (Decisions 134–139; Stage 5 absorbed, §11) | Multi-agent design competition + three-round adversarial review (CLI session, 2026-07-07; Issue 29, Stage 4) | 134–139 (ratified 2026-08-21 by arbitration; resolved Issue 29; integrated into Data Model Reference v15; surfaced Issue 31) |
doc-41-plain-language-guide.md |
Doc 41 Reading Companion — section-by-section plain-language parallel text, every cited document/decision/incident explained in place | CLI session (2026-07-08), verified against Doc 41 and companion.md | — (non-normative reading aid; Doc 41 authoritative) |
doc-42-model-documentation-division.md |
Doc 42: Model Documentation — the descriptive/normative division of labor with member-console docs/models/ (Positions 1–4; proposes Issue 30 on Decision 113 vs. as-built topology, Appendix A) |
CLI session (2026-08-20), position memo for member-console M10 phase 10i | — (positions ratified by same-day arbitration; Issue 30 entered and resolved — see Doc 43) |
doc-43-schema-topology-and-documentation-division.md |
Doc 43: Physical Schema Topology and the Documentation Division of Labor — decision record resolving Issue 30 (supersedes Decision 113's physical claim; ratifies the cross-repo descriptive/normative split; Appendix B carries the design/README.md contract text) |
CLI session (2026-08-20), compressed pipeline per Doc 33; arbitrated by Christian via member-console session | 140, 141 (resolves Issue 30) |
doc-44-provider-contract-ratification.md |
Doc 44: Provider Extension Contract — Ratification Record (Decisions 129–133 ratified as amended upon conformance-gate satisfaction; six findings dispositioned; drift register; Appendix-free — the evidence is member-console status/doc39-conformance-2026-08-21.md) |
CLI session (2026-08-21); gate run as member-console model-cards task 2.5 per arbitration | 129–133 as amended (resolves Issue 28; surfaces Issues 32–33; integrated into Data Model Reference v16) |
issue-24-subscription-module-extraction.md |
Issue 24 Holding Document: Subscription Management Module Extraction | CLI session (2026-04-17) | — (context preserved; resolved by Doc 38, Decisions 127–128) |
issue-29-implementation-findings.md |
Issue 29 Implementation Findings: Grant-Issuance Fork Inventory — dev-team answers verified against application commit b7486c6 |
Implementation-team response (2026-07-07) to prompts/issue-29-dev-team-questions.md |
— (Stage-3 evidence for Issue 29; feeds the brief's decisions 7–9) |
Note: Document 8 (Primary Key Strategy: UUIDv7 Migration) was never produced as a standalone numbered document — confirmed by full extraction including branch artifacts. The domain is covered by Decision 30 in v7_companion.md and by reference-postgresql-pk-strategies.md below.
Policy Documents
Active governance policies. These are normative for ongoing development.
| File | Policy | Source artifact | Decisions |
|---|---|---|---|
policy-soft-delete-terminal-state.md |
Soft-Delete and Terminal State Policy v1.0 | issue-14-policy_20260215-0451.md |
31–33 |
policy-jsonb-governance.md |
JSONB Governance Policy v1.0 | issue-17-policy_20260215-2139.md |
34 |
decision-35-invoice-billing-address.md |
Decision Analysis 35: Invoice Billing Address | decision-35-invoice-address_20260215-2145.md |
35 |
Reference Articles
Standalone reference pieces — published-quality explorations of the technical domains underlying the data model. Valuable independent of the data model itself.
| File | Title | Source artifact |
|---|---|---|
reference-polymorphic-associations.md |
Polymorphic Associations in Relational Databases: Patterns, Trade-offs, and the Exclusive Arc | polymorphic-associations-in-relational-databases-patterns-trade-offs-and-the_20260213-1004.md |
reference-postgresql-pk-strategies.md |
PostgreSQL Primary Key Strategies: The Definitive Guide for 2026 | postgresql-primary-key-strategies-the-definitive-guide-for-2026_20260214-2359.md |
reference-gdpr-irs-retention.md |
When the Right to Be Forgotten Collides with the Obligation to Remember: GDPR Erasure vs. IRS Retention Mandates | when-the-right-to-be-forgotten-collides-with-the-obligation-to-remember-gdpr_20260215-1158.md |
reference-open-source-billing-platforms.md |
Open-Source Billing Platforms: Licensing, Feature Gating, and FOSS Principles Compared | open-source-billing-platforms-licensing-feature-gating-and-foss-principles_20260219-2132.md |
reference-cti-vs-exclusive-arc-heuristic.md |
Class Table Inheritance vs. Exclusive Arc: A Decision Heuristic | cti-vs-exclusive-arc-heuristic_20260214-1354.md |
reference-audit-log-architecture.md |
PostgreSQL Audit Log Architecture for Cooperative SaaS: Multi-Decade Compliance and Partitioning Strategy | postgresql-audit-log-architecture-for-cooperative-saas-multi-decade-compliance_20260223-0845.md |
reference-postgresql-schemas-production.md |
PostgreSQL Schemas Beyond Multi-Tenancy: A Practical Production Guide | postgresql-schemas-beyond-multi-tenancy-a-practical-production-guide_20260226-0921.md |
reference-domain-integration-boundary-methodology.md |
Resolving Boundary-Ambiguous Concepts in Domain Schema Design | resolving-boundary-ambiguous-concepts-in-domain-schema-design-split_20260227-0011.md |
reference-external-service-integration-dimensions.md |
External Service Integration Is Not One Problem: A Seven-Dimensional Analysis | external-service-integration-is-not-one-problem-it-s-seven-dimensional-analysis_20260227-1544.md |
reference-modular-monolith-schema-decomposition.md |
Decomposing a PostgreSQL Monolith into Modular Schemas: Architecture and Best Practices | decomposing-a-postgresql-monolith-into-modular-schemas-architecture-and-best_20260304-0858.md |
reference-saas-nonprofit-tax-treatment.md |
SaaS Nonprofit Discounts: Tax Deduction Rules and Alternative Strategies for 2025 | saas-nonprofit-discounts-tax-deduction-rules-and-alternative-strategies-for-2025_20260319-0622.md |
reference-software-capability-feature-terminology.md |
The Terminology of Software Capabilities, Features, and Their Kin | the-terminology-of-software-capabilities-features-and-their-kin_20260322-0126.md |
reference-plan-enrollment-modeling.md |
Plan Enrollment Modeling in Multi-Tenant SaaS: A Comparative Research Synthesis | plan-enrollment-modeling-in-multi-tenant-saas-a-comparative-research-synthesis_20260414-0842.md |
reference-subscription-change-economics.md |
Subscription-Change Economics: Credit Disposition, Tier-Reduction Reconciliation, and Commitment Terms | CLI session (2026-05-25; Issue 26 Stage 2 research) |
Meta / Process
| File | Description | Source artifact |
|---|---|---|
meta-data-model-design-process.md |
Data Model Design Process — describes the approach, principles, and working style used throughout the design series | data-model-design-process_20260209-2019.md |
Early-Era Historical
Pre-numbered-document artifacts from the January–February 2026 design sessions. Useful for understanding the conceptual evolution from cooperative-specific roots to the generalized v7 architecture.
| File | Description | Source artifact | Date |
|---|---|---|---|
early-cooperative-saas-schema.sql |
Phased cooperative SaaS schema — conceptual foundation for the resource pool model | cooperative_ready_saas_20260127-0957.sql |
2026-01-27 |
early-cooperative-design-philosophy.md |
Cooperative-ready SaaS design philosophy — the phased approach, three principles | COOPERATIVE_READY_SAAS_GUIDE_20260127-0959.md |
2026-01-27 |
early-identity-relationships-explained.md |
Three-layer identity architecture (users / persons / accounts) explained | IDENTITY_RELATIONSHIPS_EXPLAINED_20260128-2211.md |
2026-01-28 |
early-phase1-schema.sql |
Phase 1 schema — GCP-style hierarchy, concrete implementation | phase1_schema_20260130-1951.sql |
2026-01-30 |
early-phase1-architecture.md |
Phase 1 architecture rationale and design decisions | PHASE1_ARCHITECTURE_20260130-1954.md |
2026-01-30 |
early-phase1-data-model-reference.md |
Phase 1 data model reference — field-level reference for identity, org, and workspace layers | DATA_MODEL_REFERENCE_20260205-0743.md |
2026-02-05 |
Curation Notes
Gap Analysis Result
Zero critical gaps found. All 76 decisions in v7_companion.md are fully substantiated by the exploratory documents. Three documents (doc-03, the CTI heuristic, and the design process doc) were produced on off-branch messages and only surfaced after updating extract_artifacts.py to extract from all branches.
Files Not Curated
The following artifact categories were reviewed and deliberately excluded:
- Superseded document revisions — e.g., doc-13 rev 1, doc-14 rev 1, doc-16 rev 1, v6 companion revisions 1 and 2. The canonical revisions are curated; earlier drafts are in
artifacts/. - Intermediate reference versions — v2, v4.1, v5 (parts 1/2 and combined), v6.0, v6.1, v6.2. The v7.0 canonical is the authoritative reference.
- Milestone snapshots — Data Model Reference v6.0 and Companion v6.0 dropped. Version history is tracked in
v7_companion.md; the full artifact series is inartifacts/. - History / analysis working documents — v3 analysis and consolidated open-issues tracker dropped. All issues were resolved and decisions are captured in
v7_companion.md. - v7 migration artifacts —
v7_changeset.mdandv7_new_tables.mdare fully subsumed bydata-model-v7.0.md. - Early SQL/ERD artifacts — Initial Wisconsin-specific SQL schemas (
wisconsin_185_data_model_20260127-0643.sql,identity_domains_schema_20260128-2209.sql) and all Mermaid ERD files dropped. Content was generalized and superseded. - Live canonical duplicates —
v7_companion_20260218-1035.mdanddata-model-v7.0_20260219-0451.mdare exact copies of root-level files; copying them here would create drift risk. - Early option explorations —
option_c_separate_billing.sqland related files from the early cooperative design phase are superseded; concepts evolved into the resource pool model.
Wisconsin-Specific Content
The early Wisconsin cooperative statutory details (liquidated damages limits, voting thresholds, forfeiture windows) were intentionally generalized out of v7. These are jurisdiction-specific and the platform is designed to be cooperative-agnostic.