/**
 * `/proc/bare_os/protomux_extensions.json` — policy-gated operator view of Protomux
 * channel hints for kernel extensions (no wire secrets).
 */

/**
 * @param {Record<string, string | undefined>} env
 */
function protomuxExtensionsRegistryExposed(env) {
  const v = String(env?.BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY ?? '')
    .trim()
    .toLowerCase()
  return v === '1' || v === 'true' || v === 'yes'
}

/**
 * @param {{
 *   env?: Record<string, string | undefined> | null,
 *   registrySnapshot?: Record<string, unknown> | null,
 *   ctxApiVersion?: string
 * }} opts
 */
export function buildBareOsProtomuxExtensionsProcJson(opts = {}) {
  const env = opts.env && typeof opts.env === 'object' ? opts.env : {}
  const now = Date.now()
  if (!protomuxExtensionsRegistryExposed(env)) {
    return {
      schema: 1,
      exposed: false,
      note:
        'Set BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY=1 to expose extension mux hints (alias registry snapshot + stable logical channel names).',
      atMs: now
    }
  }
  const snap =
    opts.registrySnapshot && typeof opts.registrySnapshot === 'object'
      ? opts.registrySnapshot
      : {}
  return {
    schemaVersion: 4,
    guestContractVersion: 1,
    exposed: true,
    ctxApiVersion: String(opts.ctxApiVersion || ''),
    registry: snap,
    muxWirePackage: 'protomux',
    muxWireMajor: 3,
    channelLifecycle: {
      schema: 1,
      states: ['paired', 'opening', 'open', 'closing', 'closed'],
      backpressureEvent: 'bare-os:protomux-backpressure',
      note:
        'Guest-facing contract: logical channels follow Protomux createChannel/open/close; framed streams must preserve message boundaries (length-prefixed / secret-stream).'
    },
    holepunchCompanionPackages: {
      rpcPool: 'protomux-rpc-client-pool',
      note:
        'Logical npm names in the Holepunch org; stock guest does not bundle them unless merged via ctx.bare.'
    },
    extensionLogicalChannels: [
      {
        name: 'bare-os-kernel-ext-handshake',
        note: 'Reserved logical label for extension pairing over Protomux-framed streams (P2P).'
      },
      {
        name: 'bare-os-extension-telemetry',
        note: 'Optional NDJSON-shaped diagnostic channel; host must open explicitly.'
      },
      {
        name: 'bare-os-cap-v1',
        protocol: 'bare-os-cap-v1',
        envGate: 'BARE_OS_PROTOMUX_CAP_CHANNEL',
        note: 'Opaque buffer side channel; application-layer auth required.'
      }
    ],
    wireReference: '/proc/bare_os/protomux.json',
    atMs: now
  }
}