docs(dev): plan projects and the on-device asset store - #131
Draft
joschaschmiedt wants to merge 8 commits into
Draft
docs(dev): plan projects and the on-device asset store#131joschaschmiedt wants to merge 8 commits into
joschaschmiedt wants to merge 8 commits into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Design document only — no code, no proto, no behaviour change. Adds
dev/design/ASSET_STORE_PLAN.mdand one clarifying edit todev/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:
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 —
--projectat boot,SetProject/GetProjecton the wire with aProjectChangedevent, implicit onscene-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'sStateDirectory=braemons/vstimdalready makes it writable and thevstimd-dataSamba share already exports it; a sibling directory needs a second
StateDirectoryand an ownership decision between services, for a sharingbenefit no other braemons daemon wants today.
--config-dir→--state-dir,--config→--scene-config, theConfigwire messages →SceneConfig,conn.config.*→conn.scene_config.*, and scene-config files move into their project without thevstimd_prefix. Nothing beyondv0.1.0pre-releases has shipped, so there areno aliases and no migration code. This does mean anyone on a current pre-release
must move their saved scenes by hand.
concept behind the REQ/REP socket and inventing one is a large change for a rig
that usually has one client. Documented, with a
ProjectChangedevent, ratherthan hidden.
scene-config, because a rig must boot into a scene with no client attached.
strict_assetsgives CI the hard failure.logs/is an output in a tree of inputs — same location, different API(listable, downloadable, never uploadable).
dev/EVENT_LOGGING.mdis updated topoint
--log-dirat 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,
_scratchGC policy, project metadata, per-project quotas, andsha256 vs blake3.