there's no such thing as gravity, code just sucks

 

license: public domain CC0 

Design Document: Semantic Gravity Architecture for Agent‑Native Software Development

1. Overview

This document proposes a new architectural and UX paradigm for software development:
Semantic Gravity Architecture (SGA) — a system where code is organized, refactored, visualized, and executed according to conceptual purpose rather than file boundaries.

SGA replaces file‑based editing with a semantic graph of conceptual nodes (views, flows, invariants, transitions, models, integrations, etc.), and introduces a categorical gravity model that guides where code “wants” to live. An AI agent continuously analyzes code fragments, infers their gravity vectors, proposes refactors, and negotiates exceptions with the developer through explicit annotations.

The result is a development environment that is:

• agent‑native
• explainable
• architecturally principled
• visually navigable
• mock‑data‑rich
• friction‑minimizing
• semantically grounded

This system aims to restore immediacy and joy to programming by eliminating file silos, reducing cognitive friction, and enabling continuous, isolated execution of conceptual units.

---

2. Motivation

2.1 The Problem with File‑Based Development

Files are:

• storage artifacts, not conceptual boundaries
• friction points for navigation
• poor containers for mixed concerns
• hostile to visual representations
• resistant to automated refactoring

Developers naturally write code “where their eyes are,” leading to:

• logic leaking into views
• business rules leaking into controllers
• integration code leaking into domain models

Existing patterns (MVC, MVVM, Clean Architecture) rely on manual discipline, which is fragile and cognitively expensive.

2.2 The Missing Ingredient: Architectural Gravity

Architectures fail because they lack:

• a principled way to classify code by purpose
• a mechanism to detect conceptual drift
• a negotiation loop for exceptions
• a semantic memory of architectural intent

2.3 The Opportunity: Agent‑Native Architecture

With an AI agent continuously observing, refactoring, and negotiating, we can:

• infer purpose
• maintain structure
• generate mock data
• provide multiple views
• run conceptual nodes in isolation
• record architectural decisions

This is the first time such a system is feasible.

---

3. Core Concepts

3.1 Semantic Graph as Source of Truth

The system stores code as a semantic graph, not files.

Nodes include:

• UI surfaces
• transitions
• guards
• invariants
• domain models
• integration endpoints
• workflows
• computations
• mock data generators
• personas
• architectural annotations

Edges encode:

• dependencies
• data flow
• control flow
• invariants
• purpose relationships

Files become projections, not the canonical representation.

---

3.2 Gravitational Loci

A locus is a conceptual “home” for code.
Examples:

• UI
• Domain
• Integration
• Security
• Computation
• Cache
• Graphics
• Observability
• Orchestration

Each locus has a defined purpose and intended content.

---

3.3 Categorical Gravity Vectors

Each code fragment receives a vector of categorical ratings:

• Low — barely relevant
• Medium — somewhat relevant
• High — natural home
• Antagonist — conceptually opposed

Example:

UI: High
Domain: Low
Integration: Antagonist
Security: Low
Computation: Medium

This vector guides:

• placement
• refactoring
• splitting
• warnings
• architectural negotiation

---

3.4 Antagonism as Architectural Pressure

Antagonist does not mean “illegal.”
It means:

“This code is fighting the purpose of this locus.”

The agent surfaces antagonism and asks the user how to proceed.

---

3.5 Legalization Annotations

When the user intentionally keeps antagonistic code in place, they annotate it:

@legalize("Runtime-generated query; temporary placement for flow simplicity.")

This:

• records intent
• suppresses future warnings
• becomes part of semantic provenance
• guides future agents
• enables architectural archaeology

---

3.6 Controlled Natural Language for Mock Data

Mock data is essential for:

• isolated execution
• UI previews
• flow simulation
• testing
• debugging

The agent supports controlled natural language:

“Give me international names, not just Anglo‑Saxon.”

The agent translates this into a structured generator spec.

Mock data becomes a first‑class resource.

---

3.7 Visual Representations

Because the source of truth is a semantic graph, the system can render:

• state machines
• data lineage diagrams
• control flow graphs
• UI interaction graphs
• architectural layering views
• performance hot paths
• semantic diffs
• runtime animations

All views are editable and always in sync.

---

3.8 Isolated Execution of Conceptual Nodes

Any node can be run independently:

• render a view with mock data
• simulate a transition
• test a guard
• run a workflow
• animate a state machine

The agent automatically:

• stubs dependencies
• generates data
• simulates environment
• isolates effects

---

4. Comparisons to Existing Paradigms

4.1 MVC / MVVM / Redux / Elm

These patterns enforce separation of concerns through:

• folder structure
• file boundaries
• manual discipline

SGA replaces this with:

• semantic gravity
• agent‑assisted refactoring
• architectural negotiation
• conceptual nodes

4.2 Clean Architecture / Hexagonal Architecture

These emphasize:

• domain purity
• dependency inversion
• strict layering

SGA preserves these goals but:

• removes file friction
• adds explainability
• supports exceptions
• uses categorical gravity instead of rigid rules

4.3 Visual Programming Tools

Traditional visual tools fail because:

• diagrams drift out of sync
• they cannot express edge cases
• they are not the source of truth

SGA solves this by:

• making the semantic graph canonical
• generating diagrams as projections
• allowing edits from any view

4.4 Linting and Static Analysis

Linters detect issues but:

• cannot negotiate
• cannot refactor
• cannot record intent
• cannot generate mock data

SGA’s agent is a semantic collaborator, not a rule enforcer.

---

5. Applications

5.1 Large‑Scale Web Applications

• consistent architecture
• automatic lifting of logic
• mock data for every view
• isolated execution of flows

5.2 Game Development

• visual state machines
• graphics loci
• physics loci
• runtime simulation
• mock entities

5.3 Backend Systems

• workflow orchestration
• integration endpoints
• caching strategies
• security invariants

5.4 AI‑Driven Tools

• explainable pipelines
• data lineage
• model lifecycle flows

---

6. Detailed Design Features

6.1 Gravity Inference Engine

Uses:

• vocabulary
• dependencies
• side effects
• invariants
• call graph context

Produces:

• categorical gravity vector
• antagonism flags
• refactor suggestions

6.2 Architectural Negotiation Loop

1. Agent detects antagonism
2. Surfaces suggestion
3. User chooses:
   • lift
   • split
   • legalize
4. Agent applies change
5. Semantic graph updates

6.3 Mock Data Subsystem

• type‑driven generators
• controlled‑natural‑language refinement
• personas
• adversarial cases
• semantic fuzzing

6.4 Visual Views

• always in sync
• editable
• explainable
• animated for runtime

6.5 Semantic Provenance

Every architectural decision is recorded:

• legalizations
• refactors
• invariants
• purpose tags
• generator specs

This enables:

• replayable development
• semantic archaeology
• agent‑assisted reconstruction

---

7. Future Work

• adaptive gravity thresholds per project
• user‑defined loci
• collaborative multi‑agent architecture
• semantic version control
• cross‑project architectural learning
• domain‑specific gravity profiles

---

8. Conclusion

Semantic Gravity Architecture replaces file‑based programming with a principled, agent‑native, concept‑driven environment. It introduces gravitational loci, categorical gravity vectors, architectural negotiation, and first‑class mock data generation — all grounded in a semantic graph that supports multiple synchronized views.

This system is not an incremental improvement.
It is a new substrate for software development, designed for a world where humans and agents collaborate on architecture, semantics, and intent.

 

a sufficiently friendly compiler

license: public domain CC0

 

Design: Interactive, Constraint‑Driven Compiler Collaboration

This doc sketches a compiler system where the programmer, an agent, and the compiler negotiate lowering from high‑level code to low‑level implementation using annotations, dials, and an explicit constraint graph.

---

1. Goals and non‑goals

