@maadb/core 0.14.0 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +14 -8
  2. package/dist/architect.d.ts.map +1 -1
  3. package/dist/architect.js +6 -0
  4. package/dist/architect.js.map +1 -1
  5. package/dist/engine/helpers.d.ts +7 -0
  6. package/dist/engine/helpers.d.ts.map +1 -1
  7. package/dist/engine/helpers.js +29 -5
  8. package/dist/engine/helpers.js.map +1 -1
  9. package/dist/engine/index.d.ts.map +1 -1
  10. package/dist/engine/index.js +12 -6
  11. package/dist/engine/index.js.map +1 -1
  12. package/dist/engine/journal.d.ts +2 -1
  13. package/dist/engine/journal.d.ts.map +1 -1
  14. package/dist/engine/journal.js +66 -11
  15. package/dist/engine/journal.js.map +1 -1
  16. package/dist/engine/reads.d.ts.map +1 -1
  17. package/dist/engine/reads.js +4 -2
  18. package/dist/engine/reads.js.map +1 -1
  19. package/dist/engine/writes.d.ts.map +1 -1
  20. package/dist/engine/writes.js +11 -8
  21. package/dist/engine/writes.js.map +1 -1
  22. package/dist/instructions/manifest.d.ts.map +1 -1
  23. package/dist/instructions/manifest.js +4 -0
  24. package/dist/instructions/manifest.js.map +1 -1
  25. package/dist/maad-md.d.ts.map +1 -1
  26. package/dist/maad-md.js +2 -0
  27. package/dist/maad-md.js.map +1 -1
  28. package/dist/skill-files.d.ts.map +1 -1
  29. package/dist/skill-files.js +8 -0
  30. package/dist/skill-files.js.map +1 -1
  31. package/dist/skills/corpus-explorer.d.ts +2 -0
  32. package/dist/skills/corpus-explorer.d.ts.map +1 -0
  33. package/dist/skills/corpus-explorer.js +223 -0
  34. package/dist/skills/corpus-explorer.js.map +1 -0
  35. package/dist/skills/graph-ontology.d.ts +2 -0
  36. package/dist/skills/graph-ontology.d.ts.map +1 -0
  37. package/dist/skills/graph-ontology.js +253 -0
  38. package/dist/skills/graph-ontology.js.map +1 -0
  39. package/package.json +3 -3
