Skip to content

Multiple hierarchies via schema composition - #122

Merged
mindsocket merged 2 commits into
mainfrom
feat/121-composed-hierarchies
Sep 27, 2026
Merged

mindsocket merged 2 commits into
mainfrom
feat/121-composed-hierarchies

Conversation

@mindsocket

@mindsocket mindsocket commented Sep 26, 2026 •

Copy link
Copy Markdown
Owner

Closes #121. This includes the explicit-imports design from the latest comment on #121. Follow-up work (plain allOf/$ref semantics, search paths, types arriving with imports) is tracked in #123.

Summary

A space can now have several hierarchies by composing schemas. Each schema still declares at most one hierarchy, but every imported schema contributes the hierarchy it declares as a separate named hierarchy. Previously the last provider won.

  • Naming. $metadata.hierarchy.name is optional and defaults to the declaring schema's file stem, so the bundled hierarchies are _ost_strict and _strategy_general. A duplicate name is an error unless the later hierarchy sets "override": true.
  • Main hierarchy.
    • If the root declares a hierarchy, that one is the main hierarchy.
    • If the root declares none and exactly one is imported, that one is the main hierarchy implicitly (strict_ost, strategy_general).
    • If several are imported, the root must select one with "hierarchy": { "$ref": "<schema $id>#/$metadata/hierarchy" }. Otherwise loading the schema fails.
    • Declaring a hierarchy and selecting one with $ref at the same time is an error.
    • A selection only applies when its schema is the root, so an imported schema is still usable standalone.
  • Each type belongs to at most one hierarchy. A type claimed by two hierarchies is an error.
  • Validation. Layering, parent-type, skip-level and orphan checks run per hierarchy, and allowSkipLevels is per hierarchy. A hierarchy edge whose parent belongs to a different hierarchy is reported as an invalid parent. Relationships still connect types across hierarchies.
  • Graph model. Hierarchy entries in resolvedParents carry hierarchy: <name>. Filter ancestors[]/descendants[] entries expose it as _hierarchy. A SpaceGraph is built for one selected hierarchy.
  • Rendering. show, diagram and render take --hierarchy <name>, defaulting to the main hierarchy. space_on_a_page parsing, hierarchy embedding and template-sync use the main hierarchy.
  • Explicit metadata imports.
    • $ref/$defs are now validation-only: an external $ref no longer makes the referenced schema a metadata provider.
    • Metadata travels only through $metadata.imports: ["<schema $id>", ...]. An import brings the whole schema's metadata and is transitive. Merge order is imports in order (depth-first), then the schema's own metadata last. Each schema is merged at most once, and an unresolvable import is an error.
    • One merge rule covers every key: a duplicate is an error unless the later entry sets override: true. Identities:
      • rules: id
      • relationships: parent + type + field
      • aliases: alias name. The override form is { "type": "<target>", "override": true } as the alias value.
      • hierarchies: name. Overriding by name is how a schema replaces an imported hierarchy's levels.
    • $ref rule imports inside $metadata.rules are removed. To share rules, import a rules-only schema.
    • Bundled strategy_general, strict_ost and knowledge_wiki gain imports lines.
  • Fixed the stale "error on multiple providers" note in docs/schema-dialect-update-proposal.md and the "layer 2 silently wins" comment in src/schema/schema.ts.

Docs (README, concepts, schemas, api), plugin skill references, bundled schema comments and the generated metaschema are updated to match.

Breaking changes

Schema format / composition

  • $ref no longer brings metadata. A schema that relied on $ref/allOf to pick up a partial's hierarchy, aliases, relationships or rules gets none until it lists the partial in $metadata.imports. All bundled root schemas are updated.
  • New $metadata.imports: string[]. An $id that doesn't resolve is an error.
  • $ref entries inside $metadata.rules (rule and rule-set imports) are removed, and the metaschema rejects them.
  • Aliases no longer shallow-merge with later-wins. A duplicate alias key is an error unless the later value is { "type": ..., "override": true }. Alias values may now be that object form.
  • Relationships no longer simply concatenate. A duplicate parent + type + field is an error unless the later one sets override: true (new field on relationships).
  • Rules: a duplicate id is now an error even when the two payloads are identical. Previously identical duplicates were tolerated. The error message changed from Conflicting rule "<id>" ... to Duplicate rule "<id>" found in "<a>" and "<b>". Set "override": true ....
  • Hierarchies: a duplicate name can be replaced with "override": true on the hierarchy (new field). This is the supported way to change an imported hierarchy's levels.
  • A schema's own hierarchy no longer silently overrides an imported one. Both are kept, and overlapping types are an error, unless the schema uses the same name with "override": true.
  • A root that imports two or more hierarchy-declaring schemas and declares none must now select one with hierarchy: { "$ref" }. Otherwise it fails to load.
  • $metadata.hierarchy is now oneOf a hierarchy declaration (with a new optional name) or a { "$ref" } selection. The generated metaschema has changed accordingly. { levels, $ref } together is rejected.
  • The error for an invalid level type now names the hierarchy: Hierarchy "<name>" level "<type>" is not a valid type ....

