/* SPDX-License-Identifier: LicenseRef-Starship-1.0
 * Copyright (c) 2023-2026 Robert A. James
 */
/* sk_v4_identity.h -- the identity gate for the v4 boot: no identity drive,
 * headless; Zuse's minted thumbdrive, a console.
 * docs/v4.0.0/plans/2026-10-26-engine-step4-identity-gate.md.
 *
 * Built only with STARFORTH_V4=1 (Kconfig.kernel).
 */
#ifndef STARKERNEL_V4_SK_V4_IDENTITY_H
#define STARKERNEL_V4_SK_V4_IDENTITY_H

#include "uefi.h"   /* BootDisk */
#include "blkio.h"
#include "starkernel/v4/sk_v4_marker.h"

/* After POST and the block chain: every xHCI controller brought up, and the
 * heartbeat started, as the v3 path does before its headless wait. `boot_disk`
 * is the loader's (uefi_loader.c): a USB disk is this system's stick if it is
 * that disk, or -- when the boot disk is not a stick -- the first USB disk
 * with both StarshipOS partitions. Zuse's public key is read once the stick's
 * Artemis partition is attached (docs/v4.0.0/plans/2026-10-27-stick-4-one-disk.md,
 * Task 4). */
void sk_v4_identity_boot(const BootDisk *boot_disk);

/* 1 while Zuse's session holds: her drive is attached and checked. */
int sk_v4_identity_present(void);

/* Service the heartbeat and, once a second, the USB drives that have arrived
 * or left (v3's idle beat, its USB part).  Called while waiting for a key
 * with nothing typed. */
void sk_v4_identity_beat(void);

/* The USB drives that have arrived or left, now, not waiting for the next
 * beat: before each prompt, so that a drive pulled while the last line ran
 * is seen before a prompt is shown. */
void sk_v4_identity_check_now(void);

/* MINT-ZUSE (plan 2026-10-29-stick-5, Task 4): beat until a stick that is not
 * this system's arrives -- it is offered, not attached or refused: 1, its raw
 * device and size in bytes -- or a key is pressed, or the system stick
 * leaves: 0. */
int sk_v4_identity_offer_wait(blkio_dev_t **raw, uint64_t *bytes);

/* For the mint: the system stick's Artemis is attached; the offered stick is
 * still plugged in; the offered stick handed back unused (a mint refused or
 * stopped -- the next mint offers it again); the genesis marker as read, and
 * as the mint has just written it. */
int  sk_v4_identity_stick_in(void);
int  sk_v4_identity_offered_present(void);
void sk_v4_identity_release_offered(void);
const sk_v4_marker_t *sk_v4_identity_marker(void);
void sk_v4_identity_set_marker(const sk_v4_marker_t *m);

/* The arrival check run again on the offered stick, now that the mint has
 * written its GPT and identity (it is then recognised as the real Zuse's). */
void sk_v4_identity_recheck_offered(void);

/* Headless: no prompt, and what is typed is read and dropped, until Zuse's
 * session begins (v3's sk_repl_headless_wait()). */
void sk_v4_identity_wait(void);

#endif /* STARKERNEL_V4_SK_V4_IDENTITY_H */