tom_som_dart_runtime library

TomSpecs Specification Object Model — generic Dart runtime.

The language-independent, hand-written runtime shared by every generated typed tom_som_dart_v0 facade and the TomSpecs editor:

SomMetaNode / SomMetaTree — the canonical SOM §7.1 metadata tree (every annotation, exact class/member names) with the dynamic lookups SomMetaTree.byId and SomMetaTree.byPath; generated facades emit the populated tree, this runtime defines the types;
buildSomMetaTree — the bridge that expands an exported SpecModel class graph into a wired SomMetaTree (used until the generated facades emit trees directly);
SpecDocument / SpecDocumentState — the sparse, path-keyed in-memory representation of a concrete document and its undo snapshots;
SpecDocumentYaml — the hierarchical *.docspecs.yaml v2 codec (one nested tree walked against the metadata tree; strict SpecYamlFormatException load errors, no v1 compatibility);
SpecModel and friends (SpecRoot, SpecClass, SpecField, SpecAnnotation, FormFieldSpec, SpecFieldKind) — the meta-model ("reflection") loaded from the exported spec-model meta-data;
SpecReflection — value-free enumeration and path resolution over a SpecModel;
SpecChip / SpecRowExtras / kRenderedAnnotations — the theme-free display semantics of the model's annotations: which markers a row carries, what each says, and when one must be suppressed. Shared so the editor and the reviewer cannot disagree about what a marker means while each renders it in its own idiom;
SpecEditor — the generic, meta-validated modification API (YRD7): typed value/form-field access (via the shared somParse*/somFormat* boundary helpers), headline/id editing, list-item and clear-section operations — the layer the generated typed facades are a thin veneer over;
SpecQueryEngine / SpecQueryCursor — the lexical/structural grep-like query facility (find by text/pattern, kind, class, id/path, @MapsTo/@DetailedIn, state) with lazy, edit-stable cursor iteration;
SomTextPattern — the portable pattern subset the text dimension matches with, transcribed into all nine runtimes rather than delegated to each language's regex engine, so matchSpans is identical by construction (two runtimes have no regex to delegate to at all);
SpecReviewAnnotations — the review annotations in content values (SOM §11.9): list, insert, answer, assign comment ids, resolve, apply inline marks, strip and count comment blocks, question blocks and CriticMarkup marks;
extractAnswers / renderAnswers — a review round's answers, comments, open questions and inline marks as a step folder's answers.md (SOM §11.9.7);
validateDocument — checks a document's values against the model;
DocSpecsDocument / DocSpecsSchema / DocSpecsValidator — the consolidated SOM §14 DocSpecs module: schema-free markdown parse, validation against a generated *.docspecs-schema.yaml with a structured DocSpecsViolation list, and bindDocSpecsMarkdown onto the SOM metadata tree;
SpecNodeCreator / checkAddNode — the meta-model-validated node creation gate (allowed child kind / section-id pattern / cardinality), so a document only ever grows in model-permitted ways;
SomNode / SomList / SomScalar / checkSomModelVersion / somEditabilityFor / SomEditability — the hand-written support the generated tom_som_dart_v0 typed facade extends (editing layer + instantiation-time version check + its non-throwing editability query);
CodeSpecsExtractor / CodeSpecsExtract / CodeSpecsAreaCatalog — the machine half of TomSpecs Phase 4: routes a filled document by @CodeSpecKind into one bounded, cited extract per CodeSpecs area. It copies and indexes; it never summarises, rephrases or names anything, so every scalar it emits occurs character-for-character in its source.

Pure Dart, no Flutter dependency.

Classes