CLI output / behaviour

  • schemas show prints one hierarchy "<name>"[ (main)]: a → b line per hierarchy instead of hierarchy: a → b.
  • schemas show --mermaid-erd emits edges for every hierarchy.
  • With several hierarchies, show/diagram/render show only the main hierarchy as a tree. Types from other hierarchies are listed under "Other (not in hierarchy)" unless --hierarchy is given. Miro sync uses the main hierarchy.
  • validate reports orphans across all hierarchies. A hierarchy edge pointing to a node of another hierarchy's type is now a hierarchy violation; previously it was skipped.

JSON output / API / types

  • ResolvedParentRef gains hierarchy?: string, set on every hierarchy edge. This is visible in dump output and in filter predicates as _hierarchy.
  • SchemaMetadata.hierarchy is now Hierarchy ({ name, levels, allowSkipLevels? }), and name is required. There is a new SchemaMetadata.hierarchies: Hierarchy[] (all hierarchies, main included). Hierarchy is exported from structured-context/api.
  • SpaceGraph.levels is removed and replaced by SpaceGraph.hierarchy: Hierarchy | undefined. buildSpaceGraph(nodes, levels) becomes buildSpaceGraph(nodes, hierarchy). Render plugins that read graph.levels must use graph.hierarchy?.levels.
  • The SpaceGraph hierarchy views (hierarchyRoots, orphans, nonHierarchy, hierarchyChildren, hierarchyTitles) are scoped to the graph's hierarchy.
  • assembleSpaceGraph/loadSpaceGraph accept options.hierarchy. An unknown name throws Unknown hierarchy: "<name>". Available: ....
  • executeRender accepts options.hierarchy.
  • In the internal metadata contract, the RuleRef type is renamed MetadataRef (now used only by hierarchy selection), and the RuleEntry type is removed.

Tests

New tests cover:

  • two composed hierarchies plus a root-declared one
  • an implicit main hierarchy from a single contributed one
  • the default file-stem name
  • an error when several are contributed and none is selected
  • an explicit hierarchy: { "$ref" } selection, which also compiles
  • a $ref without an import brings no metadata
  • transitive imports, and import order with an alias and rule override
  • duplicate alias, relationship and rule errors
  • relationship override and hierarchy override by name
  • an error for a type in two hierarchies
  • an error when a hierarchy is both declared and $ref'd
  • per-hierarchy validation: edge naming, per-hierarchy allowSkipLevels, and a cross-hierarchy parent
  • --hierarchy rendering through executeRender, including an unknown name

bun run typecheck, bun run lint and bun run test (451 pass) all pass.

plugin/.claude-plugin/plugin.json was reformatted so that biome check passes. It already failed on main, and the pre-commit version sync bumped the plugin to 0.11.1.

https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi

Every $ref'd schema now contributes its declared hierarchy as a separate
named hierarchy instead of the last provider winning.

- $metadata.hierarchy gains an optional `name` (default: declaring file stem)
  and may be `{ "$ref": "<schema $id>#/$metadata/hierarchy" }` on the root to
  select the main hierarchy
- main hierarchy: root-declared, else the single contributed one, else the
  root's $ref selection; several contributed with none selected is an error,
  as is declaring and selecting at once
- a type in two hierarchies, or two hierarchies with the same name, is an error
- layering, parent-type, skip-level and orphan checks run per hierarchy
- hierarchy edges in resolvedParents carry the hierarchy name
- show/diagram/render take --hierarchy <name> (default: main hierarchy)
- SchemaMetadata gains `hierarchies`; SpaceGraph.levels becomes
  SpaceGraph.hierarchy; buildSpaceGraph takes a Hierarchy

Closes #121

Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi
- $metadata.imports (schema $ids) is the only way metadata travels; imports
  are whole-schema and transitive, merged depth-first in order, own metadata last
- external $ref / $defs no longer make the referenced schema a metadata provider
- one merge rule for rules (id), relationships (parent+type+field), aliases
  (name) and hierarchies (name): duplicate is an error unless the later entry
  sets override: true (aliases: { "type": ..., "override": true })
- remove $ref rule imports inside $metadata.rules
- bundled strategy_general, strict_ost and knowledge_wiki gain imports

Claude-Session: https://claude.ai/code/session_01EJgagmpxDYVYr7fp9C6cZi
@mindsocket
mindsocket force-pushed the feat/121-composed-hierarchies branch from 00f90c6 to 0c7deee Compare September 27, 2026 02:51
Repository owner deleted a comment from claude Bot Sep 27, 2026
Repository owner deleted a comment from claude Bot Sep 27, 2026
Repository owner deleted a comment from claude Bot Sep 27, 2026
Repository owner deleted a comment from claude Bot Sep 27, 2026
@claude

claude Bot commented Sep 27, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@mindsocket
mindsocket merged commit b588c82 into main Sep 27, 2026
3 checks passed
@mindsocket
mindsocket deleted the feat/121-composed-hierarchies branch September 27, 2026 04:55
mindsocket added a commit that referenced this pull request Oct 6, 2026
- Resolve plugin schemas synchronously via convention (<pluginRoot>/schemas/) without executing plugin code
- Support plugin-prefixed schema resolution (e.g. sctx-wardley-mapping/wardley_map.json)
- Index plugin partials (_*.json) under the sctx://<pluginName>/ URI namespace
- Enforce schema URI namespace constraints and collision detection across core, plugin, and local schemas
- Integrate plugin schemas into schema composition ($ref and $metadata.imports)

Addresses #88
Relates to #7, #17, #91, #97, #122
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Multiple hierarchies via schema composition

1 participant