@imunitic/synapse 0.4.6 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imunitic/synapse",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Memory for Claude Code, Codex CLI, and OpenCode: a durable markdown vault plus a per-repo code graph.",
   "repository": {
     "type": "git",
@@ -23,9 +23,9 @@
     "*.conf.template"
   ],
   "optionalDependencies": {
-    "@imunitic/synapse-darwin-arm64": "0.4.6",
-    "@imunitic/synapse-linux-x64": "0.4.6",
-    "@imunitic/synapse-linux-arm64": "0.4.6"
+    "@imunitic/synapse-darwin-arm64": "0.5.0",
+    "@imunitic/synapse-linux-x64": "0.5.0",
+    "@imunitic/synapse-linux-arm64": "0.5.0"
   },
   "license": "SEE LICENSE IN LICENSE"
 }

package/schema/graph-node/v1.yaml

@@ -0,0 +1,96 @@
+# Declared keys are the full v1 spec; enforcement is a deliberate subset -- unknown note fields are ignored, never an error.
+# `sources` is declared last on purpose: `field_order: relative` requires every other declared
+# field to sit ahead of it in the actual file, so a small, frequently-looked-up scalar is never
+# behind a `sources:` block that can run to hundreds of `path`/`hash` pairs on a large repo.
+schema: synapse-note-schema/v1
+id: graph-node/v1
+
+frontmatter:
+  field_order: relative
+  fields:
+    schema:
+      type: string
+      required: true
+      const: graph-node/v1
+    title:
+      type: string
+      required: true
+      min_length: 1
+    summary:
+      type: string
+      required: true
+      min_length: 1
+    node_type:
+      type: string
+      required: true
+      const: synapse-node
+    project:
+      type: string
+      required: true
+      min_length: 1
+    branch:
+      type: string
+      required: true
+      min_length: 1
+    sources_digest:
+      type: string
+      required: true
+      pattern: '^[0-9a-f]{64}$'
+    stale:
+      type: boolean
+      required: true
+    built_at:
+      type: string
+      required: true
+      pattern: '^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}$'
+    commit:
+      type: string
+      required: false
+    crux_path:
+      type: string
+      required: false
+    crux_lines:
+      type: string
+      required: false
+    grounded_in:
+      type: any
+      required: false
+    sources:
+      type: any
+      required: true
+
+body:
+  h1:
+    required: true
+    count: 1
+    equals: frontmatter.title
+  # Crux and Links are `synapse-node-format`'s documented convention for every
+  # authored node, but nothing has ever structurally required either heading
+  # to exist -- `write-node`'s own crux/grounded_in extraction is scoped to
+  # `## Crux` only when present, never required. Required here would be a new
+  # constraint this schema doesn't need to introduce to do its actual job
+  # (field order, schema identity); Summary/Sources/Notes are required because
+  # `write-node` always emits all three unconditionally today, so requiring
+  # them adds no new constraint at all.
+  sections:
+    - title: Summary
+      level: 2
+      required: true
+      non_empty: true
+    - title: Crux
+      level: 2
+      required: false
+      non_empty: true
+    - title: Links
+      level: 2
+      required: false
+    - title: Sources
+      level: 2
+      required: true
+      non_empty: true
+    - title: Notes
+      level: 2
+      required: true
+  section_order: relative
+
+checks: []

package/skills/synapse-node-format/SKILL.md

@@ -55,7 +55,11 @@ to orient someone already inside. A node without one is an error, not a default.
   finds its node via this list). Do **not** trim it to a handful of "representative" files —
   doing so silently destroys that lookup, leaves the node unable to answer "which files am I
   about", and reduces hash verification to whatever survived the trim. Readability pressure