CodeSpecsArea: One row of the codespecs_mapping.md §4.1 parts catalogue, plus the codespecs_mapping.md §4.4.3 slice and codespecs_mapping.md §4.4.6 authoring steps that place it. This is the per-area context an extract carries beside its content.
CodeSpecsAreaCatalog: The machine-readable form of codespecs_mapping.md §4.1 + §4.4.3 + §4.4.6.
CodeSpecsCarrier: One A5 carrier (codespecs_prompt.md §4.5): a structured field the model must keep offering.
CodeSpecsExcludedArea: One area the gate record left out of scope.
CodeSpecsExtract: One area's extract: the area's context plus every routed entry, in SOM document order.
CodeSpecsExtractEntry: One extract entry: a single value the specification document stores, with everything needed to trace it back (codespecs_mapping.md §1.1.1, "Entry").
CodeSpecsExtractor: Produces one CodeSpecsExtract per active area from a filled specification document.
CodeSpecsExtractSet: Every extract one run produced, read back and scoped by its gate record.
CodeSpecsFieldRef: A SOM field a gate table names: a class, one of its members, and the form field when the value is one field of a @Form section.
CodeSpecsGate: Stage A of codespecs_prompt.md §4.
CodeSpecsGateCheckResult: One check's outcome.
CodeSpecsGateEntry: One area's recorded verdict.
CodeSpecsGateFinding: One thing a check found wrong.
CodeSpecsGateGap: One gap line of an insufficient area (codespecs_prompt.md §6.3): a missing input, and the section field that should have carried it.
CodeSpecsGateRecord: The Stage-B gate record, gate.verdicts.yaml (codespecs_prompt.md §6.3).
CodeSpecsGateReport: The gate's report: one result per check, A1 to A5.
CodeSpecsRequiredArgument: One A4 obligation (codespecs_prompt.md §4.4): a required Cs* marker argument and the stored SOM field it derives from.
CodeSpecsRouting: The verdict recorded for one class node of the walked document, with the provenance of the marker that decided it.
CodeSpecsSlice: One emission slice of codespecs_mapping.md §4.4.3.
CodeSpecsStep: One row of the codespecs_mapping.md §4.4.6 authoring-step table — the unit Phase 4 is authored in, one csgen todo each.
DocSpecsDocument: A schema-free DocSpecs markdown parse: the declared schema header (if any), the top-level sections, and the parse-time violations (malformed headings). Validation against a schema is a separate step — DocSpecsValidator.validate — which folds these violations into its result.
DocSpecsDocumentSection: One document: sections: slot: the backing section-type and whether the slot is optional.
DocSpecsFormField: One field of a form-types: entry.
DocSpecsFormType: One form-types: entry: an ordered field list.
DocSpecsPatternCheck: A pattern-check / pattern-check-id rule: the regex pattern plus the authored errorMessage.
DocSpecsSchema: A loaded *.docspecs-schema.yaml (the schema-generator output format , SOM §13): the title-format, the ordered sectionTypes (file order — descending prefix length in generated schemas, so first-startsWith-match is longest-prefix resolution), the formTypes, and the documentSections. Schema features outside the SOM §14 scope are ignored on load and named in warnings.
DocSpecsSection: One section of a schema-free DocSpecs parse: its id (null for a malformed heading), heading title, markdown level, 1-based heading line, accumulated bodyLines (each with its own source line = bodyStartLine + index), and nested children.
DocSpecsSectionType: One section-types: entry of a DocSpecs schema.
DocSpecsSubsectionRule: One subsection slot of a section-type: min-count (default 0) and max-count (null = infinite).
DocSpecsValidator: Validates a schema-free DocSpecsDocument against a DocSpecsSchema (SOM §14). Stateless per document; validate always returns the complete violation list (never fail-fast); a document is valid iff it is empty.
DocSpecsViolation: One structured violation (SOM §14): the rule, the offending sectionId (when one exists), the bound runtime path (when resolvable), the 1-based source line, and a human-readable message.
FormFieldSpec: A single form field within a @Form content section.
KindLink: A list-valued taxonomy annotation: a set of enum codes plus an optional explanatory note.
MarkdownFenceTracker: Fence state machine (CommonMark-ish): a line whose first non-space run (up to 3 spaces indent) is 3+ backticks or tildes opens a fence; a matching same-character run at least as long closes it.
NoArtifactLink: The third routing verdict: @NoArtifact(NoArtifactReason, {note}) — the section feeds neither a CodeSpecs part nor a follow-up process (codespecs_mapping.md §8.3).
OneOfGroup: A closed choice declared by @OneOf on a container class (codespecs_mapping.md §8.2): a set of mutually exclusive subsections of which exactly one applies, selected by a discriminator form-field.
SomContentTypeMeta: The @ContentType(type, description) annotation captured on a node.
SomDocMeta: The @Document metadata carried by a document root (SOM §7.1 DocMeta).
SomFormFieldMeta: One field of a @Form section (SOM §7.1 FormMeta.fields).
SomFormMeta: The form metadata of a @Form node (SOM §7.1 FormMeta).
SomList<T>: A typed view over a list field, layered over the document's list store.
SomListMetaRef<E>: The generated accessor for a list position (SOM §8): path is the list container path; item returns the accessor for the seq-th item position (<path>-<seq>), whose children are the element class's accessors.
SomMetaExtra: One annotation captured losslessly into the generic extra list — annotations the tree defines no dedicated slot for (SOM §7.1 note), e.g. @Max, @MinLength, @PatternCheck, @TextRequired.
SomMetaNode: One node of the SOM metadata tree (SOM §7.1 MetaNode).
SomMetaRef: One position of the generated dot-notation / ID-tree access surfaces (SOM §8): an absolute document path bound to the tree it belongs to.
SomMetaTree: The metadata tree of one document root: parent/path wiring plus the two dynamic lookups (byId, byPath) SOM §10 requires every runtime to keep.
SomNode: The base class every generated typed facade class extends.
SomScalar: A scalar list item — a bare string value held in the document's content store at its own item path. Used as the element facade for non-complex (String/scalar) lists.
SomTextPattern: A compiled pattern over the portable subset described in the library comment. Compile once with SomTextPattern.compile (or SomTextPattern.literal for a plain substring) and match with allMatches.
SpecAnnotation: A single annotation captured losslessly from the model source (SOM §5.3): its name and the resolved argument map ({ '<arg>': <value> }). This is the annotations[] block emitted by ModelJsonExporter — the superset the curated convenience accessors (SpecClass.sectionId, SpecField.min, …) are projected from.
SpecAnswerCounts: The counts a step's closing item reports.
SpecAnswerEntry: One extracted entry.
SpecAnswerExtract: The extraction of one document.
SpecAnswerRenderOptions: What answers.md includes besides the answered questions and comments.
SpecAssemblyOverlap: One place two or more fragments both write.
SpecChip: One rendered marker: what it says, what kind of statement it is, and the detail too long to fit on it.
SpecClass: A model class with its fields.
SpecDocument: A sparse, live instance of a TomSpecs document (tom_specs_editor_specification.md §8, §13).
SpecDocumentAssembly: The result of SpecDocument.assemble.
SpecDocumentMarkdown: Codec binding a SpecModel and a concrete SpecDocument to the DocSpecs Markdown import/export format (SOM §11).
SpecDocumentState: An immutable deep-copied snapshot of a SpecDocument (tom_specs_editor_specification.md §10 undo stack).
SpecDocumentYaml: Codec for the document: pass of the native *.docspecs.yaml format.
SpecEditor: Generic, typed, meta-validated editing over a SpecDocument.
SpecField: A single field of a SpecClass.
SpecListItemMove: The result of SpecDocument.moveListItem.
SpecMarkdownImport: A Markdown document loaded by SpecDocument.fromMarkdown: the document built from every accepted block, and the parse report it came from.
SpecMarkdownRejection: One rejected block in a Markdown import (SOM §11.7). Reported, never silently dropped: each carries the source line, the offending anchor (section path or id), the reason, and a human-readable message.
SpecMarkdownRendition: A Markdown rendition of a document and the document path behind each of its headings (SpecDocumentMarkdown.exportRootWithMap).
SpecMarkdownResult: The outcome of parsing a Markdown document (SOM §11.7): the staged values plus every rejected block. The values are keyed exactly like SpecDocument.toJson so a caller can merge them into a live document as a full overwrite of the covered scope.
SpecMarkedChange: A value written as a marked change.
SpecMarkEntry: One inline mark as listMarks reports it.
SpecMarkIssue: A mark the scanner could not read; it is left as written.
SpecMarkOutcome: What was done to one mark.
SpecMarkReport: The report of a mark operation, for the decision log.
SpecMatchSpan: A [start, end) half-open span within a matched string — the offsets a pattern hit, surfaced on SpecQueryMatch.matchSpans.
SpecModel: The complete exported model.
SpecModelStampCheck: The outcome of checking a loaded snapshot's generation stamp against its own payload and against the clock — see SpecModel.checkStamp.
SpecNodeCreator: Applies checkAddNode and performs the constrained mutation.
SpecNodeProjection: A flat, value-bearing projection of one document node — everything the tier-1 structural/lexical index (llm_and_d4rt_tools.md §9.2) needs to index a section without re-walking the model itself: its path, kind, class, the structural facets (section id, @MapsTo / @DetailedIn), the headline, the searchable strings (stored values + headline), and whether it currently holds a value.
SpecParagraph: One paragraph of a value (SOM §11.9.1, "Paragraphs"): a run of non-blank lines, where a blank line inside fenced code does not end the run. Its index is what afterParagraph of the inserts takes.
SpecQuery: An AND-combined lexical/structural query (llm_and_d4rt_tools.md §6). Every supplied dimension must hold for a node to match; an all-null query matches every node in the document's structural closure.
SpecQueryCursor: A lazy, forward-only cursor over the nodes matching a SpecQuery (llm_and_d4rt_tools.md §6).
SpecQueryEngine: Runs SpecQuerys over a (SpecModel, SpecDocument) pair, producing SpecQueryCursors.
SpecQueryMatch: One node matched by a SpecQuery (the llm_and_d4rt_tools.md §6 cursor record).
SpecQuestionDraft: A question to insert (SOM §11.9.2).
SpecQuestionOption: One option of a question (SOM §11.9.2): - (a) text, or - **(b)** text for the recommended one.
SpecReflection: Read-only queries over a SpecModel.
SpecResolution: The outcome of resolving a document path against a SpecModel.
SpecReviewAnnotation: One annotation, located by the value that holds it.
SpecReviewAnnotationCounts: The counts a report needs (SOM §11.9).
SpecReviewAnnotations: The annotations of a document, and the operations that edit them (SOM §11.9). Values are visited in a fixed order — content paths sorted, then form paths sorted with their field names sorted — so "document order" is the same in every runtime.
SpecRoot: A document root (a class carrying @Document).
SpecRowExtras: The annotations a row renders beside its structural label: the @Unused marker, the @Comment note, the @Headline default, the @SectionIdPattern badge, the provenance and the @SerializationOrder ordinal.
SpecSerializationOrder: Computes @SerializationOrder-based orderings over a SpecModel.
SpecValidationError: One problem found while validating a document.
SpecYamlContents: The decoded passes of a *.docspecs.yaml file: the document: pass as a populated SpecDocument, the review: pass as a raw map (the runtime carries it uninterpreted and writes it back), and the optional authoring model-version stamp.
StandardReferences: The provenance recorded by @StandardReferences(standards, connotation): which public standard(s) a section or field derives from, and what the section means.

