Rholang improvement plan

This is the ranked Rholang backlog from the audit and HAZOP. The machine-readable record is spec/improvements/rholang.yaml. Every item cites a finding and at least one HAZOP row; Phase 2 may not start until the review accepts the finding.

Staged policy

Phase 1 changes no contract. Phase 2 implements accepted items with the listed tests and a compatibility note. A breaking change requires a migration note and an updated suite. A P0 is not “fix immediately”; it is “requires an explicit review decision before Phase 2”. The review may accept, reject, or accept the risk.

Ranked items

The HAZOP rows for each item are in the manifest. Representative links:

• RR-01: HZ-ORACLE-004, HZ-ORACLE-005.
• RR-02: HZ-PROV-002, HZ-PROV-003, HZ-PROV-012.
• RR-03: HZ-VP-005, HZ-VP-013.
• RR-04: HZ-CLAIM-004, HZ-CLAIM-005, HZ-CLAIM-007.
• RR-05: HZ-DEPLOY-002, HZ-KASSET-016.
• RR-07: HZ-CLAIM-016, HZ-VP-016, HZ-ORACLE-016.
• RR-08: HZ-ORACLE-013, HZ-ORACLE-015.
• RR-11: HZ-ID-011, HZ-CRED-015, HZ-CLAIM-015, HZ-KASSET-015.

Phase 2 progress

• RR-04 is fixed: claimStatus and kassetStatus both map valid to validated, partial to conditional/validated, and invalid or unknown to rejected. An unknown verdict no longer produces a validated claim beside a rejected K-Asset. Pre-write rejection remains a follow-up.
• RR-01 is partial: OracleFactory.open now authenticates the opener and requires it to match caseReq.openedBy. Parties and subjectRef remain caller-supplied; registry binding is open. The Phase 2 guard checked caseReq.subjectRef, but KAsset.openDispute and VP.openDispute pass the subject as a separate argument and never put it in caseReq, so every dispute refused with case fields. The guard now checks the subjectRef parameter. unit_core reaches dispute, decision, execution and provenance on the rebuilt contracts.
• RR-02 is partial: ProvenanceFactory.create now authenticates the creator and rejects an empty writer list. assetRef is still a free string; asset-registry binding is an extension.
• RR-08 is fixed: Apply.applyDecision returns already applied when the K-Asset already has the decision outcome, and OracleCase.execute records a pending/applied/failed receipt with the case id, decision, and outcome so a retry can reconcile a partial cross-contract failure.
• RR-03 is fixed: ValueProposition.proveValidated reads nowHeight and rejects a supplied atHeight that differs from chain height.
• RR-05 is fixed: KAsset.nest caps a batch at 32 children and the parent list at 64, rejecting larger batches before proof consumption.
• RR-07 is partial: claim creation now requires a deadline and rejects a comment window after the deadline. Claim and VP creation now require a future deadline; oracle future-ness remains open.
• RR-11 is partial: claim validation writes a validating receipt and gains Claim.resume; identity create writes a pending directory entry and gains IdentityFactory.resume. Nest proof-consumption recovery remains.
• The other items remain proposed. On 2026-11-04 the isolated devnet was started with 8 GB and make install unit-all passed all ten suites on the rebuilt contracts. The earlier 4 GB attempt failed with exit 137; the memory requirement is documented in the devnet guide.

Policy decisions

• RR-06: Credential.check is advisory. It accepts a caller-nominated subject and no core commit may use it; tools/check_concurrency.py forbids it as a commit authority.
• RR-09: identity is not a prerequisite for claim or comment participation. This is documented as intentional; harness/unit_claim.py already exercises an unregistered commenter. It can be revisited if Sybil resistance becomes a requirement.
• RR-10: directoryState and factoryState remain explicit serialization points. No cap or sharding is implemented; a cap would be a breaking change at the cap.

Atomicity residual risk (RR-11)

The remaining P0 findings are cross-cell failure windows, not guard bypasses:

• Identity create: identityState and the bundle registration precede the directoryState write. A failure after registration but before the directory write can leave an identity cell and bundle that the directory does not reference; a retry can create a second one. A recovery record needs the emitted identity URI and a pending/finalized directory status.
• Claim validation: finalizeValidation mints the K-Asset before writing the claim’s validationRef and kassetRef. A failure between those writes can leave a K-Asset with no claim reference, or allow a retry to mint another. A validation receipt in the claim state is the intended fix.
• K-Asset nest: nestProofs consumes each child approval proof before the parent writes childRefs. A failed parent write consumes the proofs while the parent is unchanged. A nest receipt that records the consumed child ids or the proof payloads is the intended fix.

No current Phase 2 change claims to close these. They remain accepted P0 items with the failure window documented; the devnet suites cannot exercise them without crash/failure injection.

Phase 3 candidates

• Bind oracle subjectRef and provenance assetRef to a registry instead of a free string.
• Add an explicit oracle execution receipt and a claim validation receipt.
• Add identity-create and nest recovery records for the failure windows above.
• Add a registry cap/sharding plan or a measured throughput limit for directoryState/factoryState.

Why these orderings

• State integrity first. RR-04 and RR-11 prevent a claim and its K-Asset, or a parent and its child proofs, from disagreeing. They are the highest-value contract changes.
• Authority next. RR-01 and RR-02 close unauthenticated record creation. Neither is a direct authority bypass today, because the private Apply and the advisory nature of provenance limit the impact; both are record-integrity hazards.
• Time and resources after that. RR-03, RR-05, and RR-07 remove caller-controlled height, unbounded nest work, and impossible schedules. They are availability and API hazards.
• Documentation and policy last. RR-06, RR-09, and RR-10 make advisory and design choices explicit. They may close with no code change.

What is not in this plan

No KATs, payments, risk scoring, panels, governance, handles, or metrics primitives. They remain extensions. No change to the five paper-derived primitives’ core purpose. No new token or minting arm. No attempt to make the contracts a refined implementation of the Lean model; that requires a Rholang semantics, which this repository does not have.

Test plan

Each item names the harness suite that must gain a negative case before the fix and a passing case after it:

The devnet suites are nightly/manual (RGA-011). A Phase 2 change that cannot be covered statically adds its negative test to the nightly job and documents that it did not run on the pull request.

Open decisions for the review

1. Keep proved-conformance and define it as an evidence bundle, or rename it model-vector-conformance? Recommendation: keep the name, publish the definition.
2. Oracle execution: keep a permissionless crank with an idempotent receipt, or require subject authorization? Recommendation: keep the crank, make it outcome-blind and receipt-backed.
3. Identity participation: enforce an Identity record, or document permissionless participation as intentional? Recommendation: document it, test it, and revisit if Sybil resistance is a goal.
4. Provenance creation: require an asset registry binding, or state that provenance is advisory? Recommendation: require a creator capability and non-empty writers now; treat registry binding as an extension.