Skip to content

docs(dev): plan projects and the on-device asset store - #131

Draft
joschaschmiedt wants to merge 8 commits into
mainfrom
worktree-asset-store-plan
Draft

docs(dev): plan projects and the on-device asset store#131
joschaschmiedt wants to merge 8 commits into
mainfrom
worktree-asset-store-plan

Conversation

@joschaschmiedt

Copy link
Copy Markdown
Contributor

Design document only — no code, no proto, no behaviour change. Adds
dev/design/ASSET_STORE_PLAN.md and one clarifying edit to dev/EVENT_LOGGING.md.

Do not merge as a green light to implement. Phase 0 renames flags, wire
messages and client namespaces across files the in-flight refactor series is still
touching. Merging the doc is fine; starting the work is not, until those land.

Issue: #127. Blocks #108, #109, #70.

What it proposes

Make the project the unit of storage on a rig, and build the asset store inside
it:

<state-dir>/                  →  /var/lib/braemons/vstimd  (or ~/.local/braemons/vstimd)
  projects/
    <project>/
      scene-configs/             <name>.config.json
      images/  meshes/  scripts/  data/
      logs/                      ← written by the event logger, not uploaded
    default/  demos/  _session/  _scratch/

A scene-config and the files it references are one artefact, so they live in one
directory: copying a study to a second rig, archiving it, deleting it or handing it
to a collaborator becomes one operation instead of two that can drift. Asset refs
inside a saved scene-config are project-relative, so a project keeps working
after it is renamed or copied to a rig where it lives under another name.

The active project becomes real server state — --project at boot,
SetProject/GetProject on the wire with a ProjectChanged event, implicit on
scene-config load, and a selector in the overlay and the web UI. Relative refs are
resolved to absolute at command-handling time, so a later switch can never
retroactively repoint a live stimulus.

Decisions worth reviewing

  • <state-dir>/projects/, not /var/lib/braemons/assets. systemd's
    StateDirectory=braemons/vstimd already makes it writable and the vstimd-data
    Samba share already exports it; a sibling directory needs a second
    StateDirectory and an ownership decision between services, for a sharing
    benefit no other braemons daemon wants today.
  • Phase 0 is a hard rename--config-dir--state-dir, --config
    --scene-config, the Config wire messages → SceneConfig, conn.config.*
    conn.scene_config.*, and scene-config files move into their project without the
    vstimd_ prefix. Nothing beyond v0.1.0 pre-releases has shipped, so there are
    no aliases and no migration code. This does mean anyone on a current pre-release
    must move their saved scenes by hand.
  • The active project is server-global, not per-connection. There is no session
    concept behind the REQ/REP socket and inventing one is a large change for a rig
    that usually has one client. Documented, with a ProjectChanged event, rather
    than hidden.
  • A missing asset loads the stimulus disabled with a warning, not a failed
    scene-config, because a rig must boot into a scene with no client attached.
    strict_assets gives CI the hard failure.
  • logs/ is an output in a tree of inputs — same location, different API
    (listable, downloadable, never uploadable). dev/EVENT_LOGGING.md is updated to
    point --log-dir at the project tree and keeps retention as its own concern.

Not decided

Left as open questions in §12: whether loading a scene-config should always switch
the active project, _scratch GC policy, project metadata, per-project quotas, and
sha256 vs blake3.

joschaschmiedt and others added 8 commits August 18, 2026 08:25
Design for the asset store that #108 (image stimulus), #109 (movie script) and #70 (mesh textures) all need: where asset files live on the rig, how they are addressed, the upload/list/delete protocol, and what happens to a saved config whose asset has gone missing.

Supersedes Phase A of dev/design/IMAGES_MOVIES_PLAN.md, which put the store in memory and keyed it by a flat client-chosen name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The directory is "the config dir" only because of the --config-dir flag it is named after. Once it holds assets it is no longer only configs, and the word collides with the rig-config directory. Define it by what systemd creates instead, and record the flag rename as an open question.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Bare "config" now always reads as scene-config or rig-config, per the rule in CLAUDE.md, and the plan gains a phase 0 that makes the flags and the code match before the asset store is built on top of them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Nothing is released beyond v0.1.0 pre-releases, so the naming pass drops old spellings outright: --state-dir replaces --config-dir, the scene-config wire messages and client namespaces are renamed too, and scene-configs move into <state-dir>/scene-configs/ without the vstimd_ filename prefix.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ct API

Scene-configs, assets and event logs now live together under <state-dir>/projects/<project>/, so a study is one folder to copy, archive or delete. Asset refs inside a saved scene-config become project-relative, which makes a project relocatable. Adds the active project as real server state: --project at boot, SetProject/GetProject on the wire, a ProjectChanged event, and a selector in the overlay and the web UI.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…og-dir at the project tree

Records that implementation waits for #129 and the rest of the in-flight refactors, since phase 0 renames the same flags and wire messages. EVENT_LOGGING.md now says where --log-dir lands under the project layout, and keeps retention as its own concern.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant