@blockml/graph 0.9.1

package/blocks/org/blockml/bml/graph/capability/BuildIndex.bml

@@ -0,0 +1,41 @@
+<!--
+  Graph Capability — BuildIndex
+  FQN: org.blockml.bml.graph.capability.BuildIndex
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>BuildIndex</name>
+  <type>graphcap:BuildIndex</type>
+  <baseType>core:Capability</baseType>
+  <is>Build an in-memory graph index from the validate --all corpus</is>
+  <documentation>Calls bootstrapFullProjectRegistry, maps authored Block and Member nodes, and creates a Ladybug in-memory store. Does not write to disk.</documentation>
+  <references>
+    <see type="fwcap:BootstrapFullProjectRegistry" relation="SeeAlso" />
+    <see type="graphcap:RebuildIndex" relation="SeeAlso" />
+  </references>
+  <properties>
+    <options type="graph:GraphIndexOptions">
+      <documentation>options (optional).</documentation>
+    </options>
+    <result type="graph:BuildIndexResult">
+      <documentation>result (required).</documentation>
+    </result>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Descendants.bml

@@ -0,0 +1,43 @@
+<!--
+  Graph Capability — Descendants
+  FQN: org.blockml.bml.graph.capability.Descendants
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Descendants</name>
+  <type>graphcap:Descendants</type>
+  <baseType>core:Capability</baseType>
+  <is>Inverse BASE_TYPE walk</is>
+  <documentation>Only BASE_TYPE. Default depth 16.</documentation>
+  <references>
+    <see type="graphcap:Ancestors" relation="SeeAlso" />
+  </references>
+  <properties>
+    <fqn type="type:Text">
+      <documentation>Block FQN. (required)</documentation>
+    </fqn>
+    <depth type="type:Integer">
+      <documentation>Max hops (optional).</documentation>
+    </depth>
+    <nodes type="graph:GraphNode[]">
+      <documentation>Descendant blocks. (required)</documentation>
+    </nodes>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Members.bml

@@ -0,0 +1,37 @@
+<!--
+  Graph Capability — Members
+  FQN: org.blockml.bml.graph.capability.Members
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Members</name>
+  <type>graphcap:Members</type>
+  <baseType>core:Capability</baseType>
+  <is>Authored members plus inherited view</is>
+  <documentation>HAS_MEMBER on the block plus BASE_TYPE ancestors and CONTRACT owners. inheritedFrom is set for inherited members; those edges are not stored on the child. BASE_TYPE is the resolved parent only — generic arguments on baseType are not ancestors. SubBlock members are not listed on the parent.</documentation>
+  <properties>
+    <fqn type="type:Text">
+      <documentation>Block FQN. (required)</documentation>
+    </fqn>
+    <members type="graph:GraphMember[]">
+      <documentation>Members. (required)</documentation>
+    </members>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Neighbors.bml

@@ -0,0 +1,53 @@
+<!--
+  Graph Capability — Neighbors
+  FQN: org.blockml.bml.graph.capability.Neighbors
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Neighbors</name>
+  <type>graphcap:Neighbors</type>
+  <baseType>core:Capability</baseType>
+  <is>Union of uses and usedBy</is>
+  <documentation>Authored environment of a block, both directions. Default depth 1. depth n is an undirected walk of n hops. CLI --origin, --relation, and --limit filter the result list.</documentation>
+  <references>
+    <see type="graphcap:Uses" relation="SeeAlso" />
+    <see type="graphcap:UsedBy" relation="SeeAlso" />
+  </references>
+  <properties>
+    <fqn type="type:Text">
+      <documentation>Block FQN. (required)</documentation>
+    </fqn>
+    <depth type="type:Integer">
+      <documentation>Undirected hops. Default 1. (optional)</documentation>
+    </depth>
+    <origin type="type:Text">
+      <documentation>Keep neighbors whose node.origin is listed. Comma-separated. (optional)</documentation>
+    </origin>
+    <relation type="type:Text">
+      <documentation>Keep neighbors whose relation is listed. Comma-separated. (optional)</documentation>
+    </relation>
+    <limit type="type:Integer">
+      <documentation>Max neighbors after filters. (optional)</documentation>
+    </limit>
+    <neighbors type="graph:GraphNeighbor[]">
+      <documentation>Neighbors. (required)</documentation>
+    </neighbors>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/OpenIndex.bml

