For full text search please use the '?' prefix. e.g. ? Onboarding

Concept Summary

Semantic Mesh — LLM-Oriented Concept Summary

This document is the canonical, compact context for LLMs. It summarizes all documentation/concepts.* notes and cross-links to authoritative pages.

0) Semantic Flow Twin Purposes

  • Mint dereferenceable IRIs for referring to things on the Semantic Web
  • Hold versionable semantic data that uses those IRIs

1) Definition A semantic mesh is a dereferenceable, possibly-versioned corpus of semantic resources where every IRI resolves to meaningful content.

A filesystem-based mesh maps directly from a Git repository’s folder hierarchy to a published static site so that:

  • Every resource is addressable by a stable IRI.
  • "Naming resources" are dereferenceable via generated index.html resource pages.
  • "Content resources" are directly dereferenceable: they should return a file
  • RDF datasets live as distributions on versioned flow snapshots.
  • The weave process maintains coherence and keeps the repo publish-ready.

See:

2) Design Principles

3) Core Abstractions

3.1 Mesh Resources (Nodes and Components)

3.2 Facets (Folder, File, Dataset)

4) Addressing and Identity

4.1 Namespace and Relative Identifiers

  • Folder names become namespace segments; the path is the node’s relative identifier (and IRI path when published).
  • Relative identifiers are used within distributions for transposability; resolve relative to distribution location. See:
  • Namespace: overview
  • namespace segment: segment definition
  • system segments: reserved segments
  • relative identifier: relative IDs

4.2 IRI Semantics

  • Concept IRIs (slash-terminated) identify nodes, flows (abstract), snapshots (conceptual), and handle.
  • Content IRIs (with filenames) identify retrievable files: distributions, HTML pages, READMEs, assets.
  • Follow document-vs-thing hygiene to avoid ambiguity. See:
  • identifier: IRI types and mapping
  • Reference Iri Choices: trade-offs
  • IRI: terminology; prefer “IRIs” when referring to mesh-local IRIs

4.3 Handle Rationale

  • A node’s IRI refers to its referent (namespace, real-world entity, or dataset concept).
  • The handle component provides a IRI to refer to the node itself “as a mesh resource” (for config, provenance, lifecycle). See:
  • node handle
  • handle resource page

5) Physical Structure and Reserved Folders

Reserved folder names (underscore-prefixed; canonical set):

  • _node-handle/
  • Flow containers (abstract datasets):
    • _meta/, _payload/
    • _cfg-op/, _cfg-inh/ (see §9)
  • FlowShots inside a flow:
    • _default/, _working/, snapshot folders with format YYYY-MM-DD_HHMM_SS_vN/ (e.g., 2025-11-24_0142_07_v1/, 2025-11-24_0142_08_v2/, …)
  • Assets:
    • _assets/ (static files)

Folder-note pages for these reserved names live under folder.*.md (where defined):

6) Data and Versioning Model

  • Only flows are versioned (flows are DatasetSeries). Nodes are not versioned.
  • FlowShots (flow realizations):
    • _default/: latest stable realization; after weave it equals the content of the latest snapshot.
    • _working/: mutable working area.
    • Snapshot folders (format YYYY-MM-DD_HHMM_SS_vN/): immutable history for precise citation and provenance.
  • Working distribution: _working/ typically contains a single editable source; weave can fan-out serializations.
  • Sibling distribution: patterns and constraints for multi-file realizations. See:
  • Flow Version
  • working distribution
  • Sibling Distribution

7) Lifecycle and Weave Process Weave maintains structural coherence and publication readiness:

  • Ensures required system components exist.
  • If versioning is enabled, creates a new snapshot folder (format YYYY-MM-DD_HHMM_SS_vN/) from _working/.
  • Promotes _working/ contents to _default/.
  • Updates meta/provenance; regenerates resource pages.
  • Resolves internal links to maintain transposability.
  • Integrates with the scanner where applicable. See:
  • Weave Process
  • static site generation
  • Scanner
  • Provenance

8) Publishing and Sites

  • Repos are static-site-ready; pushing to GitHub Pages or any static host publishes the mesh (folder paths → IRI paths).
  • Transposition (domain/project move) is safe with relative IDs. See:
  • mesh repo
  • Semantic Flow site
  • publication

1) Configuration and Inheritance (Two Config Flows)

  • Operational Config Flow: final, resolved settings for a node (consumer). Overrides apply here.
  • Inheritable Config Flow: settings a node offers to descendants (provider). Property-level merge; order: parent → … → service → platform; propagation can be firewalled.
  • Resolution: a single inheritance mechanism resolves operational config from inheritable configs plus service/platform defaults. Explicit operational entries override inherited ones. See:
  • meshnode config flows: overview
  • operational config flow
  • inheritable config flow
  • Node Config Defaults: defaults as inheritable values

1) Aggregated Views

  • Aggregated distribution: optional roll-up of child payload nodes’ default datasets at a parent node for convenience. See:
  • Aggregated Distribution

1) Minimal File Tree Example

/repo-root/
├── _assets/                         # optional site-wide assets
├── my-node/                         # a mesh node (folder)
│   ├── _node-handle/                # handle component (resource.node-component.node-handle)
│   ├── _meta/                  # metadata flow (system)
│   │   ├── _default/
│   │   └── 2025-11-24_0142_07_v1/
│   ├── _payload/                  # payload flow (for payload nodes)
│   │   ├── _default/
│   │   ├── _working/
│   │   └── 2025-11-24_0142_07_v1/
│   ├── _cfg-inh/    # provider config (optional)
│   ├── _cfg-op/    # resolved config (optional; may be system-written)
│   ├── index.html                   # resource page
│   ├── README.md
│   └── CHANGELOG.md
└── docs/ or public host mapping     # publication target

12) Visual Overview

graph TD A[Mesh Node] --> B[Handle] A --> C[Meta flow] A --> E[payload flow] A --> G[Asset tree] A --> H[Resource pages] C --> C1[_default] C --> C2[Snapshots] E --> E1[_default] E --> E2[_working] E --> E3[Snapshots]

13) Glossary

  • semantic mesh: the set of addressable resources in a repository, published as a site
  • mesh node: an extensible resource containing other nodes and its own components
  • node component: terminal resource that supports node behavior/structure
  • node flow: DatasetSeries representing an abstract dataset (meta/data/config)
  • FlowShot: concrete Dataset realization of a flow (Snapshot, DefaultShot, WorkingShot)
  • snapshot distribution: a concrete serialization file (TriG, JSON-LD, etc.)
  • node handle: indirection to refer to the node "as a mesh resource"
  • mesh resource page: dereferenceable index.html for folders
  • Weave Process: lifecycle operation to version/promote/regenerate/repair
Backlinks