trevon/yams
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2
yams/docs/spec
History
Exact
trvon b065e6a2c1
 v0.7.5
2025-10-11 00:34:31 -04:00
..
schemas stagging v0.7.0 2025-09-25 16:40:56 -04:00
wit stagging v0.7.0 2025-09-25 16:40:56 -04:00
interface_versions.json v0.7.5 2025-10-11 00:34:31 -04:00
plugin_metadata.schema.json v0.6.12 experiemental 2025-09-11 11:28:42 -04:00
plugin_spec.md stagging v0.7.0 2025-09-25 16:40:56 -04:00
README.md stagging v0.7.0 2025-09-25 16:40:56 -04:00

README.md

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.

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 PBI update 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 default trust file is ~/.config/yams/plugins_trust.txt (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.