/*
  StarForth — Steady-State Virtual Machine Runtime

  Copyright (c) 2023–2025 Robert A. James
  All rights reserved.

  This file is part of the StarForth project.

  Licensed under the StarForth License, Version 1.0 (the "License");
  you may not use this file except in compliance with the License.

  You may obtain a copy of the License at:
      https://github.com/star.4th@proton.me/StarForth/LICENSE.txt

  This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
  express or implied, including but not limited to the warranties of
  merchantability, fitness for a particular purpose, and noninfringement.

 See the License for the specific language governing permissions and
 limitations under the License.

 */

/**
 * session.h - Per-VM session (FABRIC-3.md §H, decided 2026-09-02/03)
 *
 * A session is a Stadium patron (FABRIC-3.md §H.1) -- registering a session
 * IS admitting a patron to the Stadium, not a new parallel bookkeeping
 * structure. This struct is the piece that sits ALONGSIDE the patron,
 * referencing it by VMUuid rather than being indexed by Stadium cell index
 * or grown as inline fields on StadiumPatronHeader/struct VM (deliberately
 * its own header, mirroring VMUuid's/VMIdentity's own precedent -- standing
 * instruction: give real-shaped data its own header and integrate as a
 * field, don't grow existing structs ad hoc).
 *
 * Fields (FABRIC-3.md §H.2, all five confirmed 2026-09-02/03):
 *   vm_id    -- the patron this session references.
 *   pinned   -- session is AUTHORITATIVE over Stadium's STADIUM_FLAG_PIN
 *               bit (§H.10): the sole read/write path for pin state is
 *               session_set_pinned()/session_is_pinned() below, nothing
 *               else (including existing Stadium code) may touch
 *               STADIUM_FLAG_PIN directly.
 *   parent   -- who birthed this session (Hera -> Hermes/Artemis, etc).
 *   name     -- canonical human-readable name; feeds console.c's
 *               g_active_vm_name prefix, does not replace the
 *               console-binding mechanism itself.
 *   identity -- embedded VMIdentity (FABRIC-3.md §H.4's VM card is
 *               effectively VMIdentity's existing ownership check; reused
 *               directly here, not reinvented).
 *
 * Explicit user framing (2026-09-02), still true: "we're gonna be
 * revisiting this part of it around and around for a while" -- treat this
 * shape as a live working draft, not permanently locked.
 */

#ifndef STARKERNEL_SESSION_H
#define STARKERNEL_SESSION_H

#ifdef __STARKERNEL__

#include <stdint.h>

#include "starkernel/vm_uuid.h"
#include "starkernel/vm_identity.h"

/* Matches console.c's CONSOLE_VM_NAME_BUF precedent -- same order of
 * magnitude for the same kind of data (a short human-readable VM name). */
#define SESSION_NAME_BUF 64

typedef struct {
    VMUuid     vm_id;                    /* the patron this session references */
    int        pinned;                   /* authoritative over STADIUM_FLAG_PIN; see
                                           * session_set_pinned()/session_is_pinned() */
    VMUuid     parent;                   /* who birthed this session */
    char       name[SESSION_NAME_BUF];   /* canonical human-readable name */
    VMIdentity identity;                 /* embedded, not referenced -- see vm_identity.h */
} Session;

#endif /* __STARKERNEL__ */

#endif /* STARKERNEL_SESSION_H */