Enums

CodeSpecsGateCheck: The five Stage-A checks.
CodeSpecsGateVerdict: One of codespecs_prompt.md §6.2's three per-area verdicts.
CodeSpecsRoutingVerdict: Which of the three codespecs_mapping.md §8.3 verdicts a class carries.
DocSpecsViolationRule: The SOM §14 violation rule vocabulary — identical across all nine runtimes.
SomEditability: The outcome of the SOM §4.2 version check, as a value a read-only viewer can branch on instead of catching SomVersionException (SOM §21).
SomMetaKind: The structural kind of a metadata node, mirroring SOM §7.1 (list | form | section | content | enum | complex | scalar).
SpecAnswerKind: What an extracted entry is.
SpecChipRole: The kind of statement a chip makes, so an app can colour it without knowing which annotation produced it.
SpecCreationCode: Why an attempted node creation is illegal against the model.
SpecFieldKind: The render kind of a field, mirroring the exporter's classification.
SpecMarkDecision: What to do with one inline mark (SOM §11.9.3).
SpecMarkdownRejectReason: Why an imported Markdown block was rejected (SOM §11.7 rejection protocol).
SpecMarkKind: The five CriticMarkup inline marks (SOM §11.9.3).
SpecNodeKind: What a resolved path lands on in the model.
SpecReviewAnnotationKind: The three kinds of annotation (SOM §11.9).
SpecStateFilter: Whether a node currently holds a value, used by the state dimension.
SpecValidationCode: Why a single value in a document is invalid against the model.

