zeekay
ad5a010f79
The same fact lived in nine hand-kept places and they disagreed about 58
proposals. This makes the file the only authority and everything else a
projection of it.
ONE VOCABULARY, in vocabulary.json, read by the lint, the generator and the
doc site. Three words, each answering "can I rely on this?" and nothing else:
Draft nothing implements it yet, or its own text says the work is ahead
Final the thing it specifies exists in the code
Living governance and process: amended in place, never finished
Eight spellings folded in. `Active` was the one doing real damage: on four Meta
and Process HIPs it meant living, on 48 others it meant shipped, and one word
doing two jobs is why nothing agreed. `Review` and `Last Call` described a
queue rather than a document, and a proposal under review is still one you
cannot build against.
STATUS IS EARNED, not declared. Every Standards Track proposal was checked
against the estate: 235 have their implementation, and eight do not and say so.
HIP-0095 carries a twelve-week plan ending at "mainnet launch" and has no code.
HIP-0525 specifies an all-machine meeting while apps/meet refuses a machine a
seat. HIP-0078 names a prover at a "planned location" that does not exist.
HIP-0114 is the cog.* procedure set, and that procedure set returns nothing.
HIP-0003, HIP-0102, HIP-0305 and HIP-0901 likewise: looked, found nothing.
SIXTEEN TOMBSTONES DELETED rather than statused. A dead document kept alive in
the index is one concept wearing two names. Each successor exists and carries
the text, and the 90 references that pointed at a tombstone now point at it --
whole markdown links at once, so link text cannot outlive its target. Three of
the sixteen were pure compatibility: HIP-0028 specified a migration off a
Bitnami chart, HIP-0029 dual-engine MySQL, HIP-0030 a schema-deprecation
policy. We ship no backwards compatibility, so we do not specify it.
Nine links were already broken and had been since the corpus was renumbered:
short-form ./hip-5.md paths that never existed. Two named the wrong proposal --
one cited "HIP-1: Hanzo Multimodal Models" where multimodal is HIP-0003.
THE GENERATOR REFUSES more often than it writes, because a short table looks
exactly as authoritative as a complete one. Rows must equal files; a shrinking
index must say by how much; a section whose input is missing is an error, not
an omission; nothing is written until all of it validates. Its self-test breaks
the corpus eleven ways and requires each to refuse AND leave README byte-
identical -- a guard that reports after half-writing has protected nothing.
The lint's second implementation of the same comparison is gone.
The site rendered 52 proposals with a fallback grey badge and counted them
toward none of its three stat tiles, because docs/lib/source.ts declared a
status union by hand: it admitted a `Stagnant` no file has ever carried and
omitted the one 52 files did. Five components each kept their own copy of the
colours. All six now read vocabulary.json.
5.3 KiB
hip, title, author, type, category, capability, status, created, requires
| hip | title | author | type | category | capability | status | created | requires |
|---|---|---|---|---|---|---|---|---|
| 1126 | Framework — The DocType Engine | Hanzo AI | Standards Track | Core | framework | Final | 2026-08-20 | HIP-0026, HIP-0106, HIP-0139 |
HIP-1126: Framework — The DocType Engine
Abstract
/v1/framework is document types an org defines: describe a record once — its
fields, naming rule, lifecycle, and which role may do what — then create, list,
submit and cancel documents against it. The engine is
github.com/hanzoai/framework, built on the metadata model
github.com/hanzoai/doctype; neither knows what HTTP is, and the cloud
subsystem at apps/framework is the adapter — the "place" in the engine's
layering (apps/framework/framework.go:6-14). This HIP states the store the
place opens, how a request becomes an engine caller, and the one surface that
cannot carry a schema.
Motivation
Several application lanes — cms, erp, help, knowledge, content, guide — each
need "a record type with permissions and a lifecycle". Building that per lane
is the same engine five times, drifting. The adapter re-exports the engine
vocabulary so every lane keeps one import and compiles unchanged
(apps/framework/framework.go:22-24), and the engine enforces permissions
itself, so there is no authorization logic here — a second copy would be a
second answer (apps/framework/framework.go:29-31).
Specification
The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as in RFC 2119.
§1 The store
framework owns one store: the engine's single database, opened by cloud's
storage policy — sqlpool.Open("framework", DataDir), encrypted at rest under
a KMS-held master key (apps/framework/framework.go:73-85). Cloud names the
file rather than accepting a path from the library, because a name is what
keys an encrypted file and a handed-down path cannot be. The rows inside are
per-org — every DocType and document belongs to the caller's org — with
isolation enforced by the engine's own permission calculus.
§2 The addresses
Every route is under /v1/framework (manifest/apps.go:180). DocType
definition, roles, modules, the summary, document reads, submit and cancel are
typed operations; the DELETEs answer no body and carry no response schema. The
two document writes — POST /v1/framework/{doctype} and
PUT /v1/framework/{doctype}/{name} — are raw handlers and MUST stay raw until
the registry can carry them honestly: their request body is the document's own
field data, a flat object whose properties the DocType defines at run time, and
no Go struct both accepts that body verbatim and describes it. A reflected
schema would name the two path segments and nothing else — an SDK method that
cannot send a document. The three registry properties required to convert them
are enumerated at the registration, and a test holds the refusal until all
three exist (apps/framework/framework.go:130-147).
§3 Tenancy
The bridge parks the validated identity facts on the subtree before any route
runs (apps/framework/framework.go:107), and each operation turns the
validated principal's org into an engine Caller
(apps/framework/framework.go:249, HIP-0026); what the identity boundary
refuses, this surface refuses. On a fresh org the first caller to administer
DocTypes is seeded as its System Manager, after which only a System Manager or
a platform admin may define (apps/framework/framework.go:395-399) — the
engine's calculus, not the adapter's.
§4 Money, events, telemetry
framework is free, in those words (plugin/framework/main.go:21, cloud.Free;
not in spend.go:275). It publishes no events on the bus, and emits nothing to
observability beyond the request span every route gets.
§5 Stage
framework is beta — the manifest row declares Stage: Beta
(manifest/apps.go:180), so it is reached by flag while the raw document
writes in §2 wait on the registry properties that can type them. It is the
data core the application lanes stand on, so ga is where it is headed; the
promotion is the one manifest edit HIP-0139 §8.4 names.
§6 Upstream
framework derives from no third-party code. Its engine and metadata model are
the Hanzo modules hanzoai/framework v0.1.0 and hanzoai/doctype v0.1.0,
which this package adapts and re-exports.
Rationale
Value / engine / place, rather than one HTTP-aware engine, is what keeps the permission calculus testable without a server and reusable by lanes that are not HTTP at all. The cost is an adapter whose whole job is translation — principal to Caller, engine Code to HTTP status — and that cost is paid once here instead of once per lane.
Security Considerations
The wrong implementation answers with another org's records or lets a non-manager redefine a type out from under its documents. Both gates are the engine's: the adapter contributes only the validated org, never a client-supplied one, and deliberately holds no authorization logic that could disagree with the engine's answer. The store is encrypted at rest, so a copy of the deployment's data directory does not yield the documents without the key service.
References
- HIP-0026 — Identity and Access Management
- HIP-0106 — Hanzo Plugin Contract
- HIP-0139 — Capability
Copyright
Released under CC0 1.0 Universal Public Domain Dedication.