#FrankenGit

A clean-room, pure-Rust, Git-compatible forge designed for humans, autonomous coding agents, extreme scale, and independently verifiable recovery.

Status: active implementation and pre-release integration (spec-first design, transitioning from pre-implementation). FrankenGit now contains substantial final-abstraction slices and a narrow executable one-node boundary, but it is not yet a general-purpose Git server, a production-ready forge, or a GitHub replacement.

License: LicenseRef-MIT-OpenAI-Anthropic-Rider — the MIT licence plus the OpenAI/Anthropic rider. Decision D14 was resolved by the repository owner on 2026-08-23.

Because that rider withholds rights from named parties, the licence is not OSI-approved open source; the repository is source-available and must be described that way. See docs/LICENSING_DECISION.md.

Normative contract: docs/NORMATIVE_PROTOCOL_CONTRACTS.md governs identity, admission, publication, authority, cancellation, repair, and release-blocking invariants.

FrankenGit is not “GitHub rewritten in Rust.” It is a forge designed around a different center of gravity:

• one immutable repository decision stream and one tiny conditional authority head, rather than a mutable bare repository plus a separately authoritative product database;
• a production implementation that is pure Rust, strictly memory-safe in first-party code, and never links or invokes C Git, libgit2, or another Git engine;
• parallel, per-core preparation and microbatched publication instead of forcing expensive work through one repository process;
• Git-object-aware adaptive transport, sparse semantic workspaces, typed graph fabrics, evidence-carrying agent changes, and locally reproducible releases;
• repair, checkpoints, indexes, policy promotion, and release publication that all follow the same body-first/root-last, anti-rollback discipline.

The project is a synthesis of concrete machinery from Asupersync, FrankenSQLite, FrankenFS, FrankenSearch, franken_markdown, FrankenGraphDB, FrankenNetworkX, and Doodlestein Self-Releaser — with the gateway/API on fastapi_rust, projection read-models on sqlmodel_rust's FrankenSQLite backend, a familiar GitHub-like web UI (DOM-oriented pure-Rust/WASM, Leptos or Dioxus with SSR and Tailwind, native source-spanned rendering and trustless verified reads; a generated TypeScript client and React reference are the supported alternative), plus a terminal TUI (and an optional parallel terminal-style web surface) on the frankentui (ftui) kernel — combined with the object-store-native insight in Cursor’s “Git at Any Scale.” The detailed source-to-design map is in docs/FRANKEN_SUITE_DEEP_DIVE_SYNTHESIS.md; the concrete defects found in the first-cut architecture and their dispositions are in docs/FRANKENSUITE_DEEP_AUDIT_2026-08-19.md.

Those product-stack choices are settled, while integration is deliberately gated on their owned sibling repositories converging to one Asupersync 0.4.x constellation and registry-resolvable FrankenSQLite dependencies. The exact runtime, cancellation, connection, retry, shutdown, and verification contract is in docs/ASUPERSYNC_AND_FRANKENSQLITE_INTEGRATION_PROFILE.md.

#Current one-node integration boundary

The checked-in fgit-cli library contains a narrow, configuration-free one-node surface for exercising the same authority, admission, and object-selection abstractions the finished system will use. It does not consult a configuration file: callers supply the storage directory, tenant ID, and repository ID explicitly. The final fg binary exposes this surface: the CliOutcome::At rendering arm (missing at the 2026-08-25 snapshot, repaired in 0f6a81b7) is landed, and cargo check -p fgit-cli --all-targets passes at the current revision. The surface remains an implementation and conformance boundary rather than a complete server profile, and it will not by itself prove that a selected durability epoch or broader compatibility matrix has completed.

cargo run -p fgit-cli -- init ./fgit-data \
  11111111111111111111111111111111 \
  22222222222222222222222222222222

cargo run -p fgit-cli -- doctor ./fgit-data \
  11111111111111111111111111111111 \
  22222222222222222222222222222222