Mixins

AnnotatedSpecNode: Shared behaviour of the two model nodes that carry annotations — classes and fields. Keeps the annotation lookups defined once instead of per node type.

Constants

defaultMaxSnapshotAge → const Duration: How old a snapshot may be before SpecModel.checkStamp calls it aged.
kCodeSpecKindAnnotation → const String: The annotation names of the three routing verdicts (codespecs_mapping.md §8.3). All three ride the generic annotation bag in every SOM runtime (codespecs_mapping.md §8.4), so they are read by name rather than through a meta slot.
kCodeSpecsExtractFileSuffix → const String: The suffix every extract artifact of record carries.
kCodeSpecsExtractFormat → const int: The version of the emitted extract artifact's on-disk shape. Bumped when the YAML or Markdown layout changes in a way a reader could notice.
kCodeSpecsGateDescoped → const String: The one resolution a gate record may carry: an insufficient area the user decided to leave out.
kCodeSpecsGateRecordFile → const String: The file name of the gate record, written beside the extracts.
kCodeSpecsGateRecordFormat → const int: The gate record formatVersion this runtime reads and writes.
kFollowUpKindAnnotation → const String: See kCodeSpecKindAnnotation.
kListItemSegment → const String: Structural-path segment standing in for "any element of this list".
kNoArtifactAnnotation → const String: See kCodeSpecKindAnnotation.
kOneOfSegment → const String: Structural-path segment for the closed-choice group a class declares.
kProjectionExplanation → const String: Why a projection is shallow.
kProjectionLabel → const String: Badge text for a @CodeSpecsProjection root (codespecs_mapping.md §8.4).
kReferencesChipLabel → const String: Marker opening a node's provenance panel (@Reference / @StandardReferences). Collapsed by default: over two thousand fields carry standards, and inlining them would bury the structure.
kRenderedAnnotations → const Set<String>: Every annotation name a spec-model surface accounts for, and where it surfaces.
kSectionContentSegment → const String: Structural-path segment for a list section's own intro content.
kSectionIdSlot → const String: The reserved refersTo slot naming a registry entry's own section id rather than one of its form fields (tom_specs_model_rules.md §6.2).
kSerializationOrderToggleLabel → const String: Label of the switch revealing @SerializationOrder ordinals.
kSpecPathSeparator → const String: The path separator between section segments.
kUnusedChipLabel → const String: Marker on a node whose @Unused annotation says it carries no authored content — the section is a structural container only.
projectionChip → const SpecChip: The marker a @CodeSpecsProjection document root carries.
referencesChip → const SpecChip: The affordance that opens a node's provenance panel.
unusedChip → const SpecChip: The marker an @Unused node carries beside its struck-through label.