@@ -0,0 +1,40 @@
+<!--
+  Graph Capability — OpenIndex
+  FQN: org.blockml.bml.graph.capability.OpenIndex
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>OpenIndex</name>
+  <type>graphcap:OpenIndex</type>
+  <baseType>core:Capability</baseType>
+  <is>Load a ready graph index or rebuild when missing or stale</is>
+  <documentation>Load a ready index or rebuild when missing or stale. The Ladybug database is exclusive; openGraph waits on an index lock if another process holds the graph, then loads or rebuilds. close() releases the lock.</documentation>
+  <references>
+    <see type="graphcap:RebuildIndex" relation="SeeAlso" />
+  </references>
+  <properties>
+    <options type="graph:GraphIndexOptions">
+      <documentation>options (optional).</documentation>
+    </options>
+    <result type="graph:BuildIndexResult">
+      <documentation>result (required).</documentation>
+    </result>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Path.bml

@@ -0,0 +1,43 @@
+<!--
+  Graph Capability — Path
+  FQN: org.blockml.bml.graph.capability.Path
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Path</name>
+  <type>graphcap:Path</type>
+  <baseType>core:Capability</baseType>
+  <is>Shortest authored path between two blocks</is>
+  <documentation>Walks outgoing authored edges only (the same direction as uses), including HAS_MEMBER and MEMBER_TYPE so provenance is preserved. Incoming edges are used-by, not path. Each hop is a GraphNeighbor with direction outgoing.</documentation>
+  <properties>
+    <from type="type:Text">
+      <documentation>Start FQN. (required)</documentation>
+    </from>
+    <to type="type:Text">
+      <documentation>End FQN. (required)</documentation>
+    </to>
+    <depth type="type:Integer">
+      <documentation>Max hops (optional).</documentation>
+    </depth>
+    <path type="graph:GraphPath">
+      <documentation>Path or absent. (optional)</documentation>
+    </path>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Query.bml

@@ -0,0 +1,43 @@
+<!--
+  Graph Capability — Query
+  FQN: org.blockml.bml.graph.capability.Query
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Query</name>
+  <type>graphcap:Query</type>
+  <baseType>core:Capability</baseType>
+  <is>Cypher escape hatch over the authored graph</is>
+  <documentation>Executes parameterized Cypher against the Ladybug store. Engine types are not part of the public API. Call schema() first: Ladybug is a Cypher subset — no type(), no shortestPath(). Example is on GraphSchema.example.</documentation>
+  <references>
+    <see type="graphcap:Schema" relation="SeeAlso" />
+  </references>
+  <properties>
+    <cypher type="type:Text">
+      <documentation>Cypher statement. (required)</documentation>
+    </cypher>
+    <params type="type:Text">
+      <documentation>JSON parameters (optional).</documentation>
+    </params>
+    <result type="graph:GraphQueryResult">
+      <documentation>Tabular result. (required)</documentation>
+    </result>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/RebuildIndex.bml

@@ -0,0 +1,40 @@
+<!--
+  Graph Capability — RebuildIndex
+  FQN: org.blockml.bml.graph.capability.RebuildIndex
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>RebuildIndex</name>
+  <type>graphcap:RebuildIndex</type>
+  <baseType>core:Capability</baseType>
+  <is>Full rebuild and persist of the graph index</is>
+  <documentation>Deletes .blockml/graph/lbug and rebuilds authored nodes and edges, then writes manifest.json. Waits on the same exclusive index lock as OpenIndex so two processes cannot rebuild or query concurrently.</documentation>
+  <references>
+    <see type="graphcap:BuildIndex" relation="SeeAlso" />
+  </references>
+  <properties>
+    <options type="graph:GraphIndexOptions">
+      <documentation>options (optional).</documentation>
+    </options>
+    <result type="graph:BuildIndexResult">
+      <documentation>result (required).</documentation>
+    </result>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Schema.bml

@@ -0,0 +1,37 @@
+<!--
+  Graph Capability — Schema
+  FQN: org.blockml.bml.graph.capability.Schema
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Schema</name>
+  <type>graphcap:Schema</type>
+  <baseType>core:Capability</baseType>
+  <is>Stable node and relation documentation</is>
+  <documentation>Returns node table names, authored relation names, a prose description, and a Ladybug Cypher example. Description names the supported subset (MATCH/WHERE/RETURN/ORDER BY/LIMIT, named relations, $params) and what is missing (type(), shortestPath()).</documentation>
+  <properties>
+    <schema type="type:Text">
+      <documentation>Schema description. (required)</documentation>
+    </schema>
+    <example type="type:Text">
+      <documentation>Minimal working Cypher. (required)</documentation>
+    </example>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/UsedBy.bml