init creates or re-authenticates the empty canonical authority head. import verifies a bounded local object source composed of loose objects and checksum-bound idx-v2/pack-v2 pairs, then publishes its source refs through the sealed admission/RCR/head-CAS path. The pack-import focused integration target is checked in and all 17 cases — the original 14 plus the resource-bound expansion — pass in a local run at e296eb3f; orchestrated batch verification remains the revision-bound gate. The verified-read defect that previously kept the wider node package gate red was fixed in 7ccaf8b (layout-selected ref roots), and the whole fgit-node target set passes locally at that revision. doctor authenticates the head and can re-verify one explicitly named native object; it is not yet a complete replay, fabric, repair, or causal-diagnosis suite. export writes an authority-selected pack to a previously absent path. One emitted pack is bounded by the documented write-side envelope (--pack-max-expanded-mib; 128 MiB expanded by default), and an over-envelope clone receives a diagnosable Fatal sideband refusal rather than an unexplained early EOF.

serve accepts a bounded raw git-daemon service run, drains every admitted session, and reports accepted/completed/refused counts before it exits. The upload-pack lane is enabled by default. The receive-pack lane is available only when the operator explicitly supplies --receive-principal <principal-id-hex>; without that binding, a push is refused and publishes nothing. Receive-pack reuses the bounded framing, quarantine, validation, policy, sealed-admission, and exact-predecessor authority-CAS path rather than making socket-local refs authoritative. Its compatibility default remains one session and one in-flight client; callers explicitly opt into larger non-zero --max-sessions and --max-in-flight bounds. The bring-up transcript below deliberately names the one-session bound. One pushed pack is bounded by the documented receive session envelope — size ceilings (--receive-max-input-mib, --receive-max-expanded-mib) and a work-proportional session budget, base + admitted bytes x rate clamped to a hard ceiling (--session-timeout-secs, --session-secs-per-mib, --session-max-extension-secs) — and an over-budget verdict is delivered through report-status, never a silent hangup (see docs/GIT_COMPATIBILITY_MATRIX.md). Ingress time cannot consume the independent server-work budget that starts after the pack trailer. Smart HTTP, production SSH, and a native API are still absent. Ordinary production push over authenticated transports remains unsupported; the raw git-daemon receive lane is the composition slice the first_push.sh E2E suite exercises with a real git client. No command treats local object placement, a routing hint, or a connection-local ref map as canonical state.

scripts/one_node_bringup.sh exercises the intended empty-repository lifecycle end to end — verified at be60ac19, completing in about 40 s — with a new empty storage directory, an unused loopback address, and an absent export path:

scripts/one_node_bringup.sh "$(mktemp -d)" \
  11111111111111111111111111111111 \
  22222222222222222222222222222222 \
  127.0.0.1:9418 \
  /tmp/frankengit-one-node.pack

The script records the exact fg init → fg doctor → one explicitly bounded fg serve session → fg export commands and their observed output in bring-up.transcript below the supplied storage directory. Set FG_BIN to a prebuilt fg binary to avoid its default cargo run -p fgit-cli -- launcher. It intentionally exercises an empty repository and does not claim the full Git compatibility matrix. The non-empty clone campaign is pinned by first_clone.sh; the raw receive campaign is pinned separately by first_push.sh, including the disabled-by-default refusal twin, initial and incremental pushes, retry behavior, and clone-back identity.

#Repository-side agent triage

The checked-in scripts/bv_compat.sh launcher is an operational compatibility surface, not part of the future fgit-agent product plane. It gives pinned bv versions a complete read-only graph by projecting the repository-owned batch_pending state to non-claimable review in a private temporary file, then verifies that the authoritative tracker hash did not change. Graph scores remain advisory: an agent may claim a bead only when the exact ID appears in br ready --unassigned --no-db --json.

#Reality snapshot: 2026-09-07

FrankenGit has a working bounded Git node and substantial subsystem code; the integrated forge, agent service, hosted backend and release product are still incomplete. The reality check and bridge plan binds its broad source and runtime assessment to b74b666dc644c6ed18697f3950690bf289c33114. Subsequent bridge results below name their own revisions and do not replace an independent batch gate.

