yams/docs/spec

YAMS Interfaces & Versions

This directory contains interface specifications and schemas for YAMS plugins and public surfaces.

• wit/ – WIT definitions for WASM components (e.g., object_storage_v1.wit, dr_provider_v1.wit).
• New: graph_adapter_v1.wit defines a read-focused property-graph interface with cursor-based iteration and optional import/export and delta-apply.
• schemas/ – JSON Schemas describing manifests and interface payloads.
• interface_versions.json – authoritative version registry for public interfaces:
  • Keys: plugin_abi, object_storage_v1, dr_provider_v1, model_provider_v1, etc.
  • New: graph_adapter_v1, graphjson_v1, graph_delta_v1, provenance_v1, card_anchor_v1.
  • Bump the corresponding version when changing WIT/schemas/headers for that interface.

Daemon IPC Note

• Daemon-managed download jobs are now implemented as an internal IPC surface with:
  • guarded start via DownloadRequest
  • job status
  • job listing
  • job cancel
• This surface is policy-gated, disabled by default, and not yet treated as a stable external versioned interface in the same way as plugin WIT/schema specs. Policy
• Any change to public surfaces requires either:
  • A version bump in docs/spec/interface_versions.json for the affected interfaces, or
  • A CHANGELOG/stability note explicitly acknowledging the change.
• CI enforces this via scripts/ci/check_yams_semver.py during build.

Plugin Naming Policy (ABI)

• ABI plugins have a configurable naming policy that controls how the daemon chooses a display identity and deduplicates multiple file variants (e.g., libyams_foo_plugin.* and yams_foo_plugin.*) across Linux and macOS:

  • relaxed (default):
    • Canonicalize derived names from filenames when a manifest name is not present.
    • Prefer non-lib prefixes when both variants exist in the same directory.
    • De-duplicate providers by logical name with a path priority of user > system locations.
  • spec:
    • Respect the plugin’s manifest name verbatim for display and selection.
    • Still de-duplicate file variants that provide the same provider.

• Configuration:

  • Env: YAMS_PLUGIN_NAME_POLICY=spec|relaxed
  • Daemon config: plugin_name_policy: spec|relaxed (if supported by your deployment)

Security and Trust

• Plugins are only loaded from trusted paths. The canonical trust file is <data_dir>/plugins.trust (default ~/.local/share/yams/plugins.trust, one absolute path per line). CLI helpers: yams plugin trust add|remove ....
• For development, YAMS_PLUGIN_TRUST_ALL=1 can be set to trust directories discovered in the standard search order; do not use this in production.

Notes

• Keep WIT and schema filenames aligned with the version keys (e.g., object_storage_v1.wit, object_storage_v1.schema.json) so automated mapping is accurate.
• For new interfaces, add an entry to interface_versions.json when introducing the first version.
• GraphAdapter v1 provides read-first APIs. Write operations are intentionally scoped to import and delta-apply to keep implementations simple and deterministic.