Functions

applyInlineMarksText(String value, {required bool accept}) → String: value with every inline mark accepted (accept) or rejected, and every highlight and comment mark removed, by the rules of SOM §11.9.3. Marks in code and malformed marks stay as written.
assembleSpecDocuments(Map<String, SpecDocument> fragments) → SpecDocumentAssembly: Merges fragments — name → document, in order — into one document. See the library comment for the refusing rule.
bindDocSpecsMarkdown(SpecModel model, SpecDocument document, String text) → SpecMarkdownResult: Binds a DocSpecs markdown text onto the SOM metadata tree of model, staging values against document's path grammar — the SOM §11.7 entry point, delegated to SpecDocumentMarkdown.parse.
buildSomMetaTree(SpecModel model, {String? rootType}) → SomMetaTree: Builds the wired SomMetaTree for one document root of model.
caseChips(SpecField field) → List<SpecChip>: One chip per discriminator value field is bound to by @Case.
checkAddNode(SpecModel model, SpecDocument document, String parentPath, String childSegment, {String? itemId}) → SpecCreationError?: Validates adding child childSegment under parentPath against model, consulting document for cardinality. Returns null when the add is legal, otherwise the SpecCreationError describing the first rule it breaks.
checkSomModelVersion(String generated, String? documentVersion) → void: The instantiation-time version check every generated root facade performs (SOM §4.2). generated is the object model's own major.minor version; documentVersion is the document's recorded authoring stamp (null/empty for a brand-new, never-stamped document).
codeSpecKindChips(KindLink? link, {bool suppressUnmapped = false}) → List<SpecChip>: The @CodeSpecKind chips for link.
codeSpecsYamlString(String value) → String: A JSON string literal that is also a YAML 1.2 double-quoted scalar — the one escaping rule every CodeSpecs artifact uses for free text.
docSpecsIdTransform(String id) → String: The DocSpecs id transform used for prefix matching: every run of non-alphanumeric characters becomes _ — the exact transform the schema generator applies when deriving a prefix: from a section id (the DocSpecs prefix grammar forbids dashes).
effectiveListItemSectionId({required String? storedId, required String? pattern, required int position, required String fallbackStem}) → String: The id a list item is identified by — its storedId when it has one, and otherwise the positional id derived from the list's pattern (YRD3).
encodeTwoLetterDate(DateTime date) → String: Encodes date as the two-letter day code used in generated section ids (criterion 4).
extractAnswers(SpecModel model, SpecDocument doc, {required String label, String? path}) → SpecAnswerExtract: Extracts the annotations of doc (or of the subtree at path) with their place in the document's Markdown rendition under model, in rendition order (by line).
fieldChips(SpecField field) → List<SpecChip>: The chips a field row carries: which alternative of a closed choice it is, then where its subtree is headed.
followUpKindChips(KindLink? link) → List<SpecChip>: The @FollowUpKind process chips for link.
formatCommentBlock({required String id, required String text, String? author}) → List<String>: The lines of a comment block.
formatQuestionBlock(SpecQuestionDraft q) → List<String>: The lines of a question block.
generateListItemSectionId(String pattern, DateTime date, Iterable<String> existingIds) → String: Builds the generated section id for a new list item (criteria 3–4, 6).
isHandoffAway(SpecClass cls, String rootType, {required bool cutAtDetails, required bool cutAtMaps}) → bool: Whether cls hands off to a different document — the rule both surfaces cut their trees on.
kindChips(KindLink? codeSpec, KindLink? followUp, NoArtifactLink? noArtifact) → List<SpecChip>: The chips stating where a node's subject matter is headed.
listItemPath(String listPath, int seq) → String: The path of the seq-th item appended to the list at listPath ("$listPath-$seq"), matching SpecDocument.addListItem.
markChangeText(String oldValue, String newValue) → SpecMarkedChange: newValue with its differences from oldValue marked, so that accepting every mark gives exactly newValue and rejecting every mark exactly oldValue (SOM §11.9.3). The diff runs by line, then by word inside a changed run of lines; words are never split, changes separated by at most two unchanged words are one mark, and nothing inside code is marked.
noArtifactChips(NoArtifactLink? link) → List<SpecChip>: The @NoArtifact verdict chip for link.
oneOfChips(OneOfGroup group) → List<SpecChip>: The chips a closed-choice group header carries: how much of the discriminator's value set the alternatives cover, which values they miss, and whether the discriminator resolved at all.
parseCodeSpecsExtractYaml(String text, {String source = ''}) → CodeSpecsExtract: Parses one <CE-CODE>.extract.yaml. source names the file in errors.
parseStampTimestamp(String? raw) → DateTime?: Parses a generation-stamp timestamp to UTC, or returns null.
pathToType(SpecModel model, String rootType, String targetType) → Set<String>: The shortest chain of class names from rootType to targetType, following elementType / type references — a breadth-first walk of the class graph.
renderAnswers(List<SpecAnswerExtract> extracts, {SpecAnswerRenderOptions options = const SpecAnswerRenderOptions()}) → String: Renders extracts as a step folder's answers.md: deterministic, grouped per document in the order given, entries in document order.
sectionIdPatternPrefix(String pattern) → String: The static prefix of a @SectionIdPattern: the pattern with its trailing placeholder (the run of trailing x characters) removed. DACEN-ITEM-xxx → DACEN-ITEM-.
somEditabilityFor(String generated, String? documentVersion) → SomEditability: Classifies a document's editability under the SOM §4.2 rules without throwing (SOM §21). generated is the object model's own major.minor version; documentVersion is the document's recorded authoring stamp (null/empty for a brand-new, never-stamped document).
somFormatBool(bool? value) → String: Formats a bool for the store; null becomes '' (clear, D4).
somFormatDouble(double? value) → String: Formats a double for the store; null becomes '' (clear, D4).
somFormatEnumName(String? name, List<String> values) → String: Validates an enum constant name against values before storing.
somFormatInt(int? value) → String: Formats an int for the store; null becomes '' (clear, D4).
somFormatNum(num? value) → String: Formats a num for the store; null becomes '' (clear, D4).
somMetaNodeDiff(SomMetaNode a, SomMetaNode b, {String at = '<root>'}) → String?: Compares the a and b subtrees field by field (annotations, names, kinds, form/document metadata, children and list element subtrees).
somModelVersionString(int major, String? label) → String: Computes the major.minor model-version string from a major version counter and an optional full label (the tom_specs_model version stamp, e.g. 1.0.0+3.abc1234).
somParseBool(String? raw) → bool?: Parses a stored string as bool — exactly true/false, else null.
somParseDouble(String? raw) → double?: Parses a stored string as double, or null when absent/unparsable.
somParseEnumName(String? raw, List<String> values) → String?: Parses a stored string as an enum constant name against values (the field's enumValues domain). Returns null when absent or not in the domain — a stale/foreign name reads as unset rather than throwing, the same forgiveness the other parsers extend to malformed numbers.
somParseInt(String? raw) → int?: Parses a stored string as int, or null when absent/unparsable.
somParseNum(String? raw) → num?: Parses a stored string as num, or null when absent/unparsable.
somScalarBase(String? typeName) → String?: The scalar base of a declared field type: int? → int, null stays null.
somTypedTextReadable(String? typeName, String? raw) → bool: Whether raw, stored in a field declared as typeName, is text that type's parser can read.
specParentPath(String path) → String: The parent path of path — everything before the final /-separated segment — or path itself when it has no separator (a root path).
specPathJoin(String parent, String segment) → String: Joins parent with a child segment using the path separator.
specPathSegments(String path) → List<String>: Splits path into its /-separated segments. A list-item sequence suffix (<segment>-3) stays attached to its segment — it is part of the segment, not a separate level.
splitListItemSegment(String segment) → ({String base, int seq})?: Splits a list-item segment into its base segment and sequence number when it ends in -<digits>, or returns null when it carries no numeric suffix.
stripAnnotationsText(String value) → String: value without any comment block, question block or inline mark (every mark accepted). Plain quotes and code stay.
validateDocument(SpecModel model, SpecDocument doc) → List<SpecValidationError>: Validates doc against model. Returns an empty list when the document is valid; otherwise one SpecValidationError per problem, in a stable order (content paths, then forms, then lists; each group sorted by path).
validateSpecDocument(SpecModel model, SpecDocument document, DocSpecsSchema schema, {String? rootType}) → List<DocSpecsViolation>: Renders document (root rootType, else its single populated root), validates the rendition against schema, and returns every finding with DocSpecsViolation.path set to the document path of the section its line belongs to.

Exceptions / Errors

CodeSpecsExtractError: Thrown when the document cannot be extracted from at all.
CodeSpecsRecordError: A malformed or unreadable extract file or gate record.
SomPatternError: A pattern that is not in the SomTextPattern grammar.
SomVersionException: Raised when a generated object model is instantiated against a document whose authoring model version it must not edit (SOM §4.2).
SpecCreationError: A rejected node-creation attempt. Thrown by SpecNodeCreator.add and returned (rather than thrown) by checkAddNode.
SpecReviewAnnotationError: Thrown when an operation names an annotation, value or paragraph that does not exist.
SpecSectionIdCollision: Raised when a section id would collide with another id in the same list (criterion 5: overriding an id must keep every id in the list unique).
SpecYamlFormatException: A structural error in a *.docspecs.yaml file: wrong/unsupported format version, a key that does not match the metadata tree at its position, a malformed value shape, or (on encode) document values the tree cannot place.

tom_som_dart_runtime library

Classes

Enums

Mixins

Constants

Functions

Exceptions / Errors

tom_som_dart_runtime package

tom_som_dart_runtime library