@@ -0,0 +1,52 @@
+<!--
+  Graph Capability — UsedBy
+  FQN: org.blockml.bml.graph.capability.UsedBy
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>UsedBy</name>
+  <type>graphcap:UsedBy</type>
+  <baseType>core:Capability</baseType>
+  <is>Incoming authored block-level references</is>
+  <documentation>Inverse of Uses. Default depth 1. depth n walks n incoming hops; further hops set GraphNeighbor.source. CLI --origin, --relation, and --limit filter the result list (comma-separated origin/relation; limit is a cap after filtering).</documentation>
+  <references>
+    <see type="graphcap:Uses" relation="SeeAlso" />
+  </references>
+  <properties>
+    <fqn type="type:Text">
+      <documentation>Block FQN. (required)</documentation>
+    </fqn>
+    <depth type="type:Integer">
+      <documentation>Incoming hops. Default 1. (optional)</documentation>
+    </depth>
+    <origin type="type:Text">
+      <documentation>Keep neighbors whose node.origin is one of workspace, dependency, unresolved. Comma-separated. (optional)</documentation>
+    </origin>
+    <relation type="type:Text">
+      <documentation>Keep neighbors whose relation is listed. Comma-separated GraphRelation names. (optional)</documentation>
+    </relation>
+    <limit type="type:Integer">
+      <documentation>Max neighbors after filters. (optional)</documentation>
+    </limit>
+    <neighbors type="graph:GraphNeighbor[]">
+      <documentation>Incoming neighbors. (required)</documentation>
+    </neighbors>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/capability/Uses.bml

@@ -0,0 +1,49 @@
+<!--
+  Graph Capability — Uses
+  FQN: org.blockml.bml.graph.capability.Uses
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Uses</name>
+  <type>graphcap:Uses</type>
+  <baseType>core:Capability</baseType>
+  <is>Outgoing authored block-level references</is>
+  <documentation>Default depth 1 is one hop: BASE_TYPE, CONTRACT, HAS_SUBBLOCK plus types of authored members. via names the member. depth n walks n outgoing hops; further hops set GraphNeighbor.source to the block that owns the edge. CLI --origin, --relation, and --limit filter the result list.</documentation>
+  <properties>
+    <fqn type="type:Text">
+      <documentation>Block FQN. (required)</documentation>
+    </fqn>
+    <depth type="type:Integer">
+      <documentation>Outgoing hops. Default 1. (optional)</documentation>
+    </depth>
+    <origin type="type:Text">
+      <documentation>Keep neighbors whose node.origin is listed. Comma-separated. (optional)</documentation>
+    </origin>
+    <relation type="type:Text">
+      <documentation>Keep neighbors whose relation is listed. Comma-separated. (optional)</documentation>
+    </relation>
+    <limit type="type:Integer">
+      <documentation>Max neighbors after filters. (optional)</documentation>
+    </limit>
+    <neighbors type="graph:GraphNeighbor[]">
+      <documentation>Outgoing neighbors. (required)</documentation>
+    </neighbors>
+  </properties>
+</block>

package/blocks/org/blockml/bml/graph/documentation/ArchitectureOverview.bml

@@ -0,0 +1,39 @@
+<!--
+  Graph Documentation — ArchitectureOverview
+  FQN: org.blockml.bml.graph.documentation.ArchitectureOverview
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>ArchitectureOverview</name>
+  <type>graphdocumentation:ArchitectureOverview</type>
+  <baseType>core:Documentation</baseType>
+  <is>Corpus to index to Graph API</is>
+  <documentation>BML files → bootstrapFullProjectRegistry → TypeRegistry → authored Block/Member nodes and edges → Ladybug store → .blockml/graph/ cache → Graph API.
+
+    Graph corpus == validate --all corpus. Index is a derived cache; BML remains source of truth.
+
+    Only authored edges are stored. Transitive relations are computed by traversals.
+    BASE_TYPE is the resolved parent Block, not generic arguments on the baseType expression. Generic arguments may appear as HAS_SUBBLOCK when they are nested SubBlocks.
+    Persistence: .blockml/graph/lbug plus manifest.json (package.json/lockfile hashes, indexed file mtimes). Missing or stale index → full rebuild.
+    Ladybug is exclusive. openGraph/rebuildIndex take .blockml/graph/index.lock until close() and retry if the database file is locked.</documentation>
+  <references>
+    <see type="graphdocumentation:V1Scope" relation="ReadNext" />
+  </references>
+</block>

package/blocks/org/blockml/bml/graph/documentation/Introduction.bml

@@ -0,0 +1,37 @@
+<!--
+  Graph Documentation — Introduction
+  FQN: org.blockml.bml.graph.documentation.Introduction
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>Introduction</name>
+  <type>graphdocumentation:Introduction</type>
+  <baseType>core:Documentation</baseType>
+  <is>Purpose and scope of the Graph package</is>
+  <documentation>The @blockml/graph package provides a local authored structural graph over the effective BML corpus of a BlockML project. The corpus is the same set of documents bootstrapped by blockml validate --all.
+
+    This library (org.blockml.bml.graph.*) is the SSOT. TypeScript in packages/graph/src/ implements it. LadybugDB is an internal engine and is not part of the public API.
+
+    Consumers (CLI, agents) call BlockML-owned interfaces only.</documentation>
+  <references>
+    <see type="graphdocumentation:LayerSeparation" relation="ReadNext" />
+    <see type="fwcap:BootstrapFullProjectRegistry" relation="SeeAlso" />
+  </references>
+</block>

package/blocks/org/blockml/bml/graph/documentation/LayerSeparation.bml

@@ -0,0 +1,39 @@
+<!--
+  Graph Documentation — LayerSeparation
+  FQN: org.blockml.bml.graph.documentation.LayerSeparation
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>LayerSeparation</name>
+  <type>graphdocumentation:LayerSeparation</type>
+  <baseType>core:Documentation</baseType>
+  <is>Graph vs framework vs parser vs CLI</is>
+  <documentation>Layers:
+
+    org.blockml.bml.graph.* (@blockml/graph) — authored graph mapping, Ladybug index, persistence, semantic API, Cypher query.
+    @blockml/framework — Discovery and TypeRegistry bootstrap (bootstrapFullProjectRegistry).
+    @blockml/parser / @blockml/bom — Members, TypeExpressions, SourceLocation.
+    @blockml/cli — Human and --json CLI over this package.
+
+    Graph does not parse BML with a second XML/regex path. It does not own a separate corpus.</documentation>
+  <references>
+    <see type="graphdocumentation:ArchitectureOverview" relation="ReadNext" />
+  </references>
+</block>

package/blocks/org/blockml/bml/graph/documentation/PackageOwnership.bml

@@ -0,0 +1,36 @@
+<!--
+  Graph Documentation — PackageOwnership
+  FQN: org.blockml.bml.graph.documentation.PackageOwnership
+-->
+<block
+  xmlns="http://blockml.org/bml"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://blockml.org/bml https://blockml.org/schemas/bml.xsd
+                      "
+  xmlns:blockml="org.blockml.bml"
+  xmlns:bom="org.blockml.bml.bom"
+  xmlns:bomapi="org.blockml.bml.bom.api"
+  xmlns:bomcommon="org.blockml.bml.bom.common"
+  xmlns:bomdoc="org.blockml.bml.bom.document"
+  xmlns:core="org.blockml.bml.core"
+  xmlns:def="org.blockml.bml.definition"
+  xmlns:framework="org.blockml.bml.framework"
+  xmlns:fwcap="org.blockml.bml.framework.capability"
+  xmlns:graph="org.blockml.bml.graph"
+  xmlns:graphcap="org.blockml.bml.graph.capability"
+  xmlns:graphdocumentation="org.blockml.bml.graph.documentation"
+  xmlns:type="org.blockml.bml.type">
+
+  <name>PackageOwnership</name>
+  <type>graphdocumentation:PackageOwnership</type>
+  <baseType>core:Documentation</baseType>
+  <is>Toolchain responsibilities for Graph</is>
+  <documentation>@blockml/graph — index, persistence, semantic API, query API. Owns this BML library.
+
+    @blockml/framework — project discovery and TypeRegistry bootstrap (same corpus as validate --all).
+    @blockml/cli — blockml graph command host.
+    @blockml/bom — BlockDefinition members and SourceLocation.</documentation>
+  <references>
+    <see type="graphdocumentation:ScopeExclusions" relation="ReadNext" />
+  </references>
+</block>