harn-stdlib 0.10.118

import "std/schema"

pub const COORD_SCHEMA: string = "harn.coordination.message.v1"

pub const COORD_RECEIPT_SCHEMA: string = "harn.coordination.receipt.v1"

pub const COORD_KINDS: list<string> = [
  "status",
  "claim",
  "ack",
  "done",
  "finding",
  "checkin",
  "heartbeat",
  "handoff",
  "blocker",
  "decision",
  "request",
  "fact",
]

fn __coord_number_schema() -> any {
  return schema_union([schema_int(), schema_float()])
}

/**
 * Return the schema for normalized coordination actor/address dictionaries.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_actor_schema() -> any {
  return schema_object(
    {
      agent: schema_field(schema_string(), false),
      session_id: schema_field(schema_string(), false),
      root_session_id: schema_field(schema_string(), false),
      worker_id: schema_field(schema_string(), false),
      run_id: schema_field(schema_string(), false),
      task_id: schema_field(schema_string(), false),
      root_task_id: schema_field(schema_string(), false),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Return the schema for normalized coordination references.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_ref_schema() -> any {
  return schema_object(
    {
      kind: schema_field(schema_string(), false),
      ref: schema_field(schema_string(), false),
      url: schema_field(schema_string(), false),
      title: schema_field(schema_string(), false),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Return the schema for durable coordination messages.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_message_schema() -> any {
  return schema_object(
    {
      schema: schema_literal(COORD_SCHEMA),
      id: schema_string(),
      scope: schema_enum(["session", "pipeline", "tenant", "workspace", "task"]),
      scope_id: schema_string(),
      room: schema_string(),
      kind: schema_enum(COORD_KINDS),
      from: coord_actor_schema(),
      to: schema_field(
        schema_union([schema_string(), coord_actor_schema(), schema_list(schema_any())]),
        false,
      ),
      subject: schema_string(),
      body: schema_string(),
      data: schema_field(schema_any(), false),
      refs: schema_list(coord_ref_schema()),
      related_ids: schema_list(schema_string()),
      reply_to: schema_field(schema_string(), false),
      thread_id: schema_field(schema_string(), false),
      dedupe_key: schema_field(schema_string(), false),
      ts: schema_field(schema_string(), false),
      seq: schema_field(schema_int(), false),
      created_at: schema_string(),
      ttl: schema_field(schema_any(), false),
      privacy: schema_field(schema_any(), false),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Return the schema for receipts produced by coordination writes.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_receipt_schema() -> any {
  return schema_object(
    {
      schema: schema_literal(COORD_RECEIPT_SCHEMA),
      id: schema_string(),
      event_id: schema_union([schema_string(), schema_int()]),
      duplicate: schema_bool(),
      scope: schema_enum(["session", "pipeline", "tenant", "workspace", "task"]),
      scope_id: schema_string(),
      room: schema_string(),
      kind: schema_enum(COORD_KINDS),
      subject: schema_string(),
      channel: schema_dict(schema_any()),
      message: coord_message_schema(),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Return the schema for event/message wrappers from coordination reads.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_event_message_schema() -> any {
  return schema_object(
    {event: schema_dict(schema_any()), message: coord_message_schema()},
    {additional_properties: schema_any()},
  )
}

fn __coord_inbox_message_schema() -> any {
  return schema_union([coord_message_schema(), coord_event_message_schema()])
}

/**
 * Return the schema for `coord_inbox` results.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_inbox_schema() -> any {
  return schema_object(
    {
      consumer_id: schema_string(),
      from_cursor: schema_field(schema_any(), false),
      last_scanned_cursor: schema_field(schema_any(), false),
      next_cursor: schema_field(schema_any(), false),
      scanned: schema_int(),
      messages: schema_list(__coord_inbox_message_schema()),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Return the schema for `coord_wait_reply` results.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_wait_reply_schema() -> any {
  return schema_object(
    {
      status: schema_enum(["matched", "timeout"]),
      matched: schema_bool(),
      timed_out: schema_bool(),
      request_id: schema_string(),
      thread_id: schema_string(),
      consumer_id: schema_string(),
      reply: schema_field(__coord_inbox_message_schema(), false),
      replies: schema_list(__coord_inbox_message_schema()),
      inbox: schema_field(coord_inbox_schema(), false),
      next_cursor: schema_field(schema_any(), false),
      acknowledged: schema_field(schema_any(), false),
      elapsed_ms: __coord_number_schema(),
    },
    {additional_properties: schema_any()},
  )
}

/**
 * Validate a coordination message and return the full schema report.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_message_report(value: unknown, apply_defaults: bool = false) -> SchemaReport<dict> {
  return get_typed_report(value, coord_message_schema(), apply_defaults)
}

/**
 * Validate and normalize a coordination message.
 *
 * @effects: []
 * @errors: ["schema validation failure"]
 */
pub fn coord_message_value(value: unknown, apply_defaults: bool = false) -> dict {
  return get_typed_value(value, coord_message_schema(), apply_defaults)
}

/**
 * Validate a coordination receipt and return the full schema report.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_receipt_report(value: unknown, apply_defaults: bool = false) -> SchemaReport<dict> {
  return get_typed_report(value, coord_receipt_schema(), apply_defaults)
}

/**
 * Validate and normalize a coordination receipt.
 *
 * @effects: []
 * @errors: ["schema validation failure"]
 */
pub fn coord_receipt_value(value: unknown, apply_defaults: bool = false) -> dict {
  return get_typed_value(value, coord_receipt_schema(), apply_defaults)
}

/**
 * Validate a coordination inbox result and return the full schema report.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_inbox_report(value: unknown, apply_defaults: bool = false) -> SchemaReport<dict> {
  return get_typed_report(value, coord_inbox_schema(), apply_defaults)
}

/**
 * Validate a coordination wait result and return the full schema report.
 *
 * @effects: []
 * @errors: []
 */
pub fn coord_wait_reply_report(value: unknown, apply_defaults: bool = false) -> SchemaReport<dict> {
  return get_typed_report(value, coord_wait_reply_schema(), apply_defaults)
}

/**
 * Normalize and validate one coordination message kind.
 *
 * @effects: []
 * @errors: ["unsupported coordination message kind"]
 */
pub fn coord_kind(value: unknown) -> string {
  const kind = lowercase(trim(to_string(value ?? "status")))
  if !contains(COORD_KINDS, kind) {
    throw "std/coordination: unsupported message kind `" + kind + "`"
  }
  return kind
}