UCF Formal Specification v0.1.0
The constitutional formalization of engineering — how constitutional workspaces, entities, reviews, attestations, and commits maintain provenance, integrity, and sovereignty throughout the engineering lifecycle.
Preamble
This document is the formal specification of the Universal Constitutional Forge (UCF) — the constitutional engineering environment where constitutional work is created, reviewed, attested, and committed. UCF answers the question: How are constitutional systems engineered?
This specification answers the constitutional question: How are systems engineered? It defines the invariants that engineering must satisfy — the properties that hold true regardless of implementation. UCF specifies no IDE, no file format, no UI framework. It specifies what any conforming engineering environment must guarantee.
UCF sits at the application layer (L5), derived from UCD (constitutional derivatives). Where USR defines how meaning is executed, UCN defines how meaning is communicated, and USDS defines how artifacts are distributed, UCF defines how constitutional work is produced with verified provenance — the engineering lifecycle from workspace creation to committed artifact.
The v0.1.0 PWA demonstrated that constitutional engineering is possible in a browser-first, offline-first environment. This specification proves that it is definable, verifiable, and sovereign.
Classification: Constitutional — defines the engineering model for all of ICore.
Derivation:
UCD (constitutional derivatives) → UCF (constitutional engineering environment)
Depends on: UCD (constitutional derivatives composed from UCA capabilities). Transitively, UCF depends on the entire constitutional stack — engineering must produce work that answers all six constitutional questions.
Depended on by: Studyo (visualizes engineering workflows), ICS (tests against engineering artifacts), CodeLabs (sandboxed experimentation within UCF workspaces).
Section 1: Foundational Axioms
Every engineering capability must trace to these axioms. Nothing exists in UCF that these axioms do not authorize.
1.1 The Five Engineering Axioms
| # | Axiom | Statement | Derived From |
|---|
| EA1 | Engineering requires workspace isolation. | Every workspace is a constitutionally isolated environment. Entities within a workspace cannot affect entities in another workspace without explicit, attested transfer. No workspace may silently modify another. | Constraint (USCP) |
| EA2 | Every entity requires provenance. | Every constitutional artifact — specification, test, documentation, code — must carry verifiable provenance: what it is, who created it, what it derives from, and what it constrains. An entity without provenance is constitutionally void. | Identity (USCP) |
| EA3 | No change enters the record without review. | Every modification to a constitutional entity must pass through a review process before being committed. Unreviewed changes cannot become part of the constitutional record. Review is a gate, not a courtesy. | Verification (USCP) |
| EA4 | Reviews produce attestations. | Every completed review produces a cryptographic attestation binding the reviewer's identity to the verdict, the work reviewed, and the time of review. Attestations are immutable and append-only. | Relationship (USCP) |
| EA5 | Commits are immutable history. | Every committed change creates an immutable record linking the workspace state, the reviewed changes, the attestation chain, and a deterministic snapshot. History cannot be rewritten — only extended. | Transformation (USCP) |
1.2 Axiom Sufficiency
All six USCP primitives are represented across the axioms:
| Primitive | Present In | Role |
|---|
| Existence | EA2 (provenance) | Entities exist as provenanced artifacts, not anonymous files |
| Identity | EA2 (provenance), EA4 (attestation) | Every entity and review carries verified identity |
| Relationship | EA4 (attestation), EA5 (commits) | Attestations bind reviewers to work; commits bind changes to history |
| Constraint | EA1 (workspace isolation) | Workspaces are constitutionally isolated environments |
| Transformation | EA5 (commits) | Commits transform workspace state immutably |
| Verification | EA3 (review gate), EA4 (attestation) | Review validates; attestation proves validation occurred |
The foundation is complete. The six primitives are fully represented.
Section 2: The Engineering Model
2.1 Definitions
| Term | Definition |
|---|
| Workspace | A constitutionally isolated engineering environment containing entities, reviews, attestations, and commits. Workspaces are the atomic unit of engineering isolation. |
| Entity | A constitutionally identified artifact within a workspace: a specification, test, document, blueprint, or any other work product. Every entity carries provenance. |
| Review | A structured evaluation of an entity change by a qualified reviewer. Reviews produce verdicts (approve, reject, request-changes) with justification. |
| Attestation | A cryptographic record binding a reviewer's identity to a review verdict, the entity reviewed, and the time of review. Attestations are immutable. |
| Commit | An immutable record of workspace state at a point in time, linking reviewed changes, attestation chains, and a deterministic snapshot hash. |
| Registry | A constitutional catalog of workspaces and their public entities, enabling discovery and cross-workspace reference. |
| Snapshot | A deterministic hash of workspace state at commit time, enabling verification that the workspace has not been tampered with since commit. |
2.2 The Workspace Model
┌═══════════════════════════════════════════════════════════════════┐
║ CONSTITUTIONAL WORKSPACE ║
║ ║
║ ┌─────────────────────────────────────────────────────────────┐ ║
║ │ Entities │ ║
║ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ ║
║ │ │ Spec A │ │ Test B │ │ Doc C │ │ Code D │ │ ║
║ │ │ (proven.) │ │ (proven.) │ │ (proven.) │ │ (proven.) │ │ ║
║ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ ║
║ │ │ │ │ │ │ ║
║ │ └─────────────┴──────┬──────┴─────────────┘ │ ║
║ │ ↓ │ ║
║ │ ┌──────────────┐ │ ║
║ │ │ Reviews │ │ ║
║ │ │ (gate) │ │ ║
║ │ └──────┬───────┘ │ ║
║ │ ↓ │ ║
║ │ ┌──────────────┐ │ ║
║ │ │ Attestations │ ← cryptographic proof │ ║
║ │ │ (immutable) │ │ ║
║ │ └──────┬───────┘ │ ║
║ │ ↓ │ ║
║ │ ┌──────────────┐ │ ║
║ │ │ Commits │ ← immutable history │ ║
║ │ │ (append-only)│ │ ║
║ │ └──────────────┘ │ ║
║ └─────────────────────────────────────────────────────────────┘ ║
║ ║
║ Workspace is constitutionally isolated. ║
║ No workspace may silently modify another. ║
╚═══════════════════════════════════════════════════════════════════╝
2.3 Constitutional Layer
| Property | Value |
|---|
| Layer ordinal | 7 (Applications) |
| Layer name | Applications |
| Derives from | Layer 6 (Derivatives): UCD |
| Depended on by | Implementation layer: Studyo, CodeLabs |
| Governance status | Constitutional — engineering changes require Part IV pipeline |
Section 2.5: The Doctrine Position
UCF occupies a specific position in the constitutional doctrine:
| Doctrine Principle | UCF Position |
|---|
| Constitution before architecture | UCF's axioms (EA1-EA5) are constitutional law, derived from USCP primitives |
| Architecture before implementation | The workspace/entity/review/commit model defines the architecture; browser-first PWA is implementation |
| Implementation before optimization | v0.1.0 proved browser-first engineering is possible; this spec makes it normative |
UCF defines the invariants. Implementations choose the mechanisms.
Section 3: The Workspace Contract
3.1 Specification
| Property | Requirement |
|---|
| Record | Workspace { id, name, description, created_at, owner, entities, reviews, attestations, commits, snapshot } |
| Operations | create(name, description) → workspace, get_entity(id) → entity, list_entities() → list, get_history() → list[commit] |
| ID derivation | SHA-256(name:owner:created_at) — deterministic, reproducible |
| Isolation | Workspaces are constitutionally isolated — no cross-workspace mutation without explicit transfer |
3.2 Workspace Invariants
| # | Invariant | Statement |
|---|
| W1 | Non-empty name | Every workspace must have a non-empty human-readable name. |
| W2 | Owner required | Every workspace must have a declared owner identity. |
| W3 | Isolation | Entities in workspace A cannot be modified by operations on workspace B. |
| W4 | Snapshot integrity | The workspace snapshot hash must match SHA-256(sorted_entity_hashes). |
| W5 | Append-only history | Commits are appended in order. No commit may be removed or reordered. |
Section 4: The Entity Contract
4.1 Specification
| Property | Requirement |
|---|
| Record | Entity { id, workspace_id, name, type, content_hash, created_by, created_at, updated_at, provenance, status } |
| Operations | create(name, type, content) → entity, update(id, content) → entity, verify(id) → bool |
| ID derivation | SHA-256(workspace_id:name:type:content_hash) — deterministic |
| Types | specification, test, documentation, blueprint, code, atlas, other |
4.2 Entity Invariants
| # | Invariant | Statement |
|---|
| EN1 | Provenance required | Every entity must carry provenance: creator identity, creation time, and derivation source. |
| EN2 | Type declaration | Every entity must declare a constitutional type from the allowed set. |
| EN3 | Content binding | The entity's content_hash must equal SHA-256(content). Content tampering is detectable. |
| EN4 | Workspace membership | An entity belongs to exactly one workspace. Cross-workspace movement requires explicit transfer with attestation. |
| EN5 | Status tracking | Every entity has a status: draft, review, approved, committed, archived. Status transitions follow the review gate. |
4.3 Entity Status Lifecycle
┌────────┐ ┌────────┐ ┌──────────┐ ┌──────────┐
│ draft │────→│ review │────→│ approved │────→│ committed│
└────────┘ └───┬────┘ └──────────┘ └──────────┘
│
↓ (reject / request-changes)
┌────────┐
│ draft │ ← returns to draft
└────────┘
Any status → archived (with justification)
Section 5: The Review Contract
5.1 Specification
| Property | Requirement |
|---|
| Record | Review { id, entity_id, reviewer_id, verdict, justification, reviewed_at, changes_requested } |
| Verdicts | approve, reject, request-changes |
| Operations | submit(entity, reviewer) → review, resolve(review_id, verdict, justification) → review |
| Gate rule | No entity may transition from review to approved without a resolved review with verdict approve |
5.2 Review Invariants
| # | Invariant | Statement |
|---|
| R1 | Mandatory gate | No change to a committed entity may bypass review. Unreviewed changes cannot enter the constitutional record. |
| R2 | Reviewer identity | Every review must carry a verified reviewer identity. Anonymous reviews are constitutionally void. |
| R3 | Justified verdict | Every verdict must include a non-empty justification explaining the reasoning. |
| R4 | One review per change | Each entity version requires at least one resolved review before commitment. Multiple reviews are permitted but not required. |
| R5 | Self-review prohibited | A reviewer may not review their own entity changes. The reviewer must be a different identity than the entity's last updater. |
Section 6: The Attestation Contract
6.1 Specification
| Property | Requirement |
|---|
| Record | Attestation { id, review_id, reviewer_id, entity_id, entity_hash, verdict, timestamp, signature } |
| Operations | attest(review) → attestation, verify(attestation) → bool, get_chain(entity_id) → list[attestation] |
| Signature | SHA-256("ucf-attestation:" + reviewer_id:entity_id:entity_hash:verdict:timestamp) |
6.2 Attestation Invariants
| # | Invariant | Statement |
|---|
| AT1 | Post-review only | An attestation may only be created after a review is resolved. |
| AT2 | Entity binding | The attestation records the entity's content hash at review time — binding the attestation to the exact work reviewed. |
| AT3 | Reviewer binding | The signature includes the reviewer's identity — the attestation cannot be forged or transferred. |
| AT4 | Immutable | Attestation records are never modified after creation. They are append-only. |
| AT5 | Chain integrity | The full attestation chain for an entity must be internally consistent — every record must verify. |
Section 7: The Commit Contract
7.1 Specification
| Property | Requirement |
|---|
| Record | Commit { id, workspace_id, snapshot_hash, changes, attestation_ids, committed_at, message } |
| Operations | commit(workspace, changes, message) → commit, verify(commit) → bool, get_history(workspace) → list[commit] |
| Snapshot | SHA-256(sorted_entity_content_hashes) at time of commit — deterministic, reproducible |
7.2 Commit Invariants
| # | Invariant | Statement |
|---|
| C1 | Reviewed changes only | Every change included in a commit must have a corresponding approved review and attestation. |
| C2 | Deterministic snapshot | The snapshot hash is computed from entity content hashes at commit time — identical state produces identical hash. |
| C3 | Append-only | Commits are appended in chronological order. No commit may be removed, reordered, or modified. |
| C4 | Message required | Every commit must include a non-empty human-readable message describing the change. |
| C5 | Chain continuity | Each commit (after the first) must reference the previous commit's snapshot hash, forming an unbroken chain. |
7.3 The Commit Chain
Commit 1 Commit 2 Commit 3
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ snapshot: a1b2 │ │ snapshot: c3d4 │ │ snapshot: e5f6 │
│ prev: genesis │───────→│ prev: a1b2 │───────→│ prev: c3d4 │
│ changes: [...] │ │ changes: [...] │ │ changes: [...] │
│ attest: [...] │ │ attest: [...] │ │ attest: [...] │
│ msg: "initial" │ │ msg: "refine" │ │ msg: "add spec" │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Chain is unbreakable. Each commit proves continuity from the previous.
Section 8: The Registry Contract
8.1 Specification
| Property | Requirement |
|---|
| Record | Registry { workspaces: list, entities: list, last_updated } |
| Operations | register(workspace) → bool, search(query) → list[entity], get_workspace(id) → workspace |
8.2 Registry Invariants
| # | Invariant | Statement |
|---|
| RG1 | Discovery only | The registry enables discovery — it does not grant modification rights. |
| RG2 | Workspace opt-in | Workspaces register themselves voluntarily. Registration does not imply endorsement. |
| RG3 | Public metadata | Registry entries expose workspace name, description, entity count, and last commit time — not entity content. |
Section 9: The Constitutional Error Model
9.1 Error Taxonomy
| Error | Category | Trigger |
|---|
WorkspaceIsolationViolation | Workspace | Attempting cross-workspace mutation without explicit transfer |
ProvenanceMissing | Entity | Entity created without required provenance fields |
ReviewBypassAttempted | Review | Attempting to commit unreviewed changes |
SelfReviewAttempted | Review | Reviewer is the same identity as the entity's last updater |
AttestationInvalid | Attestation | Signature mismatch, entity hash mismatch, or chain break |
CommitChainBroken | Commit | Commit does not reference previous commit's snapshot hash |
SnapshotMismatch | Commit | Computed snapshot hash does not match stored hash |
9.2 Error Properties
| # | Property | Statement |
|---|
| EP1 | Transparent | Every error carries a human-readable message explaining the failure. |
| EP2 | Classified | Every error belongs to exactly one contract category. |
| EP3 | Non-destructive | Errors do not corrupt workspace state. The workspace remains consistent after any error. |
| EP4 | Traceable | Errors reference the specific invariant or rule that was violated. |
10.1 Conformance Tests
An implementation conforms to the UCF Formal Specification if and only if:
| # | Test | Pass Criterion | Severity |
|---|
| UCF-01 | Workspace Isolation | Entities in workspace A cannot be modified by operations on workspace B. | Critical |
| UCF-02 | Entity Provenance | Every entity carries creator identity, creation time, and derivation source. | Critical |
| UCF-03 | Content Integrity | Entity content_hash equals SHA-256(content). Tampering is detectable. | Critical |
| UCF-04 | Review Gate | No entity transitions from review to approved without a resolved review with verdict approve. | Critical |
| UCF-05 | Reviewer Identity | Every review carries a verified reviewer identity. | Critical |
| UCF-06 | Self-Review Prevention | A reviewer cannot review their own entity changes. | Major |
| UCF-07 | Attestation Integrity | Every attestation record verifies (signature matches recomputed value). | Critical |
| UCF-08 | Attestation Immutability | Attestation records are never modified after creation. | Critical |
| UCF-09 | Commit Reviewed-Only | Every change in a commit has a corresponding approved review and attestation. | Critical |
| UCF-10 | Snapshot Determinism | Identical workspace state produces identical snapshot hash. | Critical |
| UCF-11 | Commit Chain Continuity | Each commit references the previous commit's snapshot hash. | Critical |
| UCF-12 | History Immutability | Commits cannot be removed or reordered. | Critical |
| UCF-13 | Error Transparency | Every error carries a classified, human-readable message. | Major |
| UCF-14 | Registry Discovery | Registered workspaces are discoverable via search. | Minor |
| UCF-15 | Workspace Snapshot | Workspace snapshot hash equals SHA-256(sorted_entity_content_hashes). | Critical |
10.2 Conformance Levels
| Level | Name | Requirements | Certification |
|---|
| F0 | Non-Conformant | Fails any Critical test. | None. May not claim UCF conformance. |
| F1 | Core Conformant | Passes all Critical tests + ≤2 Major failures. | May operate as a constitutional forge. |
| F2 | Fully Conformant | Passes all 15 tests (15/15). | May enter the canonical reference. Eligible for standardization. |
Section 11: Self-Verification
11.1 Against the 10 Constitutional Tests
UCF Formal Specification v0.1.0 verified against the Kernel's 10 constitutional tests:
| # | Test | Result | Evidence |
|---|
| 1 | Reality | ✅ PASS | The specification addresses the real need: formal rules for constitutional engineering. Every section maps to a demonstrated implementation capability. |
| 2 | Origin | ✅ PASS | Derived from UCD (L5) and transitively the entire stack. All axioms trace to USCP primitives (Section 1.1). The five contracts map to constitutional questions. |
| 3 | Necessity | ✅ PASS | Without UCF, constitutional work cannot be produced with verified provenance. The kernel has no mechanism for engineering lifecycle management. |
| 4 | Derivation | ✅ PASS | Follows D7 (applications are constitutionally derived from UCD). Follows D1 (derived from UCD, the layer below). No upward mutations. |
| 5 | Consistency | ✅ PASS | No axiom contradicts another. No invariant conflicts with a different invariant. The five contracts are orthogonal. |
| 6 | Verification | ✅ PASS | Every axiom can be verified by tracing to USCP primitives. The 15 conformance tests provide a concrete verification protocol. |
| 7 | Simplicity | ✅ PASS | Five axioms, five contracts, fifteen conformance tests. Each element exists because removing it creates a constitutional gap. |
| 8 | Sovereignty | ✅ PASS | The specification introduces no external dependencies. Cryptographic primitives (SHA-256) serve sovereignty (attestation), not external coupling. |
| 9 | Replaceability | ✅ PASS | The contract model is technology-independent. Any language implementing the workspace/entity/review/commit model produces a conforming forge. |
| 10 | Evolution | ✅ PASS | The specification can be amended through Part IV governance. New entity types, review workflows, and attestation schemes can be added. |
Result: 10/10 PASS. UCF Formal Specification v0.1.0 is constitutionally sound and enters the constitutional record.
Appendix: Relationship to v0.1.0 Implementation
This formal specification captures what v0.1.0 demonstrated and makes it normative:
| Implementation (demonstrated) | Specification (normative) | Status |
|---|
UCF_Workspace — workspace CRUD, entity management | Section 3: Workspace Contract | Formalized |
UCF_Context — entity creation, content management | Section 4: Entity Contract | Formalized |
UCF_Review — review submission and resolution | Section 5: Review Contract | Formalized |
UCF_Attestation — cryptographic attestation | Section 6: Attestation Contract | Formalized |
UCF_Commit — versioned commits with snapshots | Section 7: Commit Contract | Formalized |
UCF_Registry — workspace discovery and registration | Section 8: Registry Contract | Formalized |
UCF_Crypto — SHA-256 hashing, attestation signing | Cryptographic substrate | Formalized |
UCF_Verification — snapshot and chain verification | Sections 7, 10 | Formalized |
UCF_Export / UCF_Import — data portability | Cross-cutting concern (UCA-adaptable) | Informative |
What the specification adds beyond v0.1.0 implementation:
- Normative axioms — the five engineering axioms (EA1-EA5) are constitutional law, not code comments
- Invariant completeness — 25 named invariants across all contracts (W1-W5, EN1-EN5, R1-R5, AT1-AT5, C1-C5, RG1-RG3, EP1-EP4)
- Conformance tests — 15 formalized tests (UCF-01 through UCF-15) with severity levels
- Self-review prevention — R5 is a new invariant not enforced in v0.1.0
- Commit chain continuity — C5 enforces unbroken history, not just append-only
- Error model — classified, transparent, non-destructive, traceable (Section 9)
Originator Attribution
This UCF Formal Specification v0.1.0 is originated, created, and concept-pioneered by:
Originator: Sir Collins — Creator and Concept Pioneer of ICore (access1@tutamail.com)
Date of origination: July 21, 2026
Scope: All axioms, contract models, invariants, engineering lifecycle, error models, conformance criteria, and verification protocols presented in this specification.
This attribution is a constitutional artifact. It establishes provenance — the lowest and most fundamental layer of trust.
UCF is the Constitution's workshop. This specification is the Constitution's promise that the workshop will only produce work that the Constitution authorizes — with verified provenance, reviewed changes, and immutable history.