DASObjectStore

Imported from sagrudd/DASObjectStore (AGENTS.md). Install upstream with npx skills add sagrudd/DASObjectStore. Copyright stays with the author.

AGENTS.md

This file defines working rules for AI coding agents contributing to DASObjectStore.

Repository Discipline

• Commit after each user prompt that results in repository changes.
• Push regularly after meaningful commits, especially when work completes a prompt or leaves the repository in a useful review state.
• If another process has unrelated worktree edits, treat those paths as read-only isolation boundaries: continue only in untouched files, never stage, overwrite, reset, stash, or reformat the unrelated paths, and commit only the non-overlapping slice. Report a blocker only when integration with those edits is required.
• Keep commits focused and reviewable.
• Avoid unrelated formatting, renames, dependency changes, or cleanup while implementing a scoped request.
• Prefer surgical modifications and additions over broad rewrites.

Multi-Agent Coordination

• Use multiple worker agents judiciously when the requested work is substantial enough to benefit from parallel delivery, especially when planning, implementation, documentation, and testing can be separated cleanly.
• Keep the lead agent accountable for the final design, integration, review, test selection, and user-facing summary. Worker agents may accelerate bounded slices, but they do not replace coherent technical ownership.
• Separate work by responsibility whenever practical:
  • planning/design agents should clarify scope, risks, data-loss boundaries, interfaces, and acceptance criteria;
  • coding agents should own specific files, modules, or behavior changes with minimal overlap;
  • documentation agents should update user-facing .rst material, examples, release notes, and operator guidance;
  • testing agents should add or run focused regression, integration, packaging, or deployment checks.
• Give each worker a concrete, non-overlapping write scope and tell workers they are not alone in the codebase. They must not revert unrelated edits and must adapt to changes made by other contributors.
• Avoid spawning workers for tiny, tightly coupled, or urgent blocking tasks where delegation would add coordination overhead. Prefer local execution for the immediate critical path and use workers for parallel sidecar tasks.
• Integrate worker output deliberately: inspect diffs, reconcile overlapping assumptions, run appropriate tests from the lead context, and keep the final commit focused.
• When the user explicitly asks for multiple agents, make a brief coordination plan before delegation and keep the user informed about which responsibilities are being handled in parallel.

Deployment Host

• The DAS appliance currently used for deployment testing is stephen@192.168.1.192.
• Use the PEM at ~/.ssh/dasobjectstore-codex for SSH access: ssh -i ~/.ssh/dasobjectstore-codex stephen@192.168.1.192.
• Do not commit or copy private key material into this repository; only the expected local key path is documented here.
• The active deployment checkout on the DAS host is usually /home/stephen/src/DASObjectStore.
• Build Linux packages on the DAS host when working from a non-Linux development machine, then install the generated Debian package through APT with sudo apt-get install --reinstall ./dasobjectstore_<version>_amd64.deb and restart dasobjectstored. Do not use a raw dpkg -i deployment because installations and reinstalls must remain formally managed through APT.
• Coding agents are authorized to compile on the DAS host, install the resulting DASObjectStore package, and restart dasobjectstored for validation.
• Coding agents may create and use a dedicated CODEX ObjectStore for automated stress and ingress tests using randomly generated data only. Keep all such test data below 1 TiB total, never use user/project data, and clean it up only through documented, explicitly confirmed management commands.

Definition of Done

• A TODO item is complete only when its implementation is committed and pushed, relevant local tests pass, user/operator documentation and TODO status are updated, and the change is ready for validation with real-world data.
• Feature work is expected to reduce the approved TODO backlog each cycle; work one dependency-ordered task at a time and do not move on while a locally actionable gap in that task remains.

Versioning

• Maintain semantic versioning for every release; releases have begun at 0.1.1.
• Keep the Rust workspace package version as the source of truth for Rust crates and CLI/server --version output.
• Keep CHANGELOG.md updated for every version change.
• Use version changes intentionally:
  • patch for compatible fixes and documentation-only release corrections;
  • minor for backward-compatible features;
  • major for breaking changes.
• Apply patch and minor version bumps automatically when the delivered work warrants them.
• Do not apply a major version bump without clear agreement from both the user and the coding agent in the thread.
• Document version-impacting decisions before changing public interfaces, persistent metadata formats, CLI behavior, or store/pool compatibility rules.

Code Organization

• Keep code highly hierarchical and modular.
• Prefer small files with clear responsibility boundaries.
• Split modules when a file begins to mix concerns such as CLI parsing, domain logic, persistence, service orchestration, and presentation.
• Keep public interfaces narrow and explicit.
• Avoid circular dependencies between modules.

Churn Control

• Minimize diff size.
• Preserve existing style unless a local convention is clearly wrong or missing.
• Do not reorder code, tables, documentation sections, or imports unless it is needed for the current change.
• Do not refactor opportunistically while implementing unrelated behavior.

Redundancy

• Avoid code redundancy at all costs.
• Extract shared domain logic into well-named modules rather than duplicating behavior across CLI, daemon, Web UI, tests, or adapters.
• Keep configuration schemas, validation rules, and lifecycle state definitions single-sourced where practical.
• Prefer generated or shared types over manually duplicated API structures once schemas stabilize.

User Documentation

• Maintain user-facing documentation under docs/user/ in Sphinx/readthedocs .rst format when changing CLI workflows, disk-management behavior, store policy, NAS/NFS endpoint handling, service operation, or portability behavior.
• Keep user docs helpful but not excessive: explain the task, the safe command path, important warnings, and how to inspect the result.
• Do not document ad hoc shell procedures for storage mutations when a formal dasobjectstore management command exists or is being introduced.
• Keep examples aligned with current CLI names, defaults, confirmation phrases, and risk boundaries.
• Update docs/index.rst or docs/user/index.rst when adding, renaming, or removing user guide pages.

