specs/TrustServiceOnboarding.md defines the mechanism: a Phase Manifest
file is committed to the declaring repo (durable, independently
foldable forever) and separately registered with the hosted service;
once registered, the Ledger's live authoritative copy is the hosted
service only, not a second competing file. Licensor token bootstrapping
is explicitly out of scope here (a WP-0008-T01 governance action).
scripts/trf_onboard.py: a dependency-light CLI (stdlib urllib +
target_revenue.validation only, no FastAPI/psycopg needed to onboard a
Phase) with validate/register-phase/append-entry/status subcommands.
The Licensor token is read only from a named environment variable,
never accepted as a literal argument.
tests/test_trf_onboard.py (4 tests, no network/Docker) proves
invalid-manifest and missing-token-env cases fail before any HTTP
attempt, by monkeypatching the request function to raise if called.
tests/test_onboarding_hosted.py (1 Docker-gated test) runs an actual
uvicorn server on a real socket and drives the full
register -> append -> status round trip through the CLI as an external
repo would invoke it.
migrations/0003_attestations.sql: one row per Phase, no UPDATE/DELETE
grant for trf_app (a published attestation is permanent).
src/target_revenue/attestation.py: publish_attestation() is idempotent
(existing row returned unchanged, never regenerated) and derives
conversion_timestamp from the ledger itself via _find_conversion_prefix(),
which finds the earliest prefix where the fold reaches Outstanding
Target = 0 rather than trusting entries[-1] or wall-clock publish time -
so a later unrelated entry can never change an already-converged Phase's
recorded conversion moment. Raises NotConvertedError rather than
fabricating a conversion. Reuses conversion.generate_attestation()
unchanged. Guarded the psycopg import behind TYPE_CHECKING so the pure
helper stays testable under plain system Python.
service/app.py adds GET /phases/{id}/attestation (unauthenticated,
publish-on-first-observation).
tests/test_attestation.py (3 tests, no Docker/Postgres) proves the
earliest-crossing behavior. 6 new Docker-gated tests in
test_ledger_hosting.py cover pre-conversion 404, the core
legal-technical property that /metrics facts/calculations/forecasts
are identical whether or not /attestation was ever called, one-time
publication, signature verification, and DB-level UPDATE/DELETE
rejection.
src/target_revenue/metrics.py: compute_metrics(manifest, entries, as_of)
is pure/deterministic like fold.py, reusing fold.py/conversion.py
unchanged. Returns facts/calculations/forecasts as three explicitly
separated blocks (TrustServicePRD TS-FR-5), covering the mandatory Q9
set plus the recommended velocity/forecast tier - forecasts are always
null rather than populated once a Phase has converted or velocity is
non-positive, so nothing disguises a projection as a fact.
Adds GET /phases/{id}/metrics (unauthenticated per FR-9/FR-10).
tests/test_metrics.py (6 tests) needs no Docker/Postgres and runs
under plain system Python. One new Docker-gated test in
test_ledger_hosting.py proves the hosted /metrics response exactly
matches compute_metrics() run offline against the same export.
migrations/0002_ledger.sql adds ledger_entries with an identity-column
sequence for exact append order and no UPDATE/DELETE grant for trf_app.
src/target_revenue/ledger.py: append_entry() rejects caller-supplied
previous_entry_hash/signature, enforces per-Licensor phase ownership,
serializes concurrent appends via pg_advisory_xact_lock, computes the
chain tip and signs with the Trust Service instance's own Ed25519 key
(service/keys.py), reusing validation.py's checks unchanged. Adds
POST/GET /phases/{id}/ledger and an unauthenticated GET /public-key.
Also fixes a route-ordering bug found while wiring this in: phase IDs
never needed the {phase_id:path} converter (they contain colons, not
slashes), and its greedy matching was swallowing /ledger-suffixed
paths into the plain GET /phases/{id} route.
tests/test_ledger_hosting.py (8 Docker-gated tests) exercises hash-chain
linkage, forged-field rejection, cross-Licensor isolation, currency and
duplicate-id rejection, DB-privilege enforcement, signature
verification via the public-key endpoint, and the task's own
highest-priority property: append -> export -> offline fold reproduces
the exact expected Development/Remission Credit and Outstanding Target.
Adds migrations/0001_registries.sql (licensors, phase_manifests,
extensions tables; trf_app role with no UPDATE/DELETE grant on either
table, canonicalization only via a SECURITY DEFINER function), and
src/target_revenue/registry.py + service/app.py: a thin FastAPI layer
wrapping the existing validation.py checks with persistence and
per-Licensor token auth, adding no new validation logic per ADR-0002.
New optional service/service-dev dependency groups keep the core
offline library dependency-free. tests/test_registry_hosting.py (7
tests, Docker-gated, auto-skip otherwise) spins an ephemeral disposable
Postgres container and verifies registration, rejection, duplicate/
unknown-token handling, extension canonicalization, and two explicit
database-privilege checks that the app role cannot bypass the
append-only/governance-gated guarantees.
Maintainer (Bernd) accepted 2026-07-29 with no changes requested.
T03-T08 may now build against PostgreSQL + per-Licensor API tokens +
railiance-cluster hosting + Python/src/target_revenue reuse.
Proposes PostgreSQL with database-enforced append-only guarantees,
per-Licensor API tokens decoupled from the existing Ed25519 entry
signatures, and railiance-cluster's existing k3s/GitOps baseline for
hosting rather than new infrastructure, reusing src/target_revenue/
directly behind a thin HTTP layer. Task left todo per the human-accept
gate policy already applied to ADR-0001.
Elaborates framework PRD FR-8/9/10 for a hosted, multi-tenant service:
stakeholders, which Stage 0 guarantees (WP-0002) carry over unchanged
vs. which single-Phase/no-auth/no-tenancy constraints must lift and
onto which task (T03-T08), functional/non-functional requirements, and
an API surface sketch. Flags that no current task owns hosting the
Breach/Compliance Record component added by License V1C1 SS7.4.
Maintainer decision (2026-07-29): full specialist legal review of the
TRSL/CUA is postponed until the framework moves out of beta, given
limited legal/commercial exposure during build/alpha. WP-0004-T10 and
WP-0005-T10 synthesize their jurisdiction research into adopted alpha/beta
working defaults (governing law -> arbitration at a neutral seat,
liability cap, data protection minimal-collection practice, and the
Enforcement Network's fee mechanics) rather than full resolution, and are
accepted on that basis. Propagates the decision to the License/CUA V1C1
Appendix A tables and status banners, SCOPE.md, CONTRIBUTING.md, the
WP-0008-T05 go-live gate, and README.md.
With WP-0001/0002/0003 finished, PRD Phase 4b (hosted Trust Service) is
unblocked per SCOPE.md's own sequencing rule, and the midterm goal shifts
from framework design to practical application: governing and monetizing
repos across the coulomb Forgejo org's product lines (coulomb-loop,
net-kingdom, helix-forge, the railiance-* family).
- TREV-WP-0006: Trust Service reference implementation (PRD Phase 4b).
Eight tasks from PRD to conformance-tested hosted service, explicit that
it builds infrastructure only - no real payments or Phase tracking.
- TREV-WP-0007: Degeneration policy finalization (PRD Phase 5) and the
full canonical monetization profile catalog (remainder of Phase 3) -
pilot Phases can't responsibly launch on the placeholder pilot policy
and one-line profile defaults alone.
- TREV-WP-0008: Governance formalization (PRD Phase 7) and pilot rollout
preparation. Forces a real design decision the framework never had to
answer while single-repo-hypothetical: who is "the Licensor" across four
independent product lines. Produces draft, non-binding Phase Manifests
as worked examples for one repo per product line, and a CLA draft.
All three explicitly preserve SCOPE.md's existing "no production Phases
until legal review" guardrail rather than overriding it under pressure to
monetize real repos: WP-0008-T05 is a dedicated, human-gated go-live
decision, and no other task in any of the three workplans is permitted to
authorize a real Phase, real Commercial Entitlement sale, or real
Development Credit tracking.
Updates SCOPE.md (new Stage 0/Stage 1 maturity table, revised out-of-scope
table distinguishing "infrastructure in scope" from "going live still
gated"), PRD roadmap (Phase 4b/5/7 now active, pointing at the new
workplans), and README's active-work table accordingly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Bernd reviewed all four extracts (TargetRevenueFrameworkCore.md,
PhaseManifestSpecification.md, TargetLedgerSpecification.md,
MonetizationExtensionSpecification.md) plus cross-links and open-question
coverage. Six-item checklist complete: one real fix (§1.11's extension-
redefinition list had drifted broader than concept §7.11's closed list),
one polish pass (PRD/CONTRIBUTING cross-link symmetry), four items
confirmed with no changes needed. Marks WP-0003-T06 done and the WP-0003
workplan finished (all 6 tasks complete).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per reviewer request (polish only, item 5): added the same "ultimate
source / day-to-day reference" dual-citation to the PRD header's
Terminology alignment line, matching README/TSD/CONTRIBUTING. Named all
three other normative extracts (PhaseManifestSpecification.md,
TargetLedgerSpecification.md, MonetizationExtensionSpecification.md) in
CONTRIBUTING.md's Terminology section, which previously named only
TargetRevenueFrameworkCore.md - now symmetric with README's full
four-document table.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Verified the six-field extension contract matches concept §12's YAML
verbatim, the core-term redefinition list matches (consistent with the
item 1 fix), registered/canonical wording matches concept §12.1-§12.2, and
the six canonical candidates match concept §12.2's list in the same order
with product-ideation/general-consulting honestly labeled as not yet
fixture-backed rather than implied complete.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Verified three reviewer notes against the actual spec and schema files:
Rule 1's bare "Required" wording vs longstop_at's "Required for Stage 0"
tier label reads unambiguously given §4 and the schema; degeneration_policy
is correctly plain Required with Q7 (which pilot policy) appearing only in
the schema field description, not as a tier qualifier; target_basis's
optional-object-with-Recommended-subfields structure matches the schema
exactly. All three confirmed as non-issues, not drift.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
WP-0003-T06 review finding: §1.11 paraphrased concept §7.11's closed
extension-redefinition list (Phase, Initial Target, Development Credit,
Remission Credit, Outstanding Target, Conversion Event, Future License) as
"any term in this section" - silently broadening the constitutional
boundary to also cover Milestone Release, Target Multiple, Trust Service,
and Monetization Profile/Extension itself. This created an inconsistency
with MonetizationExtensionSpecification.md §3, which already carried the
concept's narrower list correctly, and would have left the extract and its
sibling document silently disagreeing on what an extension may not touch.
Corrected §1.11 to quote the closed list verbatim, matching the concept,
MonetizationExtensionSpecification.md, TSD §5, and PRD FR-4 (all four of
which already had it right). Whether the broader rule might be desirable
is a separate design question from this faithfulness fix, and is not
addressed here.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Found while preparing WP-0003-T06 for review: §5's prose still named the
unsplit administrative-correction type (renamed to
administrative-correction-development/-remission earlier this session) and
incorrectly implied both admin-correction types require a reverses
pointer, when only credit-reversal and remission-correction do.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Bernd reviewed the License candidate and accepted it, conditioned on one
refinement to §1's "Commercial Use" definition: replaces the prior
circular definition ("use other than Noncommercial Use") with an
objective, billing-based trigger. Commercial Use now means billing a
customer for pre-conversion Software use, full stop - regardless of
whether the resulting payment is registered with the Trust Service.
Billing without recording the payment in the Target Ledger is Commercial
Use without a valid Commercial Entitlement, a Section 3 violation
addressed under Section 7 and, where applicable, the Enforcement Network.
This substantially resolves the affiliate/contractor/mixed-purpose/
public-sector ambiguity Appendix A item 1 flagged, since classification
no longer depends on who the customer is, only on whether they are
billed. A narrower residual item remains open: whether consumer-
protection law overrides this classification for an individual/sole-
proprietor customer in a given jurisdiction (the same recurring pattern
found across WP-0004's jurisdiction research).
Updates the document's status banner: condition 3 (human acceptance) is
now met; conditions 1 (specialist legal review) and 2 (full Appendix A
resolution) remain open - V1C1 is accepted as adequate briefing material
for counsel, not yet official Version 1.0. Marks WP-0001-T06 done and the
WP-0001 workplan finished (all 6 tasks complete). Updates
OpenQuestions-WorkingDefaults.md Q2, README, and CONTRIBUTING.md to match.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Cross-cutting research (New York Convention enforceability, neutral-seat
arbitration practice, and a consolidated drafting principle) revises the
China finding from T06/TREN-T06: China has enforced the New York
Convention since 1986 (arbitral awards travel via a ~172-state regime
with limited refusal grounds) but has ratified no foreign-judgment
convention, relying on patchy bilateral treaties and evolving reciprocity
for court judgments specifically. Arbitration, not the litigation-focused
China rider previously recommended, is likely the more promising
enforceability path for a Chinese Customer - and for the Enforcement
Partner Agreement too, per a cross-reference added to
specs/EnforcementNetworkConcept.md.
Also produces a consolidated drafting principle: write clarity-sensitive
clauses to satisfy Germany's Transparenzgebot, UK's UCTA reasonableness,
and Australia's expanded Unfair Contract Terms regime simultaneously,
since research this program has already found separately shows none of
the three reduces to another.
Updates License Appendix A item 6 and CUA Appendix A item 1 accordingly.
WP-0004 now has 9 of 10 tasks done; only the human-gated T10 synthesis
remains.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per maintainer correction: the previous "Standard Bounty Amount" was still
paid only on success, meaning it remained outcome-contingent and would not
actually escape prohibitions worded around outcome-contingency generally
(India's Rule 20: "a fee contingent on the results of litigation") rather
than percentage-proportionality specifically (Germany's quota-litis-style
rules). Renamed to "Standard Financing Amount" and restructured as a fixed
sum paid or made available regardless of the Enforcement Action's outcome
- a grant toward litigation cost, not a contingent fee in any form.
specs/EnforcementNetworkConcept.md §13 rewritten as a sequential rule
rather than "higher of two comparable numbers" (contingent percentages and
non-contingent financing are not commensurable, and treating them as
interchangeable is exactly what would make the financing look like a
disguised contingent fee):
1. 50% Contingency Share where lawful at that level.
2. Else the jurisdiction's own lower lawful outcome-contingent cap.
3. Else - no lawful outcome-contingent fee exists at all - no
Contingency Share; the Licensor's own non-contingent fee arrangement
with its lawyer governs what's owed win or lose, and the Trust
Service's Standard Financing Amount offsets that cost regardless of
outcome. Fee risk is genuinely higher here, by design: this is what
it means for the risk-shifting a contingent fee normally provides to
be unavailable, not an oversight to paper over.
New §13.0 makes explicit (per maintainer instruction) that nothing in this
rule creates a right for the Trust Service, an Enforcement Partner, or a
Litigation Funder to initiate a case - pressing charges remains
exclusively the Licensor's decision. The rule only makes a ready,
low-friction default (published caps, financing, EPA template) available
once that decision is made.
Added new core term §5.9 Standard Financing Amount; updated §5.5-5.7, §6's
lifecycle step, §9's EPA outline, and the concise definition to match.
Updated WP-0005 T10's synthesis scope and README accordingly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Per maintainer request, replaces the flat "working default 50%" Contingency
Share with a systematic per-jurisdiction rule, directly responding to
WP-0005's finding that 50% is unsafe almost everywhere except the UK:
1. 50% applies if lawful in the jurisdiction.
2. Otherwise, the higher of:
(A) the Jurisdiction Percentage Cap - the actual local statutory
maximum, published by the Enforcement Registry as background
information for prospective Enforcement Partners; or
(B) a Standard Bounty Amount - a fixed sum (not a percentage),
defaulting to $1,000 local-currency-equivalent, recalculated
annually to 50% of the trailing-18-month average unpaid-fees
amount where more than 10 settled cases exist (a sample-size floor
to avoid thin-sample noise), announced by 31 July, effective the
following 1 January, always capped at the specific case's own
unpaid fees.
Flags, as the highest-priority open question this rule itself introduces:
whether a fixed, non-percentage bounty actually escapes contingency-fee
prohibitions worded around outcome-contingency generally (India's Rule 20:
"contingent on the results of litigation") rather than percentage-
proportionality specifically (Germany's quota-litis-style rules) - the
Standard Bounty Amount may not solve what it was designed to solve in
exactly the jurisdictions that motivated it, and this is not yet verified.
Added as new specs/EnforcementNetworkConcept.md §13 (Concise Definition
renumbered §14; no other section numbers changed, so existing cross-
references to §5.5/§6/§8/§9/§11 from workplans and history/ artifacts
remain valid). Updated §5.5, §5.7, and §8's key findings to point to the
new rule. Folded the rule's population and open questions into
WP-0005-T10's synthesis scope.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Executes all remaining shared jurisdictions across both workplans:
Germany/EU (deepened contract-law angle), US (deepened), UK (deepened),
Argentina, India, China, Africa (South Africa + OHADA), and Asia-Pacific
(Singapore, Japan, Australia) - 13 new history/ research artifacts.
Highest-priority findings:
- Australia's Unfair Contract Terms regime (expanded Nov 2023) covers
standard-form contracts with any business under 100 employees/$10M
turnover by default - the CUA is exactly such a contract, and most
realistic Customers fall within this threshold. Unlike every other
jurisdiction's consumer carve-out, this is not an edge case.
- China requires a "foreign-related" contract even to select foreign
governing law, subject to a vague public-interest override even then -
confirms a dedicated China rider is needed for both the License/CUA and
the Enforcement Partner Agreement, not a shared global clause.
- India flatly prohibits advocate contingency fees (no exception gates,
stricter than Germany) while explicitly permitting third-party
litigation funding - the cleanest confirmation yet that the Litigation
Funder/Local Counsel split-role model is both necessary and legal there.
- Japan's Article 12 fee-splitting rule means even the split-role
fallback needs jurisdiction-specific structuring - the first case where
the workaround itself, not just the original mechanism, has an open
compliance question.
- Contingency Share ceilings vary widely where available: UK 50% (exact
match), South Africa 25%, Argentina 35% (50% only with risk assumption),
China 18% down to 6% on a sliding scale that shrinks as claims grow.
- Recurring cross-jurisdictional pattern (Germany, EU, US via CCPA,
Argentina): B2B governing-law/liability clauses are respected, but an
individual/sole-proprietor Customer's consumer-protection status is the
operative risk everywhere, not a one-off edge case.
Updates specs/EnforcementNetworkConcept.md §8.1 with a full 12-jurisdiction
findings table and three cross-cutting conclusions. Updates both V1C1
documents' Appendix A items (governing law, liability cap, data
protection) with the most consequential findings. Both workplans now have
only their human-gated synthesis tasks (T09-T10 / T10) remaining.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Introduces specs/EnforcementNetworkConcept.md: independent, locally-licensed
Enforcement Partners pursue unauthorized Commercial Use (License §3
violations) in their home jurisdiction for a Contingency Share of Recovery,
so enforcement scales the way the framework's monetization already does -
through aligned incentive rather than central litigation capacity. New
terminology (Alleged Violation, Enforcement Action, Recovery, Contingency
Share, Platform Share, Enforcement Registry, Enforcement Partner Agreement)
plus a proposed enforcement-recovery Monetization Extension so Recovery
flows into Development Credit through the existing accounting model rather
than a parallel bucket.
Flags the mechanism's central risk up front rather than assuming it away:
lawyer contingency fees are not legal everywhere. Backed by
workplans/TREV-WP-0005-enforcement-network-research.md (10 tasks); four
executed this session with live web research:
- Germany/EU: RVG §4a permits contingency fees only in three narrow gates,
none fitting this fact pattern well - single-role Enforcement Partner is
very likely not viable; France permits a fixed-fee-plus-uncapped-result-
fee structure instead; EU litigation-funding regulation is proposed
(2022 EP resolution) but not yet adopted.
- US: contingency fees broadly permitted; practical precondition is timely
copyright registration of the Milestone Release to unlock statutory
damages/fee-shifting; Copyright Claims Board flagged as a lower-cost venue.
- UK: Damages-Based Agreements cap fees at 50% for this case category -
the concept's originally-proposed 50% Contingency Share lands exactly on
this real statutory ceiling, the first jurisdiction where the figure is
precisely validated rather than arbitrary.
- Mechanism design: synthesizes the above into a single Enforcement Partner
Agreement template with jurisdiction-conditional role structure
(single-role vs. Litigation Funder/Local Counsel split), with a payment-
flow diagram showing the Development Credit allocation is unaffected by
which structure applies.
Six of ten WP-0005 tasks remain open (Argentina, India, China, Africa,
Asia-Pacific, and the human-gated synthesis). Cross-referenced from README.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