• The canonical core has real typed identities, seals, intent/effect folding, immutable decisions, authenticated heads and exact-predecessor CAS. The embedded node uses the admitted published FrankenSQLite/runtime stack.
• The clean-room Git substrate includes owned object, DEFLATE, pack/delta, pkt-line, upload-pack, receive-pack, quarantine and loose/packed import implementations. At the assessed revision, selected real-node E2E suites exercised nonempty clone, raw push, historical state, incremental fetch and SHA-256 repository behavior: 178 acceptance IDs across five suites. The report distinguishes ordinary-client observations from pinned-oracle conformance and records the exact limits. This is not the full Git matrix.
• The dated snapshot found durable forge merge blocked in the production composition: OneNode::admit_merge_durable_in reached materializer methods that returned DurabilityProfileUnavailable before publication. The six synchronous admission race tests cited in the previous snapshot do not establish a durable OneNode merge. The subsequent frankengit-asa3 implementation couples the actual merge event, forge position, and canonical outbox state at one authority CAS, with an authenticated delivery reader and persisted reconciliation worker. Native packages through the original sealed API now enter that same driver with their original transaction identity and node-owned object revalidation. Node-owned TreeFS sessions additionally bind real edits, exported trees, and interrupted-request recovery to the admitted workspace snapshot. Admission and node all-target tests passed through RCH at 55e1da66626c014202eee91f9282b251594c91f4, including actual authority races, process-death recovery and outbox delivery. Independent batch verification remains outstanding. Historical Digest-valued packages retain the unavailable legacy route. Exact execution evidence and scope are in the delivery contract; this focused result does not establish a complete forge or release gate.
• fg at has a real historical path and a nonempty durable-history E2E scenario in scripts/e2e/suites/node/time_travel.sh. The 2026-09-07 assessment exercised its 15 acceptance IDs, including both diff endpoints and an ahead-of-authority refusal. Capsule checkpoints and positions inside multi-decision batches remain outside that scenario.
• TreeFS now has a Linux sparse-directory implementation candidate in fgit-runner, connected to authority-selected objects by OneNode::sparse_workspace_manifest_in. It materializes actual files, imports declared tool outputs as ordinary edit intents, and explicitly closes or reports containment. The runner and node focused tests passed at 875fd14b3e79887b07d692e198531fbe810df640; their new cases include real tool editing, disk object export/reopen and fresh-process node recovery. ADR-0017 records the candidate profile and dependency boundary. Independent host-profile acceptance, public agent execution and the optional FUSE adapter remain outstanding.
• fgit-projection implements derived identity/watermark/applied-decision infrastructure using sqlmodel 0.4.2. User-facing issue/PR/search read models and the remaining outcome/close/retry acceptance are still unfinished. The previous snapshot's eight-error sqlmodel feature blocker is historical; the assessed constitution command exited zero, with a separate native build-evidence discovery defect described in the report.
• The native-linkage checker now recognizes the pinned nightly's build output layout and binds observations to package build instances. Its 105 focused tests passed at e8dbdf17fba5b0e29341e3e966e20e8f2babdd77. The new real-build positive/negative E2E still requires independent batch execution. Cached build observations are not fresh release attestations.
• Object fabric, ATP-Git, repair, verified reads, graph algorithms and agent protocols have bounded implementations. Live HTTPS object-store authority, authenticated Git transports, complete agent persistence/collectors/effects, hostile-code isolation, REST/MCP, search, UI and actual release publication remain product gaps. A trusted local process is not a hostile runner.
• The assessed workspace test command exited zero with 4,590 passed and 24 ignored. The canonical fast lane failed formatting and a separate Clippy run failed; full and release exited 3 with explicit dormancy. Those historical results do not assert gate status for later bridge code.
• Plan §4.2.1 records the unresolved merge-queue/package 1.0 scope contradiction and its owner decision boundary. The settled D14 licence remains LicenseRef-MIT-OpenAI-Anthropic-Rider; it is not OSI-approved open source.

The claims registry remains the public proof boundary. Its verified rows cover narrow artifact identity and contained Lean-model theorems; they do not prove general Git compatibility, Rust refinement of the complete implementation, forge completeness, multi-region readiness, performance leadership, or release readiness. Closed beads, crate count, test presence, and a successful local scenario will not be treated as substitutes for revision-bound evidence.

---

#TL;DR

#The problem

A conventional forge accumulates several partially authoritative systems:

• refs and objects inside mutable repository directories;
• issues, pull requests, protections, and queues inside a database;
• CI, artifacts, packages, search, graph, and notifications in separate services;
• caches and replicas with different notions of freshness;
• agents operating through human-shaped APIs and overly broad tokens;
• release systems whose “truth” is a remote workflow status and a mutable asset page.

At agent scale, the waste compounds: hundreds of workers clone or hydrate the same repository, assemble overlapping context, rerun overlapping work, produce ambiguous retries, and retain enormous derived state.

#The proposed solution

For each repository, FrankenGit defines canonical truth as:

1. immutable Git objects and immutable internal records;
2. immutable transaction seals and prepared evidence capsules;
3. an immutable sequence of RepositoryDecisionBatch objects;
4. one small authenticated RepositoryAuthorityHead selected by a linearizable conditional compare-and-swap.

A mutation becomes canonical only when the exact predecessor head is conditionally replaced. Any execution cell can prepare or attempt publication. Rendezvous routing, local caches, per-core lanes, and commit combiners make the healthy path fast but never become authority.

Everything else is rebuildable: bare repositories, packs, MIDX, bitmaps, commit graphs, FrankenSQLite read models, issue/PR tables, search/vector/graph generations, CI workspaces, dashboards, counters, and notification feeds.

---

#The architecture in one diagram

Git clients / humans / agents / CI / mirrors
                    |
          pure-Rust Git/API gateways
                    |
          stateless execution cells
          /         |          \
 per-core prep   local MVCC   immutable bodies
 lanes/combiner  and caches   and segments
          \         |          /
             AuthorityStore
        conditional repository-head CAS
                    |
      immutable repository decision stream
                    |
     materializers / forge projections /
     search / typed graphs / repair / CI

The one strong operation is deliberately small:

compare_exchange(
  repository_head_key,
  exact_predecessor_version_token,
  canonical_new_head_bytes
)

A backend is not trusted because it calls itself “S3-compatible.” It must pass the AuthorityStore conformance and fault suite, including ABA, ambiguous-response, proxy, failover, lifecycle, and version-token behavior.

The single-node profile implements the same authority interface with FrankenSQLite. Clustered deployments may use a conforming object store or a future small pure-Rust fgit-authorityd. Product semantics do not change with the backend.

---

#Core innovations

#1. Repository decisions, not a database/repository split

A successful repository mutation publishes one RepositoryCommitRecord binding:

• exact ref effects and resulting authenticated ref root;
• exact admitted Git object closure;
• exact forge-event batch and resulting forge-position root;
• policy input, decision, and evidence roots;
• retention and outbox effects;
• conflict, verifier, and resource receipts.

A merged PR cannot reach a state where the target ref moved but the PR remains open, or vice versa. Both effects belong to one committed record and one authority-head transition.

A RepositoryDecisionBatch may include many ordered terminal decisions and committed records. Refusals receive decision order for audit/idempotency but do not pretend to advance source history.

#2. Stable retry identity and immutable outcomes

A network attempt and a logical mutation are distinct. Ingress seals one canonical semantic request under one stable transaction identity. Reusing the idempotency key with different semantics fails closed.

After sealing, the transaction eventually has one terminal result:

• committed repository record; or
• canonical typed refusal.

Connection loss and cancellation are never reported as proof of non-commit. The client queries the authenticated outcome index by transaction identity.

#3. Per-core preparation and group publication

Object validation, policy-independent analysis, graph/search work, tests, semantic effect construction, and witness generation run in parallel. Per-core append-only lanes avoid central hot locks and allocator traffic. A flat combiner:

1. gathers a bounded microbatch;
2. constructs the transaction conflict graph;
3. chooses a deterministic admissible order;
4. evaluates intents against scratch state;
5. emits target-disjoint net effects;
6. stages one decision batch and candidate head;
7. attempts one conditional head replacement.

CAS losers do not discard all expensive work. They revalidate coarse witnesses, refine them only when the expected saved retry cost exceeds bounded refinement cost, deterministically rebase safe semantic intents, and retry the same sealed transaction.

“Different refs” is not automatically independence: branch protection, merge queues, quotas, retention, policy epochs, and forge aggregates can overlap even when ref strings do not.

#4. ATP-Git: transport the object graph, not just a file

Asupersync’s Adaptive Transport Protocol becomes FrankenGit’s native internal and aware-client transport profile. ATP-Git can use:

• exact and bounded probabilistic receiver have-sets;
• Git object/segment/pack delta plans;
• unique-byte deduplication with deterministic reconstruction;
• typed path graphs across direct, LAN, IPv6, tunnel, relay, mailbox, or other policy-approved paths;
• bounded multipath racing with loser cancellation and drain;
• swarm rarity and peer-availability scheduling;
• endgame duplicate requests;
• adaptive RaptorQ overhead and pacing;
• trust-scoped caches and peer evidence;
• complete deterministic transfer receipts.

