Files

glm-5.1 67ccfbf928 docs: restructure architecture docs to flowgraph pattern

- Create decisions/ directory with 32 numbered ADRs (ADR-001 through ADR-032)
  extracted from inline DD/SD/ED/SE decision sections
- Create open-questions.md with 16 OQs organized by theme, cross-referenced
  to ADRs, with status tracking (resolved/open)
- Create README.md as architecture index with doc table, ADR table, and
  lifecycle status definitions (draft/reviewed/stable/deprecated)
- Replace inline decision sections in all spec docs with ADR reference tables
- Replace inline open questions with OQ references to centralized tracker
- Update frontmatter: metagraph-module.md, overview.md, sqlite-host.md → reviewed;
  schema-evolution.md and encrypted-data.md remain draft
- DD1-DD10 → ADR-009 through ADR-018
- D1-D8 → ADR-001 through ADR-008
- SD1-SD5 → ADR-019 through ADR-023 (SD5 folded into ADR-006/008)
- ED1-ED5 → ADR-023 through ADR-027
- SE1-SE5 → ADR-028 through ADR-032

2026-05-29 07:19:03 +00:00

1.1 KiB

Raw Permalink Blame History

ADR-014: Repository stores dereferenced entry schemas

Status

Accepted

Context

When a Module entry uses Module.Import(), the entry's JSON Schema embeds the referenced Module's $defs. For example, CallGraph importing FlowGraph.Import("CallStatus") includes all of FlowGraph's definitions in the JSON Schema output. Storing this in every node_types row would duplicate the entire referenced Module.

Decision

The repository layer stores dereferenced entry schemas — each node_types row gets its entry's resolved JSON Schema with just the transitive $defs it needs, not the entire importing Module's definitions. This avoids storage bloat and version coupling between packages.

Consequences

Each DB row stores 1–3 KB of JSON Schema (just its own entry + transitive refs)
A full graph type's schemas total ~10–50 KB in the DB, negligible compared to node/edge data
No version coupling — a FlowGraph version change doesn't require updating all CallGraph rows
moduleToDbSchema() performs the dereferencing at write time

References

metagraph-module.md

1.1 KiB Raw Permalink Blame History Unescape Escape