Skip to content
sdlc

Vault model and structural transforms

State: open/building · Kind: subsystem · Audience: system

Summary

Section titled “Summary”
  • A vault kernel — file set, walk policy, reference graph, link identity — plus plan/execute structural transforms that keep link integrity across renames, moves, and restructures.
  • Transforms are planned dry-run first, then executed; links resolve through a path map, never by string guessing; no silent overwrites.
  • Rewrites ride the splice discipline of C-N6RH-lossless-roundtrip-io: only the changed span of a link changes.

Statement

Section titled “Statement”

A vault is a set of related markdown files with identity (wikilinks, anchors, transclusions) spanning them. Today the fleet walks vaults with duplicated, policy-hardcoded code. A rename/move engine ships (packages/rust/vault-transform over vault-fs and wikilink). Vault reshape, merge/split, bulk restructure and contract-pair gating from the rust-markdown PR #43 dossier are not built. The headline operation is vault reshape (TM-0025-vault-reshape): project source vault(s) into a target vault of a different shape via declarative map rules and pluggable per-note transforms, with in-place rename/move/restructure as degenerate reshapes. This capability lands that design on vault-fs, wikilink, and vault-transform: the reference graph is derived from scanned links, transforms are validated plans over the graph, and execution produces minimal byte-offset edits plus file operations. Contract pairs make reshapes checked migrations: sources validate against the source contract, output against the target contract.

What it provides

Section titled “What it provides”
  • Vault kernel: policy-parameterized walk (generalizing determined-vault::walk), path-escape guards, file identity. The kernel is vault-fs, over the real filesystem; there is no trait over a source.
  • Reference graph: wikilinks, embeds, anchors, frontmatter references — resolved through a path map with per-source link identity.
  • Vault reshape: sources[] → target projection through glob map.rules[] and a collision-resolved PathMap; pluggable per-note transforms (filter/transform/link mappers, drop_fields-class built-ins as ordinary plugins).
  • Transform operations: rename/move with backlink rewrite, merge/split, bulk restructure — each a degenerate reshape, each as plan (inspectable, dry-run) then execute.
  • Contract-pair acceptance: a reshape declares source and target contracts; the migration is checked on both ends (C-K3TQ-markdown-contract-and-validation).
  • Invariants enforced: read-only sources, link integrity, fail-closed selection, no silent overwrite, dry-run parity (execute re-verifies source hashes).

Underlying implementation

Section titled “Underlying implementation”

The shipped engine (vault-transform, M-J9TB-vault-kernel-and-transforms) splices by byte offsets over wikilink, markdown-util, yaml-splice, and atomic-write; it has no CST dependency. solutions/determined/crates/determined-vault is the Rust consumer-facing entry to the vault primitives: it re-exports vault-fs, yaml-splice, markdown-util and wikilink and adds canonical YAML emit, sidecar paths, vault-dir resolution and read_note. Inputs: the PR #43 design dossier (pipeline, invariants, link-resolution algorithm — migrated verbatim beside D-7VMX-markdown-ecosystem-strategy; its scanner code rejected), determined-vault walk/guard primitives, determined-platform/src/vaultwalk.rs as the named duplication to delete, and packages/ts/intersect (D-4FRD-intersect-api) as prior art for map-rule overlap/collision analysis.

Locations

Section titled “Locations”
  • packages/ts/vault-graph-core/
  • packages/rust/vault-fs/
  • packages/rust/vault-transform/
  • packages/rust/wikilink/
  • solutions/determined/crates/determined-vault/

← Back to Capabilities