Stack-Based Implementation Guidelines

# Stack-Based Implementation Guidelines

## Invocation

This guideline captures what should be implemented, enforced, and tested based on the stack as it exists now.

The immediate pressure came from the migration of `ruby.priority` into `topaz.priority`, but the deeper law is larger:

**the stack must express gem canon truthfully, and implementation must follow that truth without ambiguity.**

This is not only a data migration concern. It is a query concern, a display concern, a creation concern, a compatibility concern, and a future validation concern.

---

## Core Law

**Gem meaning is fixed.** Implementation must not casually blur semantic ownership across gems.

Current working law:

- **onyx** → name - **sapphire** → archetype / kind - **pearl** → body / content - **ruby** → classification / tags / status-like non-numeric metadata - **topaz** → numeric measurements and quantities - **amethyst** → access / visibility - **obsidian** → relationships - **diamond** → provenance - **emerald** → timestamps / time - **citrine** → locality / realm / host / path

That means: - `priority` belongs in **topaz** - `loc_estimate` belongs in **topaz** - `byte_weight` belongs in **topaz** - `ip`, `ssh_host`, and similar location-bearing values belong in **citrine** - `status` remains in **ruby**

---

## Guideline I — All New Writes Must Follow Canon

Creation paths must write new fields into the correct gem on first creation.

This means:

- no new code should write numeric operational values into `ruby` - creation helpers should place numeric values directly into `topaz` - locality-bearing fields should be written into `citrine` - relation-bearing fields should be written into `obsidian`

This applies to: - gap creation - route creation - node creation - mesh/forest records - atlas/material/object Things - any new Thing categories introduced later

**Implementation rule:** New code should never rely on future migration to fix bad gem placement.

---

## Guideline II — Reads Must Be Backward-Compatible During Migration

Where historical data exists in the wrong gem, reads should temporarily support both the canonical and legacy field locations.

The pattern is:

- read canonical location first - fall back to legacy location - present one coherent value to the user/system

Example shape:

- `topaz.priority` first, fallback to `ruby.priority` - `topaz.byte_weight` first, fallback to `ruby.byte_weight`

This should remain in place only while migration is incomplete or old data still exists.

**Implementation rule:** Use compatibility reads as a bridge, not a permanent excuse for drift.

---

## Guideline III — Ordering, Ranking, and Selection Must Use Canonical Fields

Anything that sorts, ranks, filters, or prioritizes Things must read from the correct gem.

That includes:

- forge gap ordering - stem queries - route priority ordering - pending work ranking - future atlas/material/object selection logic - any UI or world-system that ranks by priority, cost, density, or magnitude

If the meaning is numeric, the primary source must be **topaz**.

**Implementation rule:** Ordering logic is ontology made executable. If ordering reads the wrong gem, the system is lying.

---

## Guideline IV — Display Layers Must Reflect Canon Without Breaking Old Data

All display paths should be updated to present canonical fields while still tolerating older bodies.

This includes:

- forge displays - add/success summaries - query results - status views - diagnostic screens - future Portal/Web and 3D views

The user should see the correct value regardless of whether the Thing has already been migrated.

**Implementation rule:** Do not let the interface become a second schema.

---

## Guideline V — Migrations Must Be Paired

A real migration is not only data.

A complete migration must include:

1. **data migration** 2. **query migration** 3. **write-path migration** 4. **display migration** 5. **help/docs/example migration** 6. **test migration**

If one of these is skipped, the migration is incomplete.

The recent priority move showed this clearly: - database rows were updated - code references were found - ordering logic was fixed - creation logic was corrected - display reads were updated - help text was adjusted

That is the minimum proper shape.

**Implementation rule:** Never call a migration done because the database changed.

---

## Guideline VI — Query and Help Surfaces Must Teach Canon

User-facing query examples, help text, and docs must reinforce the real gem locations.

If examples still teach: - `ruby.priority` when the system now expects: - `topaz.priority`

