@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.
- package/README.md +14 -8
- package/dist/architect.d.ts.map +1 -1
- package/dist/architect.js +6 -0
- package/dist/architect.js.map +1 -1
- package/dist/engine/helpers.d.ts +7 -0
- package/dist/engine/helpers.d.ts.map +1 -1
- package/dist/engine/helpers.js +29 -5
- package/dist/engine/helpers.js.map +1 -1
- package/dist/engine/index.d.ts.map +1 -1
- package/dist/engine/index.js +12 -6
- package/dist/engine/index.js.map +1 -1
- package/dist/engine/journal.d.ts +2 -1
- package/dist/engine/journal.d.ts.map +1 -1
- package/dist/engine/journal.js +66 -11
- package/dist/engine/journal.js.map +1 -1
- package/dist/engine/reads.d.ts.map +1 -1
- package/dist/engine/reads.js +4 -2
- package/dist/engine/reads.js.map +1 -1
- package/dist/engine/writes.d.ts.map +1 -1
- package/dist/engine/writes.js +11 -8
- package/dist/engine/writes.js.map +1 -1
- package/dist/instructions/manifest.d.ts.map +1 -1
- package/dist/instructions/manifest.js +4 -0
- package/dist/instructions/manifest.js.map +1 -1
- package/dist/maad-md.d.ts.map +1 -1
- package/dist/maad-md.js +2 -0
- package/dist/maad-md.js.map +1 -1
- package/dist/skill-files.d.ts.map +1 -1
- package/dist/skill-files.js +8 -0
- package/dist/skill-files.js.map +1 -1
- package/dist/skills/corpus-explorer.d.ts +2 -0
- package/dist/skills/corpus-explorer.d.ts.map +1 -0
- package/dist/skills/corpus-explorer.js +223 -0
- package/dist/skills/corpus-explorer.js.map +1 -0
- package/dist/skills/graph-ontology.d.ts +2 -0
- package/dist/skills/graph-ontology.d.ts.map +1 -0
- package/dist/skills/graph-ontology.js +253 -0
- package/dist/skills/graph-ontology.js.map +1 -0
- 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 @@
|
|
|
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.
|
|
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.
|
|
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.
|
|
54
|
+
"js-yaml": "~4.3.1",
|
|
55
55
|
"pino": "10.3.1",
|
|
56
56
|
"simple-git": "3.36.0"
|
|
57
57
|
},
|