• Goal: Make lowering from HLL → LLL explicit, explainable, and steerable without sacrificing safety.
• Goal: Treat performance and representation decisions as first‑class, checkable semantics, not opaque heuristics.
• Goal: Allow interactive refinement of lowering choices with clear knock‑on effects.
• Non‑goal: Replace all compiler heuristics with manual control. The system should augment, not burden, the programmer.
• Non‑goal: Require annotations everywhere. Defaults must be reasonable and compositional.

---

2. Core concepts

2.1 Annotations (hard constraints)

Annotations are semantic contracts attached to code or types. If they cannot be upheld in the lowered program, the compiler must reject the program.

• Examples:

  • @heap — value must be heap‑allocated.
  • @stack — value must be stack‑allocated.
  • @region("frame") — value must live in a specific region.
  • @noescape — value must not outlive its lexical scope.
  • @pure — function must be side‑effect‑free.
  • @noalias — reference must not alias any other reference.
  • @soa / @aos — layout constraints.
  • @inline(always) — must be inlined (subject to well‑formedness rules).

• Properties:

  • Hard: Violations are compile‑time errors, not warnings.
  • Compositional: Annotations propagate through the IR and participate in constraint solving.
  • Semantic: They describe what must be true, not how to implement it.

2.2 Dials (soft preferences)

Dials are global or scoped optimization preferences that guide heuristics but do not invalidate programs.

• Examples:

  • opt.memory = "cache_locality" vs "allocation_count".
  • opt.layout = "prefer_soa" for a module.
  • opt.inlining_aggressiveness = high.
  • opt.vectorization = "prefer_branchless".
  • opt.reg_pressure_budget = medium.

• Properties:

  • Soft: They influence choices but never cause errors by themselves.
  • Scoped: Can apply to a project, module, function, or region.
  • Negotiable: The agent can propose dial changes to satisfy constraints or improve performance.

2.3 Constraint graph

Lowering is modeled as a constraint satisfaction problem over an IR:

• Nodes: IR entities (functions, blocks, values, allocations, regions, loops).
• Constraints:
  • From annotations (hard).
  • From language semantics (hard).
  • From dials and heuristics (soft).
• Edges: Dependencies between decisions (e.g., “if this escapes, stack allocation is impossible”).

The compiler maintains this graph and uses it to:

• Check feasibility of annotations.
• Explore alternative lowerings.
• Explain knock‑on effects.

---

3. Architecture

3.1 Pipeline overview

1. Front‑end:

   • Parse source → AST.
   • Type check, effect check.
   • Attach annotations to AST nodes.

2. Semantic IR:

   • Lower AST to a high‑level IR with:
     • explicit control flow,
     • explicit effects,
     • explicit allocation sites,
     • explicit regions/scopes.
   • Preserve annotations as IR metadata.

3. Constraint extraction:

   • Build a constraint graph from:
     • annotations,
     • type/effect system,
     • lifetime/escape analysis,
     • alias analysis,
     • layout rules.

4. Initial lowering plan:

   • Apply default heuristics + dials to propose:
     • allocation strategies,
     • inlining decisions,
     • layout choices,
     • vectorization/fusion decisions.

5. Interactive negotiation (optional mode):

   • Expose the plan and constraint graph to the agent + programmer.
   • Allow adjustments to annotations/dials.
   • Re‑solve constraints and update the plan.

6. Final IR + codegen:

   • Commit to a consistent lowering.
   • Emit low‑level IR / machine code.
   • Optionally emit a “lowering report” for debugging and learning.

---

4. Error model for annotations

Annotations are part of static semantics. They can fail in well‑defined ways.

4.1 Typical error classes

• Lifetime violations:

  • Example: @stack on a value that escapes its function.
  • Result: Error with explanation of the escape path.

• Purity violations:

  • Example: @pure function performs I/O or calls impure code.
  • Result: Error with call chain showing the impure operation.

• Alias violations:

  • Example: @noalias reference proven to alias another reference.
  • Result: Error with the aliasing path.

• Layout violations:

  • Example: @packed on a type requiring alignment; @soa on unsupported structure.
  • Result: Error with the conflicting fields/types.

• Inlining violations:

  • Example: @inline(always) on a recursive function where inlining would not terminate.
  • Result: Error with recursion cycle.

