Documentation / The grand monorepo

HiNet — Decentralized Grand Monorepo (GM)

Status: Draft spec (v1) · Companion to Whitepaper §3/§6A/§6B, Sovereign-Intelligence-Vision, Technical Spec · Fills the P-K slot in master-task-list · Depends on P-I (Node Identity & Registry)

Legend: [EXISTS] already built in app/osx/hinetd · [SPEC] designed elsewhere, not yet built · [NEW] introduced by this document · [MVP] first build target · [LATER] deferred protocol surface.

0. One-paragraph thesis

Every developer-owned iCore (one human's sovereign MoE — [Vision §2]) can, in dev-mode, freely contribute signed code to a single network-wide repository — the Grand Monorepo (GM) — that no one owns and everyone builds. The GM is the code analogue of the GQ (Grand Quorum): a fractal, decentralized artifact assembled from atomic sovereign contributions. It is stored as a git-like content-addressed object graph on a decentralized filesystem (IPFS/IPLD), its branch pointers anchored by the HiNet registry (central now → DHT/on-chain later), its merges gated by membrane-aware governance, its builds reproducibly attested, and every contribution signed, attributable, and paid through the existing economy (§6A/§6B). It reuses HiNet primitives exactly — node identity from the registry spec, the consent gate, the audit hash-chain, the CanonicalItem content-hash pattern, the ComputeBackend WorkOrder/BackendReceipt seam, and the aCore thought-convergence + threshold-signing pattern — rather than inventing parallel machinery.

1. Where this sits in the HiNet stack

Layer	GM's relationship
iCore (1 human's MoE) `[EXISTS]`	The author, reviewer, and builder. In dev-mode it drives the coding root + repo tools.
Node Identity & Registry (P-I) `[SPEC]`	Source of the Ed25519 keypair + `node_id` + owner + capabilities + iCorp binding. Every GM signature is verified against a registry pubkey. GM adds no new identity system.
Membrane (org/gov boundary) `[EXISTS-concept]`	Scopes visibility and merge rights. Public GM subtrees are world-visible; iCorp subtrees live behind the membrane (a private overlay repo, §9).
Economy (§6A pay-per-use / §6B lease) `[SPEC]`	Contribution, review, build, and downstream code usage all emit attribution receipts that feed the pay-per-use split. A leased iCore's contributions stay in the iCorp on exit — same lease rule as intelligence.
aCore verification (thought-convergence, `ThresholdSignedOutput`) `[SPEC]`	Reused verbatim for merge quorums and reproducible-build consensus — code review/build is a deterministic-enough duty to threshold-sign.
ComputeBackend seam (`WorkOrder`→`BackendReceipt`) `[SPEC]`	Reused as the build executor: a build is a signed WorkOrder returning a verified receipt.
VaultReplication (ciphertext → owner-owned + decentralized-FS targets, content-addressed) `[SPEC]`	Same decentralized-FS substrate (IPFS/Arweave/Storj). GM is its public, plaintext, shared sibling; VaultReplication is the private, encrypted, personal one. Shared IPFS node + pinning infra.

Central infrastructure note: GM's central services — the ref registry, the default pinning service, the seed IPFS peers, and the build-attestation coordinator — run on the Quorumz GCP project with their OWN resources dedicated to mind.quorumz.com / HiNet, isolated from Quorumz product resources.

2. Storage — a git-like content-addressed model on a decentralized FS

2.1 Object model (git objects → IPLD DAG nodes) `[NEW]`

The GM reuses git's three-object model, but each object is an IPLD block encoded as dag-cbor and addressed by a CID (CIDv1, multihash = sha2-256, multicodec = dag-cbor). CIDs replace git's SHA-1 object ids and give free global dedup + verifiable references — exactly the pattern canonical.py::compute_content_hash / make_id already establishes locally (sha256 content addressing), lifted onto the network FS.

# Blob — file content. Large files chunked via UnixFS (raw-leaves); small files inline.
Blob:
  # not a struct — a UnixFS/raw node; CID(blob) = content address of the bytes
  # dedup: identical file across the whole network stores ONE block

# Tree — a directory. Sorted entries → deterministic CID (like a git tree).
Tree:
  entries:
    - name: "server.py"
      cid:  "bafy…"          # CID of a Blob or a subtree Tree
      mode: "0644"           # 0644 file | 0755 exec | tree
      type: "blob"           # blob | tree | submodule
  # canonical encoding: entries sorted by name, dag-cbor → one CID per unique tree

# Commit — a snapshot + lineage + authorship + signature.
Commit:
  schema_version: "gm-1.0"
  tree:      "bafy…"                    # root Tree CID (the whole monorepo state)
  parents:   ["bafy…"]                  # 0 for root, 1 normal, 2+ for merges
  author:    "icore_ab12…"             # node_id from the registry (P-I)
  author_owner: "did:key:z6Mk…"        # optional human/owner id (Ed25519 multicodec; Node-Identity §1.2)
  committer: "icore_ab12…"             # may differ (e.g. a merge quorum)
  message:   "fix: cross-lingual retrieval ranking"
  timestamp: "2026-08-18T09:00:00Z"
  base_ref:  "refs/heads/main"          # the ref this was authored against
  parent_span: {path: "app/osx/hinetd", subtree_cid: "bafy…"}  # optional: scoped edit
  sig:                                   # Ed25519 over the canonical commit bytes (tree+parents+meta)
    scheme: "ed25519"
    node_id: "icore_ab12…"
    value:  "…"

Why monorepo, not many repos: a single root Tree makes the whole network's code one addressable DAG — you can pin/checkout any subtree by CID, attribution is a single blame-graph, and cross-cutting builds are one dependency graph. Sparse checkout (§2.4) keeps it tractable.

2.2 On-FS layout `[NEW]`

Blocks (blobs/trees/commits) live in IPFS as dag-cbor/UnixFS blocks, exchanged over libp2p bitswap [SPEC-aligned: Technical Spec already recommends libp2p/Helia].
Pinning = availability. IPFS GC's unpinned blocks, so reachability is a policy choice:
Merged content is pinned by the network pinning service (Quorumz-GCP HiNet resources) [MVP] and, later, by iCore Primes that opt in as storage providers [LATER] (a Prime is "a bitcoin miner for intelligence" — here also a storage/replication node).
Open proposals are pinned by the proposer's node (+ a small refundable bond pin on the coordinator) so spam doesn't bloat network storage (§6/threat model).
Alternative substrates (pluggable StorageBackend, mirrors the ComputeBackend/VaultReplication pattern): Arweave for permanent tagged releases (pay-once permanence), Storj/Filecoin for paid durable pinning. Trade-off table §7.

2.3 Mutable pointers — the hard part `[NEW]`

Content-addressing is immutable; branches move. Three ref backends, chosen by maturity:

Ref backend	How	Trade-off	Phase
Registry-anchored signed ref	The central RefRegistry (P-I registry, own GCP resources) stores `{ref_name → {commit_cid, updater_node_id, seq, sig}}`; updates are Ed25519-signed by an authorized updater and monotonic (`seq` strictly increases → no rollback).	Fast, simple, censorship-visible (updates are signed + logged), but one central anchor. Acceptable: it stores only pointers, never content; content stays on the decentralized FS.	MVP
IPNS (+ pubsub)	Each ref is an IPNS name keyed by a ref-key; updates published over libp2p pubsub.	Fully decentralized, but IPNS resolution is slow/flaky and key-per-ref is awkward. Use for a decentralized mirror of the registry ref.	LATER
On-chain ref anchor	A contract on the HiNet chain holds `ref → commit_cid` with governance-gated writes; refs become trustless + composable with settlement/staking.	Trustless + pairs with the token economy, but adds chain deps + latency.	LATER

MVP decision: registry-anchored signed refs, with the RefUpdate object itself content-addressed and appended to the audit chain so the ref's whole history is tamper-evident (reuse audit.py _digest hash-chain — see §5.2). This mirrors P-I's stated "central now → DHT/decentralized index later."

2.4 Clone / checkout / sparse `[NEW]`

Checkout(ref) → resolve ref→commit_cid from RefRegistry → fetch Commit → walk Tree → bitswap only the blocks you don't have (CID = you already have identical content ⇒ skip). Merkle structure = incremental, verifiable sync for free.
Sparse checkout(ref, path) → resolve the subtree CID at path and fetch only that DAG — critical so a laptop iCore never materializes the whole network's code.
Reuses the dev_tools confinement model: a checked-out subtree is a project_root, and the existing list_dir/read_file/search_code [EXISTS] operate over it unchanged.

3. Contribution model — propose · review · merge · govern

3.1 Identity of a contributor `[SPEC dependency → P-I]`

Every actor is a registered node: node_id, Ed25519 pubkey, owner, capabilities/specialities, endpoint, iCorp binding, last-seen — held by the registry (P-I). GM never mints identity; it looks up the pubkey by node_id and verifies signatures. (Note: node.py/audit.py today produce an unsigned content-free hash-chain [EXISTS]; P-I adds the keypair [SPEC]. GM consumes P-I's keypair — it does not build a second one.)

3.2 The Proposal object (a signed "PR") `[NEW]`

An iCore proposes a change as a Proposal — a signed object referencing an immutable new commit built atop a known base:

Proposal:
  id: "prop_9f3…"                  # = sha256(commit_cid | base_cid | author)  (canonical id, like make_id)
  target_ref: "refs/heads/main"
  base_commit: "bafy…"             # tip the author branched from (3-way merge base)
  head_commit: "bafy…"             # the proposed Commit CID (already signed by author, §2.1)
  scope_paths: ["app/osx/hinetd/hinetd/memory.py"]   # touched subtrees (drives reviewer routing)
  title: "Improve RRF weighting"
  body_cid: "bafy…"                # description blob (may be authored by the dev-agent)
  author_node: "icore_ab12…"
  membrane: "public"               # public | icorp:<icorp_id>  (visibility + merge gating, §9)
  bond: {amount: "…", receipt: "…"}   # refundable anti-spam bond (LATER: real settlement)
  sig: {scheme: "ed25519", node_id: "icore_ab12…", value: "…"}   # over the canonical proposal bytes
  created_at: "…"

Because head_commit is content-addressed and signed, a Proposal is immutable + non-repudiable; "updating a PR" = submitting a new head_commit (a new revision, linked by id).

3.3 Review `[NEW]`

Review:
  proposal_id: "prop_9f3…"
  revision: "bafy…"                # exact head_commit reviewed (reviews bind to bytes, not "the PR")
  reviewer_node: "icore_cd34…"
  verdict: "approve"               # approve | request_changes | reject | comment
  comments_cid: "bafy…"            # optional inline comments blob
  build_receipt: "brc_…"           # optional: reviewer attaches a passing build (§4)
  sig: {scheme: "ed25519", node_id: "icore_cd34…", value: "…"}
  created_at: "…"

Reviewers are routed by competence-signature (the same router used for quorum aggregation, P-J / M5-005): the network right-sizes to the minimal sufficient reviewer set whose specialities cover scope_paths and who are maintainers of those subtrees. A reviewer iCore evaluates by driving its coding root over a sparse checkout of base_commit + the diff (§5.4).

3.4 Governance — who can merge `[NEW]`

Governance is in-repo and content-addressed (like CODEOWNERS, but signed and membrane-aware), so the rules evolve through the same propose→merge process they govern:

# /.hinet/governance.yaml  (a versioned blob; root changes need the highest quorum)
GovernanceDoc:
  version: 3
  roots:
    "/": { maintainers: ["icore_root1…","icore_root2…"], threshold: "3-of-5" }
  subtrees:
    "app/osx/hinetd/**":
      maintainers: ["icore_ab12…","icore_cd34…","icore_ef56…"]
      merge_rule:  "2-of-3 maintainer approvals + 1 passing build receipt"
      membrane:    "public"
    "icorp/acme/**":
      maintainers: ["icore_acme_lead…"]
      merge_rule:  "1 maintainer + iCorp membership"
      membrane:    "icorp:acme"
  policies:
    require_reproducible_build: true      # MVP: 1 builder; LATER: N-of-M cross-check
    min_reviewers_by_sensitivity: {normal: 1, security: 2}
    max_proposal_rate_per_node: 20/day    # spam control (§6)

Merge = a governed state transition producing a new signed Commit whose committer is the merge quorum:

MergeDecision:
  proposal_id: "prop_9f3…"
  revision: "bafy…"
  new_commit: "bafy…"              # 3-way merge result (or fast-forward = head_commit)
  approvals: ["Review…","Review…"] # satisfying the subtree merge_rule
  build_receipts: ["brc_…"]        # satisfying require_reproducible_build
  ref_update: {ref: "refs/heads/main", from_seq: 41, to_seq: 42, new_cid: "bafy…"}
  quorum_sig:                      # REUSE aCore ThresholdSignedOutput pattern
    scheme: "BLS-threshold"        # MVP: single-maintainer ed25519; LATER: BLS n-of-m
    threshold: "2-of-3"
    value: "…"
  audit_event_id: "audit_…"        # appended to the tamper-evident chain (§5.2)

The merge-quorum signature reuses the ThresholdSignedOutput object and the ThoughtConvergence discipline from the Technical/Functional specs verbatim: "threshold signatures sign exact canonical bytes" — here the canonical bytes are the new commit CID + ref update, so semantic disagreement about review is resolved before signing the deterministic transition.

3.5 Conflict resolution `[NEW]`

Code (line-oriented): git-style 3-way merge on Blobs against base_commit. Clean auto-merges are fast-forwarded; textual conflicts block the merge and the dev-agent proposes a resolution revision (§5).
Structured files (JSON/YAML config, lockfiles, governance.yaml): merge via Automerge/CRDT [Technical Spec already lists Automerge] so independent edits converge deterministically without a human conflict.
Semantic conflicts (both sides compile, but disagree): caught by the build/test gate (§4) and by reviewer quorum; unresolved → request_changes.

3.6 Flow A — propose → review → merge (text sequence) `[NEW / MVP]`

1. Dev iCore checks out refs/heads/main → base_commit = registry.resolve(ref)   [sparse, §2.4]
2. Dev-agent edits blobs in the working subtree; builds new Tree + Commit; signs Commit (Ed25519)
3. Node bitswap-puts the new blocks to IPFS; pins them locally + posts refundable bond
4. Node POSTs Proposal (signed) → coordinator; audit.append("repo.proposal.created", ref=prop_id)
5. Coordinator routes to competence-matched maintainers of scope_paths (P-J router)
6. Reviewer iCores sparse-checkout base + diff, run dev-agent review, submit signed Reviews
7. A builder node runs the build WorkOrder → signed BuildReceipt (§4)  [merge gate]
8. When approvals + build satisfy governance.merge_rule:
     merge quorum computes 3-way merge → new_commit; threshold-signs MergeDecision + RefUpdate
9. RefRegistry applies RefUpdate (seq 41→42, monotonic); appends to audit chain
10. Network pinning service pins new_commit's reachable blocks; AttributionRecords emitted (§5)
11. Proposer's bond refunded; other nodes see the new tip on next resolve

4. Joint build / test + reproducibility

4.1 Build as a signed WorkOrder `[NEW, reuses ComputeBackend seam]`

A build/test run is expressed as the existing ComputeBackend WorkOrder and returns a BackendReceipt — "the seam moves computation, never authority." GM adds the build-specific payload:

BuildWorkOrder:                    # a ComputeBackend WorkOrder, node-signed
  commit: "bafy…"                  # exact state to build (content-addressed → reproducible)
  target: "app/osx/hinetd"         # subtree / build target
  toolchain_lock: "bafy…"          # pinned toolchain manifest (compiler, deps, all by CID)
  inputs_root: "bafy…"             # closure of build inputs (source + deps), all content-addressed
  sandbox: {network: "none", fs: "readonly-inputs", cpu_arch: "arm64"}   # hermetic

BuildReceipt:                      # a verified BackendReceipt
  id: "brc_7a…"
  build_workorder_hash: "…"
  builder_node: "icore_gh78…"
  outputs_root: "bafy…"            # CID of produced artifacts (deterministic ⇒ stable CID)
  test_summary: {passed: 412, failed: 0, suite_cid: "bafy…"}
  status: "success"                # success | build_fail | test_fail
  toolchain_hash: "…"
  duration_ms: 51230
  sig: {scheme: "ed25519", node_id: "icore_gh78…", value: "…"}

4.2 Reproducibility & build consensus `[NEW]`

Determinism: every input (source, toolchain, deps) is content-addressed; the sandbox is hermetic (no network, read-only inputs, pinned arch). Same inputs_root + toolchain_lock ⇒ same outputs_root CID. This is the code analogue of "same inputs CID → same output CID."
Cross-builder consensus (merge gate): require_reproducible_build demands N independent builders produce byte-identical outputs_root — this is exactly the aCore exact-consensus mode (deterministic duty), so build receipts feed the ThoughtConvergence cluster; disagreement ⇒ a builder is faulty/lying (poisoning) → flagged, not merged.
[MVP] 1 network builder (Quorumz-GCP HiNet resource) as a trusted gate.
[LATER] N-of-M builder quorum with reproducibility cross-check + slashing; [LATER] TEE-attested builds (Tier 3) and [LATER] zk build proofs (Tier 5) from the Technical Spec's verification tiers.
Toolchain pinning: a Nix-style / content-addressed dependency closure [MVP: a lockfile of CIDs; LATER: full Nix-derivation closure].

4.3 Flow B — CI/build gate (text sequence) `[NEW]`

1. On a new Proposal revision, coordinator emits a BuildWorkOrder for each affected target
2. Builder node(s) fetch commit + inputs_root by CID (bitswap), run hermetically in sandbox
3. Each emits a signed BuildReceipt (outputs_root CID + test summary)
4. ThoughtConvergence clusters receipts by exact outputs_root match (+ test pass)
   - MVP: 1 builder, status must be success
   - LATER: N-of-M identical outputs_root  → reproducible; else quorum flags nondeterminism
5. Passing receipt(s) attach to the Proposal; satisfy governance.require_reproducible_build
6. outputs_root artifacts are pinned + become the canonical build for that commit (cacheable by CID)

5. Incentives / attribution + provenance

5.1 Provenance is intrinsic (the DAG is the ledger) `[NEW]`

Provenance needs no side-channel: the commit DAG is an immutable Merkle history where every commit is Ed25519-signed by a registered node (§3.1) and every merge is quorum-signed (§3.4). git blame over the DAG yields line/subtree-level attribution to node_id → owner. Because CIDs are global, provenance is verifiable by anyone without trusting the registry (the registry only orders refs; the content self-authenticates).

AttributionRecord:                 # emitted at merge; the unit of the economy split
  commit: "bafy…"
  merged_into: "refs/heads/main@seq=42"
  contributions:                   # blame-derived, weighted
    - node_id: "icore_ab12…"   role: "author"     weight: 0.70   lines: 214
    - node_id: "icore_cd34…"   role: "reviewer"   weight: 0.15
    - node_id: "icore_gh78…"   role: "builder"    weight: 0.05
    - node_id: "icore_root1…"  role: "maintainer" weight: 0.10
  membrane: "public"               # public → attributable+payable; icorp:* → paid VIA the iCorp
  audit_event_id: "audit_…"

5.2 Ties to the existing audit chain `[EXISTS + extended]`

Each node already keeps a tamper-evident hash-chain (audit.py, content-free prev→hash sha256, cross-thread + cross-process flock-serialized [EXISTS]). GM adds event types — repo.proposal.created, repo.review.submitted, repo.build.completed, repo.merge.applied, repo.ref.updated — each carrying only CIDs/ids (content-free, consistent with the chain's design). The RefRegistry keeps its own analogous chain over RefUpdates so the global ref history is tamper-evident too. This makes "who did what, authorized by which consent grant" auditable end-to-end — the Technical Spec's verifiable execution path principle.

5.3 Economy hooks `[SPEC dependency → §6A/§6B, P-F]`

Contribution is income-producing, on the same rails as intelligence usage:

Work payouts: authoring, reviewing, building, and maintaining a merged change split a merge reward by AttributionRecord.weight (minus platform share, §6A). Reviewers/builders earn like network service providers.
Usage royalties (the real value): when merged code is used — a module invoked in a served qCore path, an artifact downloaded, a released package consumed, or a monetized aCore built from it — usage-metered attribution receipts flow to the historical contributors of the invoked subtrees (pro-rata by blame weight, decaying with edits). This is the §6A "you get paid when your intelligence serves the network" rule, applied to code that serves the network.
Bounties/escrow: an Issue may escrow a reward; the MergeDecision that closes it releases payment to the contributor [LATER].
Settlement: [MVP] log attribution + reward events locally (no token issuance) — matching the Functional Spec's MVP stance ("log contribution events; defer settlement"); [LATER] real metering + micropayment split (P-F3).

5.4 Membrane & lease rules for contributions `[NEW, from §6B]`

Public GM: contributions are individually attributed + paid to the contributing iCore/owner.
iCorp GM overlay (§9): a leased iCore contributing to an icorp:* subtree contributes as part of the iCorp; on employment exit, the iCore leaves but its committed code stays in the iCorp's monorepo (identical to "intelligence contributed remains in the iCorp's model," §6B). iCorp code answers/earns as the iCorp; internal iCores are neither referenced nor paid individually externally, honoring the membrane.

6. Relation to the dev-agent (a developer's iCore in dev-mode)

The GM is the natural extension of the standalone laptop iCore's dev value (P-A / PA-2): "a LOCAL coding agent that knows your code." Today dev_tools.py [EXISTS] is read-only + repo-confined (list_dir, read_file, search_code, realpath-jailed to one project_root, no writes, no exec). GM graduates dev-mode from read-only to consent-gated contribution, staying inside the same confinement + consent model.

6.1 New dev-agent tools `[NEW]` (consent-gated, extend `dev_tools.py`)

Tool	Action	Gate
`checkout_ref(ref, path?)`	sparse-checkout a GM subtree into a confined working root	consent: `repo_read`
`write_file(path, content)`	edit a blob in the working root (jailed like `_safe()`)	consent: `repo_write` (local only)
`run_tests(target)`	run the hermetic build/test locally (dry-run of §4)	consent: `repo_build`
`propose_change(target_ref, message)`	build Tree+Commit, sign with the node key, submit a Proposal	consent: `repo_contribute` + human approval
`review_proposal(prop_id, verdict)`	drive the coding root over a diff, submit a signed Review	consent: `repo_review`

These are the code analogues of the vault's allowed_uses (ingest|rag|delta_train|agent_read|agent_write [EXISTS] in consent.py); GM adds repo_read|repo_write|repo_build|repo_contribute|repo_review to the same ConsentGrant machinery — "no data (or code) leaves without a live grant." propose_change (the only network-egress action) additionally requires explicit human approval (requires_human_approval), so an autonomous dev-agent can draft + test freely but a human signs off before a signed commit leaves the node.

6.2 New hinetd endpoints `[NEW]` (alongside existing `/v1`, `/v1/agent`, `/node/*`)

POST /repo/checkout        {ref, path?}                 → materialize a confined working subtree
POST /repo/propose         {target_ref, message}        → build+sign Commit, submit Proposal  (approval-gated)
GET  /repo/proposals       ?scope=&membrane=            → list (competence-routed to me as reviewer)
POST /repo/proposals/{id}/review   {verdict, comments}  → signed Review
POST /repo/build           {commit, target}             → BuildWorkOrder → BuildReceipt
GET  /repo/blame           ?path=&ref=                  → attribution graph (who wrote what)
GET  /repo/object/{cid}                                 → fetch a block (bitswap-backed)

Central (registry / coordinator, Quorumz-GCP HiNet resources):

GET  /registry/nodes/{node_id}          → pubkey, capabilities, iCorp binding  (P-I)
GET  /refs/{ref}                          → {commit_cid, seq, sig}
POST /refs/{ref}   {RefUpdate, sig}       → monotonic signed ref update (governance-checked)
POST /coordinator/merge  {MergeDecision}  → verify quorum, apply RefUpdate, emit AttributionRecords

6.3 Dogfooding

The GM's first and canonical content is HiNet itself — hinetd, the connectors, the harness (the "OURS" harness of P-K), the specs. The network builds the network: a developer's iCore in dev-mode contributes to the very substrate it runs on. This is the tightest possible loop between P-A (standalone value now) and P-K (network value later).

7. Concrete tech choices + trade-offs

Concern	Choice `[MVP]`	Alternatives / `[LATER]`	Trade-off
Object encoding	IPLD `dag-cbor`, CIDv1, `sha2-256`	git pack + `git-remote-ipfs`	dag-cbor = native IPFS traversal, verifiable links; git-compat bridge deferred
Block store / transport	IPFS + libp2p bitswap (Helia/Kubo)	—	Aligns with Technical Spec's stated libp2p/Helia direction; availability needs pinning
Availability	Central pinning service (own GCP resources)	iCore-Prime pin providers; Filecoin/Storj deals	Central MVP is simple; Prime pinning is the decentralization + network-effect path
Permanent releases	Pin	Arweave tagged releases	Arweave = pay-once permanence for tagged artifacts; overkill for every commit
Mutable refs	Registry-anchored signed monotonic refs	IPNS+pubsub; on-chain anchor	Central anchor stores only pointers (content decentralized); trustless refs deferred
Code merge	git 3-way	—	Mature, deterministic on text
Structured merge	Automerge CRDT	—	Conflict-free for config/lockfiles; listed in Technical Spec
Contributor sig	Ed25519 (node key, P-I)	—	Matches the whole HiNet identity stack
Merge/build consensus	Single maintainer + 1 builder	BLS threshold quorum + N-of-M reproducible builders + TEE/zk	Reuses aCore `ThresholdSignedOutput`; scales trust later
Build hermeticity	Sandboxed, no-network, pinned toolchain lockfile	Full Nix closure; TEE	Good-enough reproducibility MVP; hardened later
Identity/registry	Central registry (P-I)	DHT / on-chain	Central now → decentralized index later (P-I's own plan)

8. Threat model

Threat	Vector	Mitigation
Spam proposals	Cheap PRs flood the coordinator + bloat pinned storage	Only registered (Ed25519) nodes may propose; per-node rate limit (`governance.max_proposal_rate`); refundable bond pin; open proposals pinned by proposer, not the network; nothing merges without maintainer/quorum approval
Malicious code merged	Backdoor slips past review	Mandatory maintainer quorum + `min_reviewers_by_sensitivity`; competence-routed reviewers; security-sensitivity paths need 2+ reviewers; full signed audit trail for post-hoc accountability + revert
Build poisoning	A builder returns a lying `outputs_root` (malware artifact ≠ source)	Reproducible cross-builder consensus (N-of-M identical `outputs_root`) catches divergence; `[LATER]` TEE attestation / zk build proof; hermetic sandbox (no network exfil during build)
Untrusted code executes on my node	Reviewing/building runs attacker code	Hermetic sandbox (no network, read-only inputs) — the Technical Spec's "isolate untrusted agent execution" rule; dev-agent review is static (read/search) by default, execution only in sandbox
Sybil / governance capture	Fake nodes gain maintainer majority	Registry identity + stake/reputation weighting `[LATER]`; iCorp subtrees gated to iCorp membership; root-governance changes need the highest threshold; maintainers added only by existing-maintainer quorum
Ref rollback / equivocation	Anchor serves an old/forked tip	Monotonic `seq` + signed `RefUpdate`s appended to a tamper-evident chain; clients reject non-increasing seq; `[LATER]` IPNS/on-chain mirror for cross-checking the central anchor
Supply-chain (deps)	Compromised dependency pulled in	All deps content-addressed + pinned in `toolchain_lock`/`inputs_root`; a dep change = a reviewable diff; hermetic closure
Secret exfiltration in a build	Build phones home with a stolen token	No-network sandbox; no secrets mounted into builds; artifacts are pure functions of pinned inputs
Storage DoS / griefing	Pin garbage, exhaust the pinning service	Network pins only merged, reachable blocks; proposals bonded; GC of unmerged/abandoned proposals after TTL
Membrane leak	iCorp-private code exposed publicly	iCorp overlay is a separate encrypted namespace (§9); public RefRegistry never indexes `icorp:*`; enforced at the coordinator + pinning ACL
Key compromise	Stolen node key forges commits	Registry revocation + key-rotation (P-I signed lifecycle); post-revocation signatures rejected; audit chain bounds the blast radius

9. iCorp private monorepo overlay `[NEW, from §6B membranes]` `[LATER]`

An iCorp builds its own sovereign codebase behind its membrane. Implemented as an overlay namespace on the same object model:

Namespace: icorp:<id> refs live in a membrane-gated RefRegistry partition; blocks are encrypted-at-rest and pinned only to iCorp-owned + consented pin targets (reuse VaultReplication's ciphertext-to-owner-targets discipline — GM's private sibling).
Visibility (two/three views, §4 of Vision): a public netizen never sees icorp:*; an iCorp member sees the full workspace. Enforced at coordinator + pinning ACL, keyed by registry iCorp binding.
Streamlined path: because the member set is known, iCorp merge governance can be lighter-weight than the open network (Vision §6) — e.g. 1 maintainer + membership.
Lease on exit: §5.4 — code stays with the iCorp; the iCore leaves.
Externalization: an iCorp may publish a subtree into the public GM (a governed cross-membrane merge), after which it earns as the iCorp unit.

10. What exists vs new · MVP vs later (rollup)

Reuse directly ([EXISTS]): audit hash-chain (audit.py), consent gate + ConsentGrant/allowed_uses (consent.py), vault content-hashing + make_id/compute_content_hash (canonical.py), read-only repo-confined dev tools + _safe() jail (dev_tools.py), /v1/agent tool-loop + coding root, the lazily-wired node singleton (node.py).

Reuse by design ([SPEC], consume don't rebuild): Ed25519 node identity + registry (P-I), ComputeBackend WorkOrder/BackendReceipt seam, VaultReplication decentralized-FS targets, aCore ThresholdSignedOutput + ThoughtConvergence, competence-signature router (P-J), economy split (§6A/§6B, P-F), membranes/iCorp/lease (Vision).

New in this spec ([NEW]): GM IPLD object model (Blob/Tree/Commit → CID), registry-anchored monotonic signed refs, Proposal/Review/MergeDecision/GovernanceDoc, reproducible BuildWorkOrder/BuildReceipt consensus, AttributionRecord + usage-royalty hooks, dev-agent contribution tools + /repo/* endpoints, iCorp overlay namespace.

MVP scope [MVP]: dag-cbor objects on IPFS with a central pinning service; central registry-anchored signed refs (monotonic, audit-chained); Ed25519-signed proposals; single-maintainer + single-builder merge gate; git 3-way + Automerge conflict handling; consent-gated checkout/propose/review dev tools with human approval on egress; local attribution + reward logging (no settlement); public GM only; HiNet's own code as first content.

Later [LATER]: BLS threshold merge quorums; N-of-M reproducible-build consensus + slashing; TEE/zk build proofs; IPNS/DHT/on-chain ref mirrors; iCorp private overlay; real metering/micropayment settlement + bounties; iCore-Prime pin/build providers; full Nix build closures; git-compat bridge.

11. Open decisions (flagged)

Ref anchor trust vs latency: stay central longer (simple, fast) vs invest early in IPNS/on-chain (trustless, slower). Leaning central-MVP per P-I.
Attribution weighting formula: author/reviewer/builder/maintainer split ratios + edit-decay of usage royalties — needs an economic model + anti-gaming analysis (e.g. trivial-commit farming).
Reproducibility depth for MVP: lockfile-of-CIDs vs full Nix derivation closure — how hermetic is "hermetic enough" before N-of-M cross-check exists?
Monorepo scale: one global root Tree vs federated roots per domain stitched by submodule CIDs, once the DAG is huge (checkout/blame cost).
Bond/stake currency pre-token: what backs the anti-spam bond before settlement exists (reputation-only? off-chain credit?).
Reviewer incentive integrity: paying reviewers risks rubber-stamping; needs a quality/dissent signal (tie to ThoughtConvergence dissent records + reputation slashing).
iCorp externalization licensing: legal/attribution semantics when membrane-internal code crosses into the public GM (who is credited/paid, under what license).
GC policy for abandoned proposals: TTL + bond forfeiture rules vs preserving a permanent proposal record.
Base layer choice for permanence: IPFS-pinning vs Arweave vs Filecoin for tagged releases specifically — durability SLA vs cost.

Next: Onboarding & agent harness → · All documentation →

HiNet — Decentralized Grand Monorepo (GM)

0. One-paragraph thesis

1. Where this sits in the HiNet stack

2. Storage — a git-like content-addressed model on a decentralized FS

2.1 Object model (git objects → IPLD DAG nodes) [NEW]

2.2 On-FS layout [NEW]

2.3 Mutable pointers — the hard part [NEW]

2.4 Clone / checkout / sparse [NEW]

3. Contribution model — propose · review · merge · govern

3.1 Identity of a contributor [SPEC dependency → P-I]

3.2 The Proposal object (a signed "PR") [NEW]

3.3 Review [NEW]

3.4 Governance — who can merge [NEW]

3.5 Conflict resolution [NEW]

3.6 Flow A — propose → review → merge (text sequence) [NEW / MVP]