It accelerates internal replication, agent/CI inputs, migration, repair, artifacts, and FrankenGit-aware clone/fetch. Ordinary Git clients still receive standards-compatible smart-HTTP/SSH streams from the pure-Rust Git engine. ATP-Git never changes native Git object identity or semantics.

See docs/ATP_GIT_PROFILE.md.

#5. Git TreeFS: a million workspaces without a million clones

An agent or CI job opens:

• an immutable Git tree/object base pinned to an exact repository state;
• a sparse, capability-scoped copy-on-write semantic overlay;
• lazy authorized object reads;
• typed edit intents and source-span lineage;
• explicit staged, visible, and durable output epochs.

The reference interface is a direct Rust API. Sparse-directory and FrankenFS/FUSE adapters support ordinary tools. Export produces exact Git objects plus a proposed repository transaction; the workspace never gains publication authority merely because a file exists locally.

See docs/GIT_TREE_FS.md.

#6. Typed graph fabrics, not one opaque “knowledge graph”

FrankenGit maintains separate graphs for:

• commit ancestry and object reachability;
• files, symbols, calls, imports, and dependencies;
• ownership and review history;
• builds, checks, artifacts, and provenance;
• agents, tasks, capabilities, and evidence;
• object placement, failure domains, repair, and retention;
• federation and trust observations.

Exact, deterministic-derived, and statistical edges have different types and authority limits. Graph algorithms that can influence reviewer assignment, build order, context assembly, merge planning, placement, or risk declare an observable tie-break policy and emit a decision-path/complexity witness.

The algorithm palette includes reachability, SCC/condensation, dominators, bridges/articulation, shortest and k-shortest paths, matching, min-cost flow, max-flow/min-cut, topological/critical path, transitive reduction, centrality, community/k-core, and dynamic graph maintenance.

See docs/GRAPH_INTELLIGENCE_ARCHITECTURE.md.

#7. CALM classification and obligation-typed side effects

Every operation is classified as:

• monotone/coordination-free;
• bounded commutative;
• coordinated.

Append-only immutable objects, evidence, and some social events can propagate without global coordination. Refs, authorization, retention, billing, merge queues, and destructive transitions require ordered authority.

Every side effect that acquires responsibility creates an obligation: object placement, authority-CAS attempt, secret lease, runner allocation, outbox delivery, workspace output, repair, context fetch, or billing reserve. An obligation must commit, abort, transfer, or drain before its Asupersync region closes. “Fire and forget” is not a valid state.

See docs/CALM_AND_OBLIGATIONS.md.

#8. Repair is an authority-governed mutation

RaptorQ and replicas may reconstruct bytes, but decoder success is not acceptance. Recovered bytes must verify their original length, digest, internal/Git/LFS/package identity, manifest/Merkle closure, tenant namespace, and structural codec.

A verified repair then revalidates the current placement/retention authority before publishing. A repair prepared against stale state cannot overwrite a newer placement or resurrect deleted data.

RaptorQ applies only to registered immutable classes where coding wins against simpler replicas. It is not consensus, cryptographic integrity, authorization, or current metadata.

See docs/RAPTORQ_PERMEATION_MAP.md.

#9. Identity-bound conformal/e-process policy

Conformal bounds, e-processes/e-martingales, no-regret controllers, off-policy evaluation, changepoint detection, Beta posteriors, and Lyapunov/progress governors may adapt bounded operational policies such as:

• ATP path/block/repair parameters;
• cache and prefetch budgets;
• scrub/repair priority;
• search/rerank/context budgets;
• witness-refinement and retry policy;
• reversible admission throttles;
• canary escalation and resource allocation.

The evidence identity includes metric, population, selection rule, exact sequence window, regime epoch, candidate/fallback policy, assumptions, and numeric/toolchain fingerprint. Insufficient support or regime shift selects the deterministic fallback.

Statistics never decide Git identity, signatures, authorization, ref atomicity, retention roots, whether committed data exists, or irreversible punishment.

#10. Local, root-last releases through DSR

FrankenGit does not depend on GitHub-hosted Actions. Repository-owned commands define verification. Workflow YAML is a thin portable adapter executed locally through Doodlestein Self-Releaser/act, with macOS and Windows lanes on registered native hosts.

A release is authoritative only after the complete target matrix, exact asset set, checksum sidecars, SBOM, provenance, signatures, installer/extraction/version/smoke tests, and verification evidence pass. The signed local release manifest is published last. GitHub Releases is reconciled as a distribution mirror.

See docs/LOCAL_VERIFICATION_AND_RELEASE_PIPELINE.md.

---

#Beyond parity: what the architecture unlocks

The core innovations above are intended to make FrankenGit a correct, economical forge. The same primitives — one authenticated head, an immutable decision stream, content-addressed evidence, and pinned build capsules — will also unlock five capabilities that are difficult to graft onto a mutable forge. The repository contains bounded internal slices for several of them, but none is yet a shipped end-user capability. Each will remain scoped by the claim lattice, its comprehensive-plan section, and its backlog work.

#Verifiable reads, not just verifiable writes

Every supported FrankenGit read will derive from an authenticated RepositoryAuthorityHead. The verified-read protocol will let a ref, object-membership, PR-state, or outcome answer carry a Merkle proof connecting it to a head the client verifies independently. The authenticated roots and bounded proof/verifier slices exist; public API integration, complete proof coverage, mirror/CDN serving, and product UX do not. When those surfaces land, a verifying client will trust the head chain rather than the serving cell. (Plan §18.7, backlog FG-037.)

#Time travel as a product primitive

Because canonical state will remain an immutable decision stream, “the entire forge at decision N” will be a well-defined object rather than a reconstruction heuristic over mutable tables. fg at <decision> will open a complete read-only forge snapshot, and bisection will generalize from commits to forge state. The dated reality snapshot above identifies the bounded implementation and its historical evidence. It records history loading, two-ended diff projection, consistency checks, and binary rendering as landed. The remaining historical projection work requires non-empty durable-history coverage and verification of the production checkpoint path, not just parser coverage or an older passing revision. A complete time-travel product is not yet claimed. (Plan §31.8, backlog FG-038.)

#The evidence economy

Evidence-Carrying Changes and check receipts will be content-addressed and self-describing so they can travel between organizations without silently upgrading their claims. Schema, signing, import-policy, and adversarial slices exist, but no deployed cross-organization exchange service exists. Imported evidence will be allowed to tighten local checks and will never bypass them. (Plan §34.8, backlog FG-039.)

#Deterministic build outputs as derived state

FrankenGit will treat deterministic CI outputs like other profile-identified derived artifacts: trust-scoped, content-addressed, and keyed by the exact BuildInputCapsule. Internal reuse and poisoning-evidence slices exist, while the production workflow coordinator, hostile-execution substrate, and deployed cache service remain incomplete. (Plan §29.8, backlog FG-040.)

#Formal verification of the tiny core

The design concentrates trust into a deliberately small ordered residue: seals, terminal outcomes, batch admission, one head compare-and-swap, and root-last publication. Contained Lean theorems now cover named properties under explicit boundary assumptions, as recorded in the generated claim table below. They are not a proof of the production Rust implementation: the refinement bridge still has uncovered histories and no claim may cross that boundary without matching evidence. (Plan §40.8, backlog FG-041.)

---

#Pure Rust and dependency constitution

The production implementation is pure Rust on Rust 2024 with a dated current nightly pin.

Non-negotiable rules:

• every first-party crate uses #![forbid(unsafe_code)];
• no C/C++ FFI or linked native Git/crypto/network/compression/database engine;
• no production subprocess invocation of git or another VCS engine;
• upstream Git is a separately executed, pinned differential oracle only;
• Asupersync is the sole async runtime;
• FrankenSuite crates are preferred for existing mechanisms;
• external crates are exceptional, fundamental, pure-Rust, registry-approved, and dependency-evidence tracked;
• no Tokio, generic ORM/database/framework stack, opaque distributed system, or alternate runtime in production;
• no empty crate scaffolds or in-memory maps presented as final durable abstractions.

World-class performance is expected from algorithmic work reduction, safe portable SIMD, dense layouts, bounded arenas, per-core lanes, immutable sharing, batching, and cache-aware data structures—not raw pointers or hidden C fallbacks.

See docs/DEPENDENCY_AND_MEMORY_SAFETY_CONSTITUTION.md and registries/dependency_policy.tsv.

---

#Git compatibility is constitutional

FrankenGit preserves ordinary Git where it claims support:

• native SHA-1 and SHA-256 object identity as distinct typed domains;
• exact object framing, pack/delta/DEFLATE, pkt-line, sideband, upload-pack, and receive-pack;
• protocol-accurate fetch/clone and push terminology;
• atomic/non-atomic push semantics;
• shallow/partial/promisor operation;
• tags, notes, submodules, signed pushes, LFS, commit graphs, bitmaps, MIDX, bundles, and migration subsets according to explicit registry rows;
• observable iteration order, tie-breaks, error/refusal behavior, and resource limits.

FrankenGit does not claim a fictional standardized “protocol v2 push” command. Fetch and push are tracked as separate services/capability matrices.

Compatibility is differential against pinned upstream Git versions and source-derived/adversarial corpora. “Clone worked once” is not evidence of compatibility.

See docs/GIT_COMPATIBILITY_MATRIX.md.

---

#Agent-native collaboration

An agent operates through a signed IntentRun sponsored by a human or service principal. Authority is attenuated by repository, ref, path, object/secret/effect class, network domain, time, compute, storage, transfer, token, and monetary budget.

The run receives provenance-preserving ContextPacket objects and a TreeFS workspace. Network, secret, CI, publication, package, and external-service effects go through a non-textual capability broker and return immutable receipts.

An EvidenceCarryingChange binds:

• exact base authority state and proposed Git object closure;
• workspace intents and net effect;
• context identities, transforms, ranks, and omissions;
• tests/checks/build/tool/effect receipts;
• claimed invariants and explicit non-claims;
• graph/conflict/complexity witnesses;
• verifier attestations and independence class;
• requested publication/effects and budgets.

Prompt injection inside repository or retrieved text cannot widen capabilities, reveal secrets, suppress mandatory verification, approve itself, or alter retention/disclosure policy.

See docs/AGENT_PROTOCOL.md.

---

#Deployment profiles

#Embedded

• one binary/node;
• FrankenSQLite authority profile and local immutable object fabric;
• same canonical formats and transaction semantics as clustered operation;
• local TreeFS/materializations/search/graph;
• portable capsule backup/export.

#Self-hosted cluster

• stateless execution cells;
• conforming conditional authority backend or future fgit-authorityd;
• policy-driven immutable placement;
• active-active reads/materializations/projections;
• any eligible cell may attempt canonical publication;
• no repository “home cell” correctness dependency.

#FrankenGit.com

Adds managed global placement, quotas/accounting, SSO/SCIM, audit/compliance, hosted runners, premium retention/recovery, abuse controls, support, and measured SLOs. It must not fork canonical formats or make self-hosted correctness depend on proprietary services.

#Offline/local-first

Exact capsules, immutable bundles, local refs/forge events, and evidence can be exchanged later. Remote protected refs become observations or proposed transactions, never CRDT last-writer-wins authority.

---

#Verification doctrine

The project distinguishes:

invariant > proof > bounded_model > statistical > slo > benchmark

Weaker evidence cannot justify a stronger claim. Every public claim names scope, evidence, assumptions, current source/toolchain/profile, and expiry/revalidation rule.

Replay completeness is explicit:

• replayable;
• structural replay;
• verifiable when named external artifacts are supplied;
• audit only.

Failed hypotheses, rejected architectures, performance regressions, and cutover failures live in an append-only negative-evidence ledger so future agents do not repeat them.

#Checked claim status

This block is generated by fgit-registry-check claims-status. The checker refuses a stale block and automatically demotes a verified row when a committed artifact no longer matches its exact digest.

The initial local commands are:

./scripts/verify.sh docs
./scripts/verify.sh constitution
./scripts/verify.sh fast
./scripts/verify.sh full
./scripts/verify.sh release

The documentation/constitution/fast bootstrap lanes exist today. full and release deliberately return a typed exit-3 refusal until real conformance, fault, native-target, and artifact gates land; a dormant gate never reports success.

No invocation is evidence for a later revision. A green local crate test, a dirty-worktree lane, a batch_pending bead, or an older replay artifact will not be described as proof that current main is verified. The orchestrated batch gate and the generated claim registry will remain the revision-bound sources of truth.

See VERIFY_SPEC.md and docs/NEGATIVE_EVIDENCE_LEDGER.md.

---

#Workspace progress and planned expansion

Crates appear only with a real final-abstraction slice. The prospective strict DAG contains:

