−
100%
+
fit
scroll
# 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.
△