tom_som_rust_v0 — typed TomSpecs object model for Rust

> Cross-references. > tom_specs_model/doc/som_multiplatform_spec_model.md > is the SOM authority: SOM §6 decides the split between this > typed access path and the generic one, SOM §8 decides what > this generated surface contains, SOM §4.2 decides the model > version stamp and the editing rules it enforces, and > SOM §17 decides how the package is built and published. > tom_specs_model/doc/index.md catalogues every > TomSpecs subject-matter document and owns the § citation > convention. This README says how to use this package's code; > those documents own the model, the formats and the rules, and > nothing here restates them.

Generated typed TomSpecs object-model facade (Rust).

Where this fits

tom_som_rust_v0 is the generated typed face of the TomSpecs object model for Rust: one type per document section, so a specification is read and written through named members rather than through string paths. It exists because a string path is checked only at run time — a mistyped one reads as an absent value instead of an error — and a specification is exactly the kind of document where that failure is silent and expensive. It is one half of a pair: the hand-written tom_som_rust_runtime holds everything identical in every language (the sparse document store, the codecs, the validator) and this half holds only what changes when the model changes, so a regeneration rewrites the typed types and touches nothing else. The same pair exists for all nine SOM languages, generated from one model, so a document written through any of them reads identically through the other eight. The crate has no third-party dependencies — only the runtime crate — and because cargo package requires every dependency to carry a version, the path dependency on the runtime also pins the model version.

Overview

A TomSpecs document is sparse and path-keyed: a value lives under the globally-unique section-id path it belongs to, and an absent key means "no value" rather than an empty one. This package holds none of those values — SpecDocument, in the runtime, does. What it holds is a typed view: each generated type wraps a document together with the path prefix it is rooted at, and its members resolve to the paths beneath that prefix. Constructing a document root also runs the model-version check (SOM §4.2), so a document stamped by a different model version is refused rather than silently misread.

Everything generated here is derived from the tom_specs_model Dart model and rewritten wholesale on every run of tom_specs_clitool/bin/generate_som.dart. Beside the typed types the package ships the lossless meta-data file (meta/spec_model.meta.json, SOM §5.3), the generated DocSpecs schemas (schemas/, SOM §13), and the metadata trees that drive the dot-notation and id-tree access surfaces (SOM §8). The hand-written trees beside them — examples/, the tests, doc/ — are preserved across regeneration; the generator writes files, it never wipes the output root.

Installation

These are proprietary (publish = false) crates, so they are not on crates.io. When published to a private registry, add the facade (it pulls in tom_som_rust_runtime):

cargo add tom_som_rust_v0

or pin it in your Cargo.toml:

[dependencies]
tom_som_rust_v0 = "1.3.2"

tom_som_rust_v0 and tom_som_rust_runtime both carry version 1.3.2, taken from the TomSpecs model version — pin them together. Every other dependency route (git, path, vendored, build-from-source) is in readme_howtointegrate.md.

Features

Document roots

Each root is a whole TomSpecs document, and the first segment of every path beneath it is its section id. Construct the root you need over a SpecDocument; the 1254 model classes are reached through it.

Section id	Document	Generated root type
`SBP`	Solution Blueprint	`D00SolutionBlueprint`
`CLA`	Current Landscape Assessment	`D01CurrentLandscapeAssessment`
`TOM`	Target Operating Model	`D02TargetOperatingModel`
`IFM`	Information Model	`D03InformationModel`
`RSP`	Requirements Specification	`D04RequirementsSpecification`
`ISC`	Interaction Scenarios	`D05InteractionScenarios`
`ATS`	Architecture & Technology Specification	`D06ArchitectureTechnologySpecification`
`IIS`	Integration & Interface Specification	`D07IntegrationInterfaceSpecification`
`SAS`	Security & Access Specification	`D08SecurityAccessSpecification`
`XDS`	Experience Design Specification	`D09ExperienceDesignSpecification`
`QAP`	Quality & Acceptance Plan	`D10QualityAcceptancePlan`
`DRM`	Delivery Roadmap	`D11DeliveryRoadmap`
`TRP`	Transition & Rollout Plan	`D12TransitionRolloutPlan`
`CGP`	CodeSpecs Generation Projection	`D13CodeSpecsProjection`

Quick start

Add tom_som_rust_v0 to your Cargo.toml (cargo add tom_som_rust_v0), then:

use tom_som_rust_runtime as som;
use tom_som_rust_v0::D00SolutionBlueprint;

fn main() {
    // A typed Solution Blueprint over a fresh document. The constructor also
    // runs the instantiation-time model-version check (an empty stamp is
    // editable).
    let doc = som::doc_ref(som::SpecDocument::new());
    let pd = D00SolutionBlueprint::new(doc, "").expect("new D00SolutionBlueprint");

    pd.set_content("A platform that unifies our fragmented order systems.");
    pd.current_landscape()
        .set_content("Three legacy systems with no shared customer record.");

    println!("{}", pd.content());
}

Prints A platform that unifies our fragmented order systems. — the value just written, read back through the typed getter.

Examples

Sample	Demonstrates
`a_typed_access.rs`	The generated typed facade — named members, nested-section navigation, and the typed `SomList` collection.
`b_generic_document.rs`	The generic runtime underneath — string paths into a sparse store, plus JSON and YAML serialization.
`c_reflection_metadata.rs`	The value-free reflection surface — load `meta/spec_model.meta.json` , enumerate roots and fields, resolve a path to the model node it lands on.
`golden_log.rs`	The cross-language golden-log generator ( `SOM §19` ) — reads essentially every section both ways and asserts typed equals generic.

examples/README.md gives the run command for each.

For complete, runnable sample projects — a whole task carried end to end across several packages rather than one package's API — see tom_specs_samples/.

Usage

The generic store underneath

A facade is a view; the document is the value. Reach past the typed types whenever a path is computed rather than known — both sides address exactly the same store.

use tom_som_rust_runtime as som;
use tom_som_rust_v0::meta;

let mut doc = som::SpecDocument::new();
doc.set_content(
    "SBP/content",
    "A platform that unifies our fragmented order systems.",
);

// A repeated section: append an item, then fill a content leaf under it.
let item = doc.add_list_item("SBP/currentLandscape/CUOPME-OPER-LST");
doc.set_content(&format!("{}/content", item), "Average order turnaround: 4.2 days.");

// The whole document serializes to the canonical wire format.
let tree = meta::d00_solution_blueprint_meta_tree();
print!("{}", som::encode_yaml(&doc, &tree, "1.0").expect("encode_yaml"));

Metadata and reflection

The exported class graph answers "what can the model hold?" with no document values involved — enumerate roots and fields, or resolve a concrete path to the model node it lands on (SOM §7).

use std::fs;

use tom_som_rust_runtime as som;

let data = fs::read_to_string("meta/spec_model.meta.json").expect("read meta");
let model = som::SpecModel::from_json_str(&data).expect("parse meta-data");
let reflection = som::SpecReflection::new(&model);

for root in reflection.roots() {
    println!("{}  {}", reflection.root_segment(root), root.title);
}

let res = reflection
    .resolve("SBP/currentLandscape/content")
    .expect("resolve");
println!("kind={}  value_leaf={}", res.kind, res.is_value_leaf());

Regenerating

This package is output. When the model changes, regenerate it rather than editing it — every file carrying the GENERATED … do not edit by hand banner is overwritten:

dart run tom_specs_clitool/bin/generate_som.dart

Architecture

  tom_som_rust_v0          the typed path — this package
    D00SolutionBlueprint …        one type per document root
            │  extends
            ▼
     SomNode / SomScalar / SomList     editing-facade bases
            │  bound to
            ▼
      SpecDocument                sparse, path-keyed value store
            │                     (tom_som_rust_runtime)
            ▼
  SpecReflection · SpecValidator · YAML + Markdown codecs
            ▲
            │  described by
      SomMetaTree  ◀── meta/spec_model.meta.json

Type	Responsibility
`D00SolutionBlueprint` …	The generated document roots — one per row of the table above, each the typed entry point to a whole document.
`SomNode`	The base every generated section type extends: a document plus the path prefix this section is rooted at.
`SomScalar`	A typed leaf — parse and format at the store boundary, so `int` / `bool` / enum members read as themselves.
`SomList`	A typed repeated section — append, index and enumerate items whose paths the store generates.
`SomMetaTree` / `SomMetaNode`	The generated metadata trees ( `SOM §7` ): the model's shape as data, behind the dot-notation and id-tree access surfaces.
`SomEditability`	The `SOM §4.2` version-check outcome — whether a stamped document may be edited by this facade.
`SpecDocument`	The value store itself. Lives in `tom_som_rust_runtime` ; every type above is a view onto it.

Ecosystem

  tom_specs_model          the Dart model — the source of truth
         │
         ▼  generate_som
  tom_specs_clitool        the generator
         │
         ▼  emits
  tom_som_rust_v0   ← this package (typed)
         │
         ▼  depends on
  tom_som_rust_runtime  (generic, hand-written)
         │
         ▼  validated against
  tom_som_conformance      the shared cross-language corpus

The same shape repeats for all nine languages; the corpus at the bottom is shared, which is what makes "identical in every language" a measured claim rather than an intention (SOM §19).

Further documentation

TomSpecs subject matter — the authorities this package implements:

Document	Authority for
index.md	The catalogue of every TomSpecs subject-matter document, and the `§` citation convention.
som_multiplatform_spec_model.md	The two access paths, what this generated surface contains, the version stamp and editing rules, the `.md` and `.docspecs.yaml` formats, and the conformance corpus.
som_toolchains.md	This language plane's build and verify toolchain, and the reference host.
tom_specs_model_meta_schema.md	The on-disk schema of `meta/spec_model.meta.json`.

This package — its own guides:

Guide	Covers
doc/tutorial.md	A Rust walkthrough end to end — install, open a document, read and edit a section, validate it, and serialize to `*.docspecs.yaml` and Markdown.
readme_howtointegrate.md	Every dependency route, how to pin the version, and building from source.
examples/README.md	The runnable samples and how to run each.

Siblings — packages you will reach for next:

Package	What it is
tom_som_rust_runtime	The generic runtime this facade is a view over — reach for it directly to drive a document by path.
tom_som_conformance	The shared corpus and the cross-language drivers that run every port against it.
tom_specs_clitool	The generator that writes this package.

Status

Version 1.3.2, tracking the TomSpecs model version and matching tom_som_rust_runtime. Generated surface: 14 document roots, 1254 model classes. Verify the package with:

cargo build
cargo test
./run_tests.sh   # cargo test + the three samples

A generated README states no fixed test count: the count moves with the model, and a number this file could not update would go stale the first time the model did. The command above is the standing answer — it runs this package against the shared cross-language corpus (SOM §19).