then the documentation becomes a source of corruption.

This applies to: - CLI help - forge help - scrolls and FIDs when they speak concretely - Portal query builders - future onboarding surfaces

**Implementation rule:** Examples are schema pressure. Treat them as part of implementation.

---

## Guideline VII — Types Should Acquire Chord Profiles

Each `sapphire` type should gradually develop an expected **gem chord profile**.

Not a rigid prison at first, but a known pattern:

- dominant gems - expected gems - optional gems - suspiciously absent gems

For example:

### Gap Thing Likely heavy in: - `onyx` - `sapphire` - `pearl` - `ruby.status` - `topaz.priority` - `topaz.loc_estimate` - `topaz.byte_weight` - `obsidian` links - `citrine` locality

### Node Thing Likely heavy in: - `onyx` - `sapphire` - `ruby` role/class - `citrine` host/network locality - `topaz` numeric ports/load/weights - `obsidian` peer/service links

This should eventually support: - validation - linting - migration hints - query optimization - display defaults

**Implementation rule:** Gem canon defines field meaning. Chord profiles define expected body shape.

---

## Guideline VIII — Validation Should Become System Truth

The stack should eventually enforce or at least warn on suspicious placement.

Examples:

- numeric fields found in `ruby` - locality fields found in `ruby` - timestamps outside `emerald` - host/path values outside `citrine` - relation lists outside `obsidian`

This should not begin as brittle refusal everywhere. It can begin as:

- warnings during creation - lint tools - diagnostic reports - migration suggestions - CI checks for core Things

**Implementation rule:** The ontology should be testable, not just discussable.

---

## Guideline IX — Load Pressure Should Be Measured Against Semantic Shape

Gem placement is not only neatness. It affects pressure.

Bad placement causes: - worse queries - inconsistent ordering - harder indexing - more complicated displays - more expensive migrations - weaker validation

So bottleneck testing should include semantic integrity checks, not only runtime speed.

Questions to ask:

- are topaz-heavy queries using topaz consistently? - are locality filters pulling from citrine consistently? - are relation traversals staying inside obsidian? - are displays composing one Thing body or compensating for schema drift?

**Implementation rule:** Semantic drift is a performance problem in slow motion.

---

## Guideline X — Compatibility Paths Must Have an End

Every fallback should imply a future cleanup target.

For example:

- support `ruby.priority` during transition - migrate all known records - remove legacy fallback once the body is clean - document the cutoff

Otherwise compatibility code becomes permanent rot.

**Implementation rule:** Backward compatibility is a bridge, not a homeland.

---

## Immediate Implementation List

Based on the current stack and migration direction, the following should be implemented or continued:

### 1. Canonical field ownership audit Audit common Things for obvious gem misplacements: - numeric values in ruby - locality in ruby - timestamps outside emerald - relation bodies outside obsidian

### 2. Chord profiles for major Thing kinds Start with: - gap - node - route - fid - ring - atlas/material/object-related Things - mesh/forest deployment Things

### 3. Read/write parity checks For each migrated field: - ensure creators write canonically - ensure readers prefer canonical fields - ensure displays show canonical values - ensure sort/order paths use canonical values

### 4. Query/help example cleanup Update examples and help text to teach real gem usage.

### 5. Migration registry Maintain a simple list of: - migrated fields - pending migrations - temporary fallbacks - removal targets

### 6. Validation/lint layer Add a lightweight validator for gem misuse by Thing type.

### 7. Bottleneck testing with semantic tracing When testing load, tag pressure by: - gem family - query type - traversal type - manifestation layer so bottlenecks can be tied back to semantic structure.

---

## Closing

The recent migration was not just cleanup.

It revealed the real law:

**implementation must serve the stack, not quietly redefine it.**

When the canon is correct and the code obeys it: - queries simplify - displays clarify - migrations shrink - validation becomes possible - load testing becomes more honest - the ontology begins to carry its own weight

That is the path worth keeping.