// =============================================================
// FROZEN. Wire contract between hub and modules.
// =============================================================
//
// This file is the stable wire contract between the F∆I Hub
// and any module compiled against it. It is **frozen at v1.0**.
//
// Frozen means:
//
//   - No removal, rename, or signature change of any existing
//     interface, function, type, field, or variant case.
//   - Additive changes (new types, new variant cases at the end,
//     new fields with stable defaults) require a minor bump
//     (1.0 -> 1.1) and a coordinated review.
//   - Any breaking change requires a major bump (1.0 -> 2.0)
//     and a parallel-world transition plan.
//
// The fai_runtime crate ships a snapshot test that fails if
// this file changes without an intentional, reviewed update.
// See `crates/fai_runtime/tests/wit_freeze.rs`.
//
// Module authors do NOT depend on this file directly. They
// use `fai-module-sdk`, which wraps these bindings behind a
// stable, ergonomic surface. That is what protects modules
// from any future evolution of this contract.

package fai:platform@1.0.0;

/// Types that flow between the host (hub) and modules.
interface types {
  /// A typed value passed between the host and a module.
  variant payload {
    /// Plain UTF-8 text.
    text(string),
    /// Arbitrary JSON encoded as a string.
    json(string),
    /// Raw bytes with a MIME type.
    bytes(bytes-value),
    /// A reference to a file, by URI.
    file-ref(file-ref),
  }

  /// Inline byte content.
  record bytes-value {
    mime-type: string,
    data: list<u8>,
  }

  /// File reference by URI.
  record file-ref {
    uri: string,
    mime-type: string,
    size-bytes: u64,
    sha256: string,
  }

  /// Context passed with every invocation.
  record invocation-context {
    invocation-id: string,
    capability-namespace: string,
    capability-name: string,
    deadline-ms: u64,
  }

  /// Structured error type returned by modules.
  variant invocation-error {
    invalid-input(string),
    permission-denied(string),
    resource-exhausted(string),
    deadline-exceeded,
    internal(string),
  }
}

/// The host-provided interface that modules can import to talk back.
interface host {
  /// Log a structured message. Level is "trace", "debug", "info", "warn", "error".
  log: func(level: string, message: string);
}

/// The core interface every module exports.
interface invoke {
  use types.{payload, invocation-context, invocation-error};

  /// Invoke the module with inputs, receive outputs or an error.
  invoke: func(
    ctx: invocation-context,
    inputs: list<tuple<string, payload>>,
  ) -> result<list<tuple<string, payload>>, invocation-error>;
}

/// The world a module component targets.
///
/// Modules `export` the invoke interface to be callable by the hub.
/// Modules `import` the host interface to emit logs.
world module {
  import host;
  export invoke;
}