• foundation: typed IDs/refusals, canonical codec, claims, evidence, resources, registry checker;
• Git/storage primitives: objects, packs, wire, authority, object fabric, RaptorQ, ATP-Git, TreeFS, crypto policy;
• canonical engines: reference model, transaction kernel, chronicle, policy, forge events, GC, repair, materialization, generation authority;
• derived systems: search, typed graphs, document lineage, agents, CI protocol, packages, projections;
• products/adapters: gateway, API, CLI, node, runner, operations, browser/WASM.

The repository now contains dozens of first-party fgit-* crates plus the constitutional registry checker. Implemented crate-level slices include the foundation, Git/storage, transaction/chronicle, embedded authority, object fabric, TreeFS, repair, statistics, graph, forge, identity/policy, agent, runner, release, node, and CLI layers. A crate being present means only that its bounded final-abstraction slice exists; it does not mean the complete subsystem or its product integration is ready. Search, projection, gateway/API, web, TUI, operations, package-registry, and several hosted-service surfaces will still need their owning implementation and evidence slices.

See the full map in COMPREHENSIVE_PLAN_FOR_THE_DESIGN_OF_FRANKENGIT.md.

---

#Repository map

Machine-validated registries live under registries/.

---

#Near-term execution

The next integration work will prioritize capability gaps rather than crate count:

1. The raw git-daemon receive-pack slice will be extended into smart HTTP and production SSH, while the pinned-client compatibility campaign grows its restart, fault, and larger-repository evidence without weakening finite resource bounds.
2. The existing snapshot/history and two-ended diff paths will gain non-empty durable-history coverage through the actual fg binary, including authority consistency and refusal cases. Production checkpoint behavior and the wider snapshot contract must have revision-bound evidence before fg at is described as a complete product capability.
3. Forge merges will move from real computation plus an incomplete durable composition to the same asynchronous materialization and exactly-one-head-CAS path used by admitted receive operations.
4. Identity and policy will be wired into receive, merge, transport, and disclosure boundaries before broader multi-tenant surfaces open.
5. fastapi_rust, sqlmodel/FrankenSQLite, and FrankenTUI will converge on the one runtime/dependency constellation before smart HTTP, native REST, projections/search, web, and TUI product layers are admitted.
6. Workflow coordination and production hostile-execution isolation will land before CI is described as deployable; release publication will remain refused until the full/release gates and native target matrix are real.
7. Multi-cell, repair, verified-read, performance, and hosted-service claims will expand only from revision-bound conformance, fault, security, and economics evidence.

The phase plan is in COMPREHENSIVE_PLAN_FOR_THE_DESIGN_OF_FRANKENGIT.md.

---

#What FrankenGit is not

• not a new incompatible VCS;
• not a wrapper around C Git or libgit2;
• not a mutable bare repository designated as canonical truth;
• not a repository-primary or home-cell architecture;
• not a relational forge database reconciled asynchronously with Git refs;
• not asynchronous multi-master ref mutation;
• not RaptorQ used as consensus, hashing, or authorization;
• not graph/model output used as hidden policy authority;
• not agent text interpreted as capabilities;
• not GitHub-hosted Actions used as release truth;
• not yet a complete network push service, smart-HTTP/SSH forge, native API, hosted multi-region service, or releasable product;
• not yet supported by evidence broad enough to claim general Git compatibility, performance leadership, production readiness, or complete Rust-level formal verification;
• not honestly describable as OSI open source under the current license (D14 resolved it as LicenseRef-MIT-OpenAI-Anthropic-Rider, whose OSI marker is no).

---

#License

The license is LicenseRef-MIT-OpenAI-Anthropic-Rider: the MIT licence together with the OpenAI/Anthropic rider, recorded as decision D14 by the repository owner on 2026-08-23. The full text is in LICENSE.

The rider withholds all rights from OpenAI, Anthropic, their affiliates, and anyone acting on their behalf. Because the Open Source Definition forbids discriminating against persons or groups, these terms are not an OSI-approved open-source license, and the repository is described as source-available. Public wording must remain exact: name the license, and do not call it open source while the rider stands.

---

#Public design review

The architecture and its growing implementation are intentionally public so contradictions can be found before they harden into product semantics. Useful review will continue to focus on concrete invariants, counterexamples, protocol compatibility, authority-store semantics, resource/security bounds, graph/transport algorithms, dependency closure, and executable evidence—not on whether the plan sounds ambitious or the repository contains many files.