• Region violations:

  • Example: @region("frame") on a value that must outlive the frame.
  • Result: Error with lifetime mismatch.

4.2 Error reporting shape

• Core message: Which annotation failed and where.
• Cause chain: Minimal slice of the constraint graph that explains why.
• Alternatives: Valid strategies the compiler can suggest:
  • remove or relax the annotation,
  • adjust another annotation,
  • tweak a dial (e.g., enable region allocation).

---

5. Interactive negotiation flow

This mode is optional but central to the design.

5.1 Baseline flow

1. Compiler proposes a plan:

   • “Given current code + annotations + dials, here is the lowering.”

2. Agent summarizes tradeoffs:

   • Example: “Using SoA for Particle improves cache locality but increases register pressure; loop fusion reduces parallelism.”

3. Programmer adjusts:

   • Add/modify annotations.
   • Change dials (e.g., “don’t fuse loops in this module”).

4. Compiler re‑solves constraints:

   • Updates the plan.
   • Detects any new annotation conflicts.

5. Agent highlights knock‑on effects:

   • “Unfusing loops may disable vectorization; here’s the affected loop.”

6. Programmer accepts or iterates.

5.2 Conflict resolution

When an annotation is impossible:

• Compiler: Rejects the program and marks the conflicting region.
• Agent: Explains:
  • the failing annotation,
  • the dependency chain,
  • possible fixes (e.g., remove @stack, add @noescape, introduce a region).

This keeps the system sound while still being negotiable.

---

6. Example scenario

6.1 Source sketch

@soa
struct Particle {
  position: Vec3,
  velocity: Vec3,
}

@pure
fn update(@noalias particles: &mut [Particle]) {
  for p in particles {
    p.position += p.velocity;
  }
}

6.2 Compiler’s initial plan

• Use SoA layout for Particle.
• Inline update into hot call sites.
• Vectorize the loop.
• Allocate particles in a region tied to the simulation frame.

6.3 Programmer adds a constraint

@stack
fn simulate_frame() {
  let particles = make_particles(); // large array
  update(&mut particles);
  render(&particles);
}

6.4 Constraint failure

• @stack on particles conflicts with:
  • its size (too large for stack) or
  • its lifetime (if it escapes) or
  • region strategy (if region is required).

Error:

@stack allocation for particles is impossible.
Reason: particles is passed to render, which may store it beyond simulate_frame.
Options:

• Remove @stack and allow region/heap allocation.
• Mark render so that it cannot retain particles (@noescape on parameter).
• Introduce a frame‑region and use @region("frame") instead of @stack.

The programmer can then refine the design explicitly.

---

7. Open design questions

• Annotation granularity:
  How fine‑grained should annotations be (per value, per field, per function, per module)?
• Default policy:
  How much can the compiler do “well enough” without annotations, while still being explainable?
• Annotation ergonomics:
  How to avoid annotation bloat while still enabling precise control where needed?
• Performance modeling:
  How should the system surface performance tradeoffs (e.g., estimated cache misses, allocations, branch mispredicts)?
• Agent protocol:
  What is the minimal, compositional vocabulary for the agent to explain constraints and tradeoffs?

---

8. Summary

This design treats compilation as:

• A constraint‑driven transformation from high‑level semantics to low‑level implementation.
• A collaboration between programmer, compiler, and agent.
• A space of explicit, explainable choices, not opaque heuristics.

Annotations are hard, checkable contracts.
Dials are soft, steerable preferences.
The constraint graph is the shared object of reasoning.

 

self defeating

good thing all the ai tools that probably were somewhat developed using ai tools all have just terribly bad UX. 

trekkers

ST:TNG was the last good ST. 

things seem to have gotten exponentially worse thereafter. 

dd-wrt

well now, the QoS UX is dog shyte! impressive. i should find the time to get an AI agent to tell me how to make and contribute a patch...

law of the executed middle

you're either with us

or against us. 

now that's what i call logic. 

dumb all the way down

the only thing dumber than the Snowpiercer movie would be to turn it i to a long tv series. 

oh, wait!