Project Architecture Preferences

• Keep DASObjectStore public-core first.
• Keep the implementation Rust-first unless an integration boundary clearly requires another language or tool.
• Use clap for CLI parsing and command documentation.
• Use axum for GUI-facing HTTP/API surfaces and yew for frontend GUI work.
• Treat DASObjectStore as a server/client system. Managed storage mutation belongs behind the daemon/service boundary, not inside a normal-user CLI process.
• Prefer dasobjectstored as the enterprise storage authority: disk discovery, mount validation, placement, ingest execution, destage, health mutation, disk retirement, repair, and object-service orchestration should be daemon-owned.
• Treat dasobjectstore as a client: it may parse commands, authenticate, submit jobs, stream source data, and render progress, but it should not write directly into managed DAS roots in normal operation.
• Keep eventual GUI delivery aligned with sibling Monas and Synoptikon surfaces rather than introducing an unrelated UI stack.
• Keep Mnemosyne/Synoptikon integration in an adapter layer.
• Keep storage profiles and object-service providers abstract enough to evolve without breaking pool metadata.
• Treat persistent metadata formats as compatibility-sensitive public surfaces.
• Prefer explicit state machines for disk, pool, object, ingest, and repair lifecycle behavior.
• Treat file ingress as a performance-critical product surface. SSD-first streaming, parallel HDD fan-out, verification, bounded resource use, backpressure, crash recovery, and resumability must be designed together.
• Treat the console TUI as a supported operator surface, not a developer diagnostic. It must consume the same daemon job model/events as CLI, Web UI, and Synoptikon-facing adapters.
• Reconcile standalone local authentication with the product charter before expanding administrator workflows: local OS users and sudo-derived administrator status are preferred for appliance-style standalone operation unless a documented host-mode decision supersedes that model.

Safety

• Never hide data-loss risk behind convenience.
• Risky operations must require both policy allowance and action-time confirmation.
• Health, repair, drain, and recovery paths should favor clear user-facing state over silent automation.

Kanon identity contract

• This repository's Mnemosyne product or component identity must be registered in the authoritative Kanon registry at https://github.com/sagrudd/kanon.
• Changes to the stable identifier, display name, repository location, crate, package, container, binary, product-manifest or schema coordinates, supported host modes, dependencies, compatibility, lifecycle, aliases, deprecation, or replacement must include the corresponding Kanon change in the same delivery transaction or an explicitly linked Kanon pull request.
• Before a release, verify that this repository's Kanon identity and dependency declarations match the release artefacts. Once Kanon channels and locksets are operational, releases and maintained product branches must use the applicable supported channel and pin the resolved lockset identifier and digest.
• Do not invent, rename, or reuse Mnemosyne product identifiers locally. Do not treat registration in Kanon as proof that a component is installed, entitled, healthy, or supported by every host profile.
• If live Kanon services are unavailable, use a verified pinned Kanon snapshot or lockset. Do not bypass identity or compatibility validation to make a release proceed.

Authoritative release graph: Kanon -> Terraform -> artefact

Kanon at https://github.com/sagrudd/kanon is the sole authority for this component's permanent identity, release version, source repository and revision, package/container/binary coordinates, dependencies, compatibility, lifecycle, aliases, deprecation/replacement, supported host modes and lockset membership.

A local manifest, sources.lock, Terraform catalogue or TOML projection, package metadata, existing DEB/RPM file, branch name or working checkout is never a second authority. Do not invent, copy, or override Kanon values locally to make a build or installation pass.

Any identity, version, dependency, packaging, support or provenance change must start with a coordinated Kanon registry change. If resolved content changes, create a new immutable Kanon lockset; never rewrite or republish a historical lockset. Record the linked Kanon change and exact lockset ID and content digest in the component and Terraform delivery.

Terraform must consume that exact Kanon lockset through the Kanon resolver and regenerate its compatibility projection, catalogue, adapters, package descriptions and dependency metadata. Do not hand-edit generated projections or maintain a second annotation point. The Terraform source pins and the lockset's source revisions must agree exactly.

A build, install or release is invalid unless Kanon, Terraform, the checkout, DEB/RPM control metadata and provenance agree on lockset ID and digest, component identity, version, source revision, architecture, adapter and the complete declared dependency closure. Any mismatch is a hard failure.

An existing DEB/RPM may be reused only when its exact identity, version, architecture, lockset/source provenance and dependency closure match the currently verified lockset. A same-name or same-version artefact without that match is stale and must not be installed, published or used to satisfy a dependency.

Kanon lock validation, Terraform projection/catalogue validation, adapter and package-metadata tests, and stale-artefact checks are release gates for make deb, make rpm, make install, Jenkins and customer releases. If Kanon or its pinned lockset cannot be verified, the supported build and installation path fails closed; there is no silent fallback to local metadata.

Adding a component such as Phoreus, Ergasterion, Mnematikon, Tameion or Logistes requires Kanon registration, dependency closure, lockset resolution, Terraform projection, adapter validation and DEB/RPM metadata tests before it can be described as supported. A pending or unsupported identity cannot be declared supported locally.

Before completing a change, run the repository's Kanon/lockset and package gates and record the exact lockset ID, digest and source revisions in the change or pull request. If a required Kanon or Terraform change is not available, report that as a blocker rather than shipping stale content.

Programme Governance

This repository participates in the Mnemosyne Programme.

Programme-level planning, integration priorities and dependency management are governed by:

~/Projects/mnemosyne-programme

Engineering standards are governed by:

~/Projects/mnemosyne-engineering-standard

Repository-local engineering guidance supplements, but does not replace, programme governance.