-  belongs on `## Sources` below, never here.
+  belongs on `## Sources` below, never here. Always the *last* frontmatter field — on a large
+  project it can run to hundreds of `path`/`hash` pairs, and every other field stays ahead of it so
+  a single-key lookup never has to scan past it. `graph-node/v1`'s schema enforces this order
+  directly (`field_order: relative`); this document and `synapse write-node`'s own emission order
+  agree with it, not the other way around.
 - **`sources_digest`:** `sha256` over the sorted `path:hash` lines of `sources` (see "Computing
   `sources_digest`" below). Lets a staleness check answer "has this node changed" by reading one
   field instead of every hash.
@@ -149,18 +153,19 @@ to orient someone already inside. A node without one is an error, not a default.
 
 ```yaml
 ---
+schema: graph-node/v1
 title: "World — entity/component/resource core"
 node_type: synapse-node
 project: acme
+sources_digest: <sha256 over the sorted "path:hash" lines>
+stale: false
+built_at: "<now>"
 sources:
   - path: acme_ecs/world.ml
     hash: <git hash-object output>
   - path: acme_ecs/world.mli
     hash: <git hash-object output>
   # ... every file the node covers, not a selection
-sources_digest: <sha256 over the sorted "path:hash" lines>
-stale: false
-built_at: "<now>"
 ---
 
 # World — entity/component/resource core

package/skills/synapse-query/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: synapse-query
-description: This repo has a Synapse code graph. For ANY task here — understanding how something works, finding where code lives, tracing what depends on a file, or scoping an edit — consult synapse/{project}/Index.md and synapse query before grepping or reading source files. Grep only after Synapse has named the exact file(s) to read.
+description: This repo has a Synapse code graph. For ANY task here — understanding how something works, finding where code lives, tracing what depends on a file, or scoping an edit — consult synapse/{project}/Index.md and synapse query before grepping or reading source files. Grep only after Synapse has named the exact file(s) to read. Also applies when this repo has no graph of its own but the task concerns another checkout that does — synapse query --namespace <repo>@<branch> reaches that graph without switching directories.
 ---
 
 # Synapse Query: Day-to-Day Use of the Code Graph
@@ -56,6 +56,7 @@ required:
 | A node's prose, without its (possibly huge) `sources` list | `synapse query body "{Node}"` | Disk read, never the API; skips frontmatter and `## Notes`. See the cost note above. |
 | Every file a node covers | `synapse query sources "{Node}" [--count\|--modules\|--filter <p>]` | Filtered/counted/grouped, never the raw megabyte-scale list. |
 | Is this node's understanding still accurate? | `synapse query stale` / `drift` / `grounding` | Hand off to the `synapse-node` skill's procedure — this skill doesn't re-explain that. |
+| A node in a *different* checkout's graph, from a repo with no namespace of its own (or the wrong one) | `synapse query --namespace <repo>@<branch> body "{Node}"` (any subcommand takes it) | Names the target namespace directly instead of deriving it from cwd. `stale`/`drift`/`grounding`/`symbol` still need that checkout's real files on disk and refuse without `SYNAPSE_REPO_ROOT` set to it — `body`/`sources`/`field`/`links` don't. |
 
 ## Usage scenarios
 
@@ -87,12 +88,17 @@ resolve the specific symbol-level question:
 ## Guardrails
 
 - **Never grep the whole repo before checking `synapse/{project}/Index.md`**, unless this repo has
-  no Synapse namespace at all (`vault_list` on `synapse/{project}/` comes back empty — in that case
-  there's nothing to consult, say so and proceed normally).
+  no Synapse namespace at all (`vault_list` on `synapse/{project}/` comes back empty). Before
+  concluding there's nothing to consult, check whether the task actually concerns a *different*
+  checkout — `synapse query --namespace <repo>@<branch> body "{Node}"` reaches that repo's graph
+  without switching directories or checking it out. Only when no namespace anywhere covers the task
+  is there truly nothing to consult; say so and proceed normally.
 - **Never treat a node's summary as ground truth for a symbol-level claim** it wasn't built to make
   precisely — see "When a node isn't enough" above.
-- **Never `vault_read` a node just to read its prose.** That pulls the full frontmatter, which can
-  run to megabytes on a hub node. Use `synapse query body` (see the cost note above).
+- **Never `vault_read` a node just to read its prose — including a node in another checkout's
+  namespace.** That pulls the full frontmatter, which can run to megabytes on a hub node. Use
+  `synapse query body` (add `--namespace <repo>@<branch>` for a graph outside this checkout) — see
+  the cost note above.
 - **Never reason about a node's staleness inline in this skill.** Hand off to `synapse-node`'s
   procedure — that's its job, not this skill's.
 - **Never treat `synapse query`'s exit 1 as "clean."** It means the check could not run (no

package/skills/synapse-vault/SKILL.md

@@ -30,7 +30,7 @@ Search before you answer when the question is about:
 synapse vault-search-text <query>          full-text, relevance-ranked, with match context
 synapse vault-search --fields <f1,f2,...>  JsonLogic over frontmatter, tags, content, path globs
 synapse vault-list                         when you already know roughly where it is
-synapse vault-read <path>                  the whole note -- no partial/targeted read exists
+synapse vault-read <path>                  the whole note -- no partial/targeted read, except one path shape below
 ```
 
 `vault-search`'s JsonLogic filter and `--fields` projection both stop at frontmatter/tags/content/
@@ -39,6 +39,13 @@ exists yet), and `vault-read` always returns the full body, never one section on
 exactly what you need with `--fields` instead of over-fetching, and pull a specific section out of
 `vault-read`'s output locally when that's all you actually need.
 
+**The one exception is a `synapse/{project}/*.md` code-graph node.** `vault-read` on one of those
+returns the same whole-note body as any other path — frontmatter included, which on a hub node can
+run to megabytes just to reach a few hundred words of prose. `synapse query body <node>` (add
+`--namespace <repo>@<branch>` to reach a different checkout's graph) is the targeted read for that
+one path shape: prose only, no frontmatter. Reach for it instead of `vault-read` for anything under
+`synapse/` — see the `synapse-query` skill for the rest of its subcommands.
+
 A search that returns nothing is a real result and worth one line in the note you then write —
 a negative result cannot be rediscovered by searching for it.