@@ -0,0 +1,223 @@
1
+ // ============================================================================
2
+ // Corpus Explorer skill — managed instruction generator (fully static).
3
+ // ============================================================================
4
+ export function generateCorpusExplorerSkill() {
5
+ return `# Mapping an Unfamiliar Project
6
+
7
+ > Managed by the MAADb engine — do not edit (changes block future refreshes).
8
+ > Project-specific corpus maps belong in \`_skills/local/corpus-map.md\`.
9
+ > Never append session notes to this skill file.
10
+
11
+ ## Purpose
12
+
13
+ You are an agent landing in a MAADB project you did not build and do not
14
+ know. This skill is a staged exploration protocol that takes you from zero
15
+ to a **written, typed map of the corpus** — what the record types are, how
16
+ they connect, how dense the graph is, where it is broken — using cheap,
17
+ bounded reads. The protocol front-loads index-backed tools and defers
18
+ full-body reads to the end, so orientation cost stays flat even on large
19
+ corpora.
20
+
21
+ Audience: any agent with reader access. The final stage writes one overlay
22
+ file, which needs writer access (skippable — report the map in chat instead).
23
+
24
+ ## When to load this skill
25
+
26
+ - First session in a project whose \`maad_summary\` you have never seen.
27
+ - You've been handed a task referencing types or records you can't place.
28
+ - Before proposing schema or convention changes to an inherited corpus —
29
+ map first, judge second.
30
+ - Periodically on long-lived projects, to refresh a stale corpus map.
31
+
32
+ If \`maad_summary\` shows an **empty** project, stop — this skill maps
33
+ existing data. Enter Architect mode instead (\`_skills/architect-core.md\`).
34
+
35
+ ## Ground rules
36
+
37
+ - **Never** map a corpus by listing or reading files directly — all reads go
38
+ through MCP tools, and the index is faster than you.
39
+ - Match read shape to need (\`hot\` → fields, \`warm\` → one section, \`cold\` →
40
+ full body). In this protocol, \`cold\` appears only in Stage 3, on a
41
+ handful of records.
42
+ - Everything you write into the map must be grounded in a tool result from
43
+ **this** session; counts you intend to publish go through
44
+ \`maad_verify mode=count\` first.
45
+ - Watch \`_meta.warnings[]\` on every response — orientation is exactly when
46
+ you want to notice degraded subsystems or drift signals early.
47
+
48
+ ## The protocol
49
+
50
+ Six stages. Each produces a section of the final map; you can stop early
51
+ and still hold a partial map (that's a feature — Stage 6 records what was
52
+ *not* explored, and a truncated map that says so is still trustworthy).
53
+
54
+ ### Stage 0 — Bind and capabilities
55
+
56
+ On multi-project servers: \`maad_projects\`, then \`maad_use_project\` (bindings
57
+ are fixed per session). Then \`maad_describe\`: project overview, stats, and
58
+ \`capabilities\` — notably whether relationship paths and semantic search are
59
+ available in this deployment, which decides your Stage 4 toolkit.
60
+
61
+ ### Stage 1 — Summary: the shape
62
+
63
+ \`maad_summary\` once. Extract into notes:
64
+
65
+ - Type inventory with counts — your candidate class list.
66
+ - Sample doc IDs per type — seeds for Stages 3–4.
67
+ - Warnings: broken refs and validation errors reported here are your first
68
+ hygiene signal; carry them to Stage 5, don't chase them yet.
69
+
70
+ Ask whether the project already has orientation overlays — via
71
+ \`maad_describe\` / summary warnings, or by reading known managed paths
72
+ through tools when the deployment exposes them (\`MAAD.md\`,
73
+ \`_skills/local/corpus-map.md\`, \`_skills/local/ontology.md\`). An existing
74
+ local overlay changes your job from *mapping* to *verifying and updating
75
+ a map*. Do not walk the project tree on disk.
76
+
77
+ ### Stage 2 — Schema: the intended graph
78
+
79
+ For each type from Stage 1: \`maad_schema <type>\`. Build two tables as you
80
+ go:
81
+
82
+ 1. **Type table** — required fields, enums (the project's controlled
83
+ vocabularies), indexed fields (what the project's builders expected to
84
+ query — intent fossilized in config).
85
+ 2. **Edge table** — every \`ref\` / \`list[ref]\` field: source type, field
86
+ name, target type. This is the **intended** graph, before you've looked
87
+ at a single record.
88
+
89
+ Note the file-strategy signal: types whose records are few but block-heavy
90
+ are transaction-pattern (entries appended under parents — see
91
+ \`_skills/schema-guide.md\`); their real "record count" is blocks, not files,
92
+ and their parent ref is usually the corpus's highest-volume edge.
93
+
94
+ ### Stage 3 — Samples: the actual records
95
+
96
+ Per type, cheapest first:
97
+
98
+ - \`maad_get <sample-id> hot\` on 1–2 samples — do real records fill the
99
+ schema's fields? Sparse optional fields here foreshadow a sparse graph.
100
+ - \`maad_query\` with a projection of 3–4 key fields, small limit — the
101
+ spread, not just the sample (status distributions, date ranges).
102
+ - \`maad_get <id> cold\` on **one or two** records total, for narrative
103
+ texture: are bodies annotated (\`[[type:value|label]]\`)? Do they name
104
+ other records in prose?
105
+ - \`maad_search primitive=entity limit=20\` (then other primitives that the
106
+ domain suggests) — is the annotation layer in active use, and with which
107
+ subtypes? Remember frontmatter string fields index as \`primitive=entity,
108
+ subtype=<field-name>\`, so search results mix field values and body
109
+ annotations; the subtype tells you which.
110
+ - Where \`maad_describe\` said semantic search is enabled,
111
+ \`maad_semantic_search\` with 2–3 domain phrases is a cheap probe for
112
+ themes the schema doesn't capture. Degraded responses say so — fall back
113
+ without guessing.
114
+
115
+ ### Stage 4 — Related and paths: the realized graph
116
+
117
+ Now compare the intended graph (Stage 2) with reality.
118
+
119
+ 1. **Measure edge usage with aggregates, not iteration.** For each edge in
120
+ the Stage 2 table: \`maad_aggregate docType=<source> groupBy=<ref-field>\`.
121
+ Group count ≈ how many distinct targets are actually referenced; a
122
+ near-empty result means a declared-but-unused edge. This also hands you
123
+ the **hubs** — target IDs with the largest groups.
124
+ 2. **Walk the hubs.** For the top 2–3 hubs: \`maad_related direction=both\`,
125
+ then
126
+
127
+ \`\`\`
128
+ maad_relationship_paths
129
+ startDocId: <hub>
130
+ direction: both
131
+ maxDepth: 2
132
+ \`\`\`
133
+
134
+ Organize by \`nodes[].distance\`. Check \`truncation.truncated\` /
135
+ \`limitsReached\` before concluding anything about reach — a truncated
136
+ traversal is a lower bound.
137
+ 3. **Probe the observed-vs-intended gap.** Re-run one hub's paths with
138
+ \`extractionKinds: ["ref", "mention"]\`. Many \`mention\` edges beyond the
139
+ \`ref\` edges = structure living in prose = densification opportunity
140
+ (that's the graph/ontology skill's Recipe 4 — record it, don't fix it
141
+ mid-mapping). Few mentions *and* few refs on a corpus whose bodies
142
+ clearly name other records (Stage 3) = links invisible to tooling
143
+ entirely; note that too.
144
+ 4. Cross-type detail questions that surface here ("which open cases belong
145
+ to which client industry?") are \`maad_join\` / ref-chain
146
+ \`maad_aggregate\` one-liners — use them to spot-check, resist per-record
147
+ loops.
148
+
149
+ ### Stage 5 — Integrity: where the graph is broken
150
+
151
+ - \`maad_find_orphans\` — per-record broken-ref inventory (which ref fields
152
+ point at nonexistent targets).
153
+ - \`maad_verify mode=integrity\` — the wider sweep (index/document drift,
154
+ schema drift) — cheap insurance that what you just mapped is what's
155
+ actually on disk, especially if the project sees external edits.
156
+
157
+ Findings go **in the map**, not into ad-hoc repair: repair tools follow
158
+ dry-run-then-confirm contracts and deserve a deliberate pass, and on
159
+ read-only deployments mutation isn't yours to do (\`READ_ONLY\` — report,
160
+ don't retry).
161
+
162
+ ### Stage 6 — Write the typed map
163
+
164
+ Deliverable: \`_skills/local/corpus-map.md\` — a project-owned overlay file
165
+ (engine refresh never touches it). Create or update; if one existed
166
+ (Stage 1), preserve its history notes and update the snapshot. Suggested
167
+ shape:
168
+
169
+ \`\`\`markdown
170
+ # Corpus Map — <project> (as of <date>)
171
+
172
+ ## Types
173
+ | type | count* | pattern | purpose (one line) | key fields |
174
+
175
+ ## Edges (intended vs realized)
176
+ | ref field | source → target | declared | usage (aggregate) | mention overflow? |
177
+
178
+ ## Annotation practice
179
+ Primitives/subtypes in active use; whether doc-ID mentions are annotated.
180
+
181
+ ## Hubs
182
+ Top hub records and what clusters around them (path-walk findings).
183
+
184
+ ## Hygiene
185
+ Broken refs / orphans / drift found in Stage 5. Unfixed — inventory only.
186
+
187
+ ## Not explored
188
+ Types sampled shallowly, truncated traversals, stages skipped.
189
+
190
+ ## Open questions
191
+ Anything the corpus couldn't answer about itself.
192
+
193
+ *counts verified via maad_verify mode=count on <date>
194
+ \`\`\`
195
+
196
+ The map is a **snapshot of project truth, owned by the project** — exactly
197
+ what \`_skills/local/\` is for. It is not engine documentation; never put
198
+ engine-version facts in it (they rot — \`MAAD.md\` owns those).
199
+
200
+ If you lack writer access, deliver the same content as your session report.
201
+
202
+ ## After the map — handoffs
203
+
204
+ - Sparse realized graph, rich mention/prose links → load the
205
+ graph/ontology skill (\`_skills/graph-ontology.md\`) and run its
206
+ densification recipe against the map's "mention overflow" column.
207
+ - Schema gaps or evolution needs → Architect mode
208
+ (\`_skills/architect-core.md\` + \`_skills/schema-guide.md\`).
209
+ - Broken refs / drift → a deliberate hygiene pass with the repair tools'
210
+ dry-run contracts; the map's Hygiene section is its worklist.
211
+
212
+ ## Non-goals / hand off to the host
213
+
214
+ - No visualization: the map is markdown tables. Rendering it as an
215
+ interactive graph or dashboard is host-side work — never engine core.
216
+ - No repair during mapping — inventory only (Stage 5).
217
+ - No schema edits during mapping — the map may *recommend*; Architect
218
+ executes.
219
+ - No file-system spelunking — if a question can't be answered through the
220
+ tool surface, that inability is itself a finding for the map.
221
+ `;
222
+ }
223
+ //# sourceMappingURL=corpus-explorer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"corpus-explorer.js","sourceRoot":"","sources":["../../src/skills/corpus-explorer.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,wEAAwE;AACxE,+EAA+E;AAE/E,MAAM,UAAU,2BAA2B;IACzC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwNR,CAAC;AACF,CAAC"}
@@ -0,0 +1,2 @@
1
+ export declare function generateGraphOntologySkill(): string;
2
+ //# sourceMappingURL=graph-ontology.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"graph-ontology.d.ts","sourceRoot":"","sources":["../../src/skills/graph-ontology.ts"],"names":[],"mappings":"AAIA,wBAAgB,0BAA0B,IAAI,MAAM,CAwPnD"}
@@ -0,0 +1,253 @@
1
+ // ============================================================================
2
+ // Graph / Ontology skill — managed instruction generator (fully static).
3
+ // ============================================================================
4
+ export function generateGraphOntologySkill() {
5
+ return `# Working the Project as a Typed Graph
6
+
7
+ > Managed by the MAADb engine — do not edit (changes block future refreshes).
8
+ > Project-specific ontology conventions belong in \`_skills/local/ontology.md\`.
9
+ > Findings and densification notes go there too — never append them to this file.
10
+
11
+ ## Purpose
12
+
13
+ You are an agent operating on a MAADB project. This skill teaches you to
14
+ treat the project as a **typed information graph**: to read structure that
15
+ already exists, to choose the right traversal tool for each question, and to
16
+ **densify** the graph — promoting links that live only in prose into typed,
17
+ queryable structure. The engine gives you bounded graph primitives; you are
18
+ the query planner and the ontologist.
19
+
20
+ Audience: any agent with at least reader access. Densification recipes
21
+ (Recipes 4–5) additionally need writer access and — for schema changes — the
22
+ Architect channel described in \`_skills/architect-core.md\`.
23
+
24
+ ## When to load this skill
25
+
26
+ - You need to answer connection questions: "how is X related to Y?",
27
+ "what depends on this record?", "walk the chain from case to industry."
28
+ - You are building a report or view that spans record types.
29
+ - You notice the project is **link-poor**: records reference each other in
30
+ body text but \`maad_related\` returns little — structure exists in prose
31
+ but not in the graph.
32
+ - You are establishing or extending naming/linking conventions for a project
33
+ (light ontology work).
34
+
35
+ For first-contact orientation in a project you don't know at all, load
36
+ \`_skills/corpus-explorer.md\` first — it ends where this skill begins.
37
+
38
+ ## The graph model — what an edge is
39
+
40
+ The engine derives edges from markdown; SQLite rows are derived data and
41
+ reindex rebuilds them. There are exactly two edge kinds:
42
+
43
+ 1. **\`ref\` edges** — frontmatter fields of type \`ref\` (or \`list\` with
44
+ \`item_type: ref\`). Typed by the **field name** (\`client\`, \`parent_case\`,
45
+ \`assigned_attorney\`). This is the *intentional* graph: schema-declared,
46
+ validated, queryable, joinable. Evidence origin is the field; source
47
+ line/block evidence is null.
48
+ 2. **\`mention\` edges** — inline annotations \`[[type:value|label]]\` whose
49
+ value is a doc ID with a registered prefix (e.g.
50
+ \`[[identifier:cli-001|the client]]\`). This is the *observed* graph:
51
+ extracted from prose, carrying line and block evidence, but not schema-
52
+ validated. Plain prose that names a record without an annotation creates
53
+ **no edge at all**.
54
+
55
+ The density gradient — prose → annotated mention → typed ref — is the core
56
+ of this skill. Each promotion step makes a link more queryable and more
57
+ verifiable.
58
+
59
+ ## Choosing the traversal tool
60
+
61
+ | Question shape | Tool | Why |
62
+ |---|---|---|
63
+ | "What touches this one record?" (1 hop) | \`maad_related\` | Cheapest neighborhood read; direction \`outgoing\` / \`incoming\` / \`both\` (default \`both\`) |
64
+ | "How does A connect to B?" / "what's within N hops?" / "show me the evidence" | \`maad_relationship_paths\` | Bounded multi-hop BFS, deterministic, cycle-safe, returns per-edge evidence and per-node distance |
65
+ | "Give me these fields from many records *and* their ref targets" | \`maad_join\` | One call instead of query → get → get (N+1) chains |
66
+ | "Roll up a metric across a ref hop" ("cases per client industry") | \`maad_aggregate\` with a ref-chain \`groupBy\` (\`"client->industry"\`) | Group-by resolves refs at query time; never iterate records to count |
67
+ | "Where is this record *mentioned* in prose?" | \`maad_search\` with \`primitive=identifier\` and \`value=<docId>\` (or \`primitive=entity\` + matching \`subtype\`), or \`maad_relationship_paths\` with \`extractionKinds: ["ref","mention"]\` | Mentions are opt-in on path traversal; search requires \`primitive\` and finds the raw extracted objects |
68
+
69
+ Two defaults that will bite you if unexamined:
70
+
71
+ - \`maad_related\` defaults to direction \`both\`; \`maad_relationship_paths\`
72
+ defaults to \`outgoing\`. When a path result looks mysteriously empty, check
73
+ direction first — dependency questions ("what refs this?") need
74
+ \`incoming\` or \`both\`.
75
+ - \`maad_relationship_paths\` traverses **\`ref\` edges only by default**.
76
+ Mentions are opt-in via \`extractionKinds: ["ref", "mention"]\`. If you are
77
+ probing the *observed* graph, you must opt in.
78
+
79
+ Bounds (validated, over-cap values are rejected, not clamped): \`maxDepth\`
80
+ default 2, cap 4 · \`maxNodes\` 50/100 · \`maxEdges\` 100/200 · \`maxPaths\`
81
+ 25/50. If a response trips the byte-size guard, narrow with \`fieldLabels\`
82
+ or \`extractionKinds\`, or lower the limits — don't retry as-is.
83
+
84
+ ## Recipes
85
+
86
+ ### Recipe 1 — Typed neighborhood of one record
87
+
88
+ Goal: everything structurally connected to \`cas-012\`, with meaning.
89
+
90
+ 1. \`maad_get cas-012 hot\` — its own typed fields.
91
+ 2. \`maad_related docId=cas-012 direction=both\` — 1-hop adjacency; note the
92
+ **field names** on each edge (they are your edge types).
93
+ 3. Where you need target detail for several neighbors of the same type,
94
+ don't loop \`maad_get\` — use \`maad_join\` on the source type with
95
+ \`refFields\` (Recipe 6).
96
+ 4. Only escalate to \`maad_relationship_paths\` if 1 hop is insufficient.
97
+
98
+ ### Recipe 2 — Connection between two specific records
99
+
100
+ Goal: does \`cas-012\` connect to \`con-007\`, and through what?
101
+
102
+ \`\`\`
103
+ maad_relationship_paths
104
+ startDocId: cas-012
105
+ targetDocId: con-007
106
+ direction: both
107
+ maxDepth: 3
108
+ \`\`\`
109
+
110
+ Read the result as claims with proof: each edge carries \`fieldLabel\`,
111
+ extraction kind, and canonical evidence (source line + block for mentions;
112
+ field origin for refs). When you report the connection, cite the doc IDs on
113
+ the path — and for mention-backed hops, treat the link as *observed, not
114
+ validated* and say so.
115
+
116
+ A \`state: missing\` node on a path is a **broken ref** — the edge exists but
117
+ the target doesn't. Report it (and see Recipe 7); missing targets are
118
+ terminal, so real connectivity may be wider than what a broken hop shows.
119
+
120
+ ### Recipe 3 — Bounded exploration outward from a hub
121
+
122
+ Goal: the working set within 2 hops of a central record.
123
+
124
+ \`\`\`
125
+ maad_relationship_paths
126
+ startDocId: cli-001
127
+ direction: both
128
+ maxDepth: 2
129
+ fieldLabels: [client, parent_case] # optional: only these edge types
130
+ \`\`\`
131
+
132
+ Use \`nodes[].distance\` to organize the result into rings. Check
133
+ \`truncation.truncated\` and \`limitsReached\` **before** summarizing — a
134
+ truncated traversal is a lower bound, not a census, and your summary must
135
+ say which limit was hit if one was.
136
+
137
+ ### Recipe 4 — Promote prose links to typed structure (densification)
138
+
139
+ Goal: links that exist only in narrative become schema-typed refs.
140
+
141
+ 1. **Find candidates.** Probe the observed graph:
142
+ \`maad_relationship_paths\` from key records with
143
+ \`extractionKinds: ["ref","mention"]\`, \`maxDepth: 1\` — every \`mention\`
144
+ edge is a candidate. Corpus-wide, \`maad_search\` with
145
+ \`primitive=identifier\` and \`value=<docId>\` (required \`primitive\` —
146
+ omit it and the call fails \`INVALID_PRIMITIVE\`) inventories where each
147
+ hub is mentioned. (Prose links with no annotation at all are invisible
148
+ to tools — surfacing those is judgment work while reading \`cold\` bodies.)
149
+ 2. **Decide if the link is structural.** Promote when the relationship is:
150
+ queried or filtered on; needed in joins/aggregates; integrity-relevant
151
+ (should break loudly if the target vanishes); or cardinality-stable
152
+ (every case has a client). Leave as mention/prose when it's incidental
153
+ commentary.
154
+ 3. **Type it.** If a suitable \`ref\` field exists in the schema, done. If
155
+ not, this is a schema change — an **additive** new \`ref\` field (with
156
+ \`target\` and \`index: true\`) via the Architect channel
157
+ (\`_skills/architect-core.md\`): registry/schema edits go through the
158
+ deployment's approved channel, then \`maad_reload\`. Never write schema
159
+ files through record tools.
160
+ 4. **Set the field.** \`maad_update\` per record (sequential; pass
161
+ \`expectedVersion\` when you hold a read), or \`maad_bulk_update\` for a
162
+ genuine batch. Keep the prose mention — you are adding structure, not
163
+ rewriting narrative.
164
+ 5. **Verify.** \`maad_related\` on a sample now shows the edge with the new
165
+ field label; \`maad_find_orphans docType=<type>\` catches typo'd targets
166
+ immediately.
167
+ 6. **Record the convention** in \`_skills/local/ontology.md\` (Recipe 5) so
168
+ the next agent types new records the same way.
169
+
170
+ ### Recipe 5 — Light ontology, MAADB-style
171
+
172
+ An ontology here is **conventions, not a reasoner**:
173
+
174
+ - **Classes** = registered doc types.
175
+ - **Typed predicates** = \`ref\` field names. Name them as relations
176
+ (\`parent_case\`, \`assigned_attorney\`), not generically (\`link1\`, \`related\`).
177
+ The field name is the only edge label the graph has — spend it well.
178
+ - **Controlled vocabularies** = \`enum\` fields.
179
+ - **Annotation vocabulary** = the 11 fixed primitives plus registry
180
+ \`extraction.subtypes\` (e.g. \`attorney: entity\`). Subtypes make
181
+ \`maad_search\` domain-aware without engine changes.
182
+
183
+ The ontology's *documentation* lives in \`_skills/local/ontology.md\` — a
184
+ project-owned overlay file you create and maintain (it survives engine
185
+ refreshes). Keep it short and normative: one table of types, one table of
186
+ ref fields with their meaning and cardinality, the subtype vocabulary, and
187
+ the annotation policy ("always annotate doc-ID mentions in prose as
188
+ \`[[identifier:<docId>|label]]\`" is the single highest-leverage rule, because
189
+ it feeds Recipe 4's candidate pipeline).
190
+
191
+ Schema *changes* implied by ontology work are Architect work — hand off to
192
+ \`_skills/architect-core.md\`; do not duplicate its channel rules here.
193
+
194
+ ### Recipe 6 — Cross-type reports and views
195
+
196
+ Row-level view ("open cases with client name and industry"):
197
+
198
+ \`\`\`
199
+ maad_join
200
+ docType: case
201
+ filters: { status: open }
202
+ refs: [client]
203
+ fields: [title, status, opened_at]
204
+ refFields: { client: [name, industry] }
205
+ \`\`\`
206
+
207
+ Rollup ("case count by client industry"):
208
+
209
+ \`\`\`
210
+ maad_aggregate
211
+ docType: case
212
+ groupBy: "client->industry"
213
+ filters: { status: open }
214
+ \`\`\`
215
+
216
+ Compose the two into a markdown report (summary table from \`aggregate\`,
217
+ detail table from \`join\`) and — if the report should persist — write it as a
218
+ record via \`maad_create\` in a report-ish doc type if the project has one.
219
+ Ground every number you state: \`maad_verify mode=count\` (or \`mode=field\`)
220
+ before presenting totals as fact. Rendering to anything richer than
221
+ markdown, and publishing anywhere, is host work (see Non-goals).
222
+
223
+ ### Recipe 7 — Graph hygiene
224
+
225
+ Run before *and* after densification passes:
226
+
227
+ - \`maad_find_orphans\` — records whose ref fields point at nonexistent
228
+ targets (broken refs, per-record detail).
229
+ - \`maad_verify mode=integrity\` — the broader sweep (index drift, schema
230
+ drift, broken refs) after pulls or external edits.
231
+ - \`maad_validate\` after any schema evolution — see \`_skills/schema-guide.md\`
232
+ § versioning for the migrate-or-grandfather discipline.
233
+
234
+ A densification pass that introduces broken refs has made the graph *worse*
235
+ — typed-but-wrong beats untyped only if you catch it, which is why Recipe 4
236
+ ends in \`maad_find_orphans\`.
237
+
238
+ ## Non-goals / hand off to the host
239
+
240
+ - **No visualization here.** Emitting a small inline Mermaid/DOT sketch in
241
+ chat from path output is fine as ordinary agent output; anything
242
+ interactive, rendered, served, or saved as an artifact belongs to
243
+ host-side skills — never to \`@maadb/core\`.
244
+ - **No query language.** You compose bounded primitives; there is no Cypher
245
+ and none is coming.
246
+ - **No inference engine.** Do not invent transitive/derived edges and
247
+ present them as data — a multi-hop path is evidence of connection, not a
248
+ new fact. If a derived relationship matters, promote it explicitly
249
+ (Recipe 4) so it becomes a real, validated edge.
250
+ - **No schema writes through record tools** — Architect channel only.
251
+ `;
252
+ }
253
+ //# sourceMappingURL=graph-ontology.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"graph-ontology.js","sourceRoot":"","sources":["../../src/skills/graph-ontology.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,yEAAyE;AACzE,+EAA+E;AAE/E,MAAM,UAAU,0BAA0B;IACxC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsPR,CAAC;AACF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@maadb/core",
3
- "version": "0.14.0",
3
+ "version": "0.15.1",
4
4
  "description": "Markdown As A Database — treats markdown as the canonical data store, builds a queryable index, and gives LLMs deterministic read/write access.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -48,10 +48,10 @@
48
48
  "node": ">=24.0.0"
49
49
  },
50
50
  "dependencies": {
51
- "@modelcontextprotocol/sdk": "1.29.0",
51
+ "@modelcontextprotocol/sdk": "1.30.0",
52
52
  "better-sqlite3": "12.11.1",
53
53
  "gray-matter": "~4.0.3",
54
- "js-yaml": "~4.3.0",
54
+ "js-yaml": "~4.3.1",
55
55
  "pino": "10.3.1",
56
56
  "simple-git": "3.36.0"
57
57
  },