kernel-module/intent_schema.h

/**

 * intent_schema.h

 * نظام النوايا السيادي - هيكل البيانات الأساسي

 * Sovereign Intent Schema - Core Data Structures

 *

 * Author: Ahmad Ali Parr

 * License: Sovereign Source

 */

#ifndef ASOS_INTENT_SCHEMA_H
#define ASOS_INTENT_SCHEMA_H

#include <stdint.h>
#include <stddef.h>

/* ═══════════════════════════════════════════════════════════════

 * Intent Type Constants | ثوابت أنواع النوايا

 * ═══════════════════════════════════════════════════════════════ */

#define INTENT_ALLOCATE         0x01  /* Resource allocation request */
#define INTENT_IO_READ          0x02  /* Autonomous read operation */
#define INTENT_IO_WRITE         0x03  /* Durable write with WORM seal */
#define INTENT_NET_SEND         0x04  /* Network transmission */
#define INTENT_NET_RECV         0x05  /* Network receive with filter */
#define INTENT_COMPUTE          0x06  /* Offload to NPU/accelerator */
#define INTENT_QUERY_STATE      0x07  /* System state inspection */
#define INTENT_SEAL_COMMIT      0x08  /* Cryptographic state seal */

/* Priority Levels | مستويات الأولوية */
#define PRIORITY_BACKGROUND     0     /* Best-effort, defer under load */
#define PRIORITY_NORMAL         1     /* Standard application priority */
#define PRIORITY_HIGH           2     /* Time-sensitive operation */
#define PRIORITY_CRITICAL       3     /* System-critical, preemptive */

/* Trust Nonce Size (Blake3 256-bit) */
#define TRUST_NONCE_SIZE        32

/* Maximum Intent Payload Size (16KB) */
#define MAX_INTENT_PAYLOAD      (16 * 1024)

/* Maximum Goal Schema String (1KB) */
#define MAX_GOAL_SCHEMA         1024

/* ═══════════════════════════════════════════════════════════════

 * Intent Payload Structure | هيكل حمولة النية

 * ═══════════════════════════════════════════════════════════════ */

/**

 * SystemIntent - User-submitted intent payload

 *

 * Instead of imperative syscalls, applications construct an intent

 * describing WHAT they want (goal) with constraints (trust nonce,

 * priority) and let the Kernel Agent Runtime (KAR) resolve HOW.

 *

 * Memory Layout:

 * - Fixed header (64 bytes)

 * - Variable payload (up to 16KB)

 * - Trust nonce (32 bytes Blake3)

 *

 * All fields are validated at the kernel boundary.

 */
struct SystemIntent {
    /* ─── Core Intent Fields ─── */
    uint32_t intent_type;        /* One of INTENT_* constants */
    uint32_t priority;           /* Execution urgency (0-3) */
    uint32_t flags;              /* Reserved for future extensions */
    uint32_t payload_len;        /* Length of payload_data in bytes */

    /* ─── Goal Description ─── */
    /**

     * goal_schema: Symbolic or serialized description of the desired outcome.

     *

     * Examples:

     *   - "persist:durability=WORM,replication=3"

     *   - "allocate:memory=4MB,alignment=4K,zone=DMA"

     *   - "compute:model=classifier,input=tensor[224,224,3]"

     *

     * This is NOT Turing-complete code — it's a structured constraint language

     * parsed by the KAR policy engine.

     */
    char goal_schema[MAX_GOAL_SCHEMA];

    /* ─── Payload Data ─── */
    /**

     * payload_data: Pointer to working memory (user-space address).

     *

     * Kernel will copy_from_user() this safely. For zero-copy intents,

     * this can be a ring buffer descriptor instead.

     */
    void *payload_data;

    /* ─── Cryptographic Trust ─── */
    /**

     * trust_nonce: Blake3 hash of (intent_type || priority || goal_schema || timestamp)

     *

     * Verified by KAR before execution. Prevents:

     * - Intent replay attacks

     * - Privilege escalation via modified intents

     * - TOCTOU races (time-of-check to time-of-use)

     *

     * Generated by libasos in user space, validated in kernel.

     */
    uint8_t trust_nonce[TRUST_NONCE_SIZE];

    /* ─── Execution Context ─── */
    uint64_t timestamp_ns;       /* Monotonic clock at submission */
    uint32_t source_pid;         /* Process ID (set by kernel, not user) */
    uint32_t source_uid;         /* User ID (set by kernel, not user) */

} __attribute__((packed));

/* ═══════════════════════════════════════════════════════════════

 * Intent Result Structure | هيكل نتيجة النية

 * ═══════════════════════════════════════════════════════════════ */

/**

 * IntentResult - Kernel's resolved outcome

 *

 * Returned to user space after KAR processes the intent.

 * Contains execution status, resolved resource handles, and

 * cryptographic seal for audit trail.

 */
struct IntentResult {
    /* ─── Status Code ─── */
    int32_t status;              /* 0 = success, negative = error code */
    uint32_t kar_action;         /* What the KAR actually did */

    /* ─── Resolved Resources ─── */
    uint64_t resource_handle;    /* Opaque handle to kernel resource */
    size_t bytes_transferred;    /* For I/O operations */

    /* ─── Cryptographic Seal ─── */
    /**

     * worm_seal: Blake3(intent || result || timestamp)

     *

     * Immutable audit record. Can be verified against WORM chain

     * to prove this intent was executed with this outcome at this time.

     */
    uint8_t worm_seal[TRUST_NONCE_SIZE];

    /* ─── Execution Metadata ─── */
    uint64_t execution_time_ns;  /* Time spent in KAR */
    uint32_t kar_agent_id;       /* Which agent processed this */

} __attribute__((packed));

/* ═══════════════════════════════════════════════════════════════

 * Ring Buffer Entry | إدخال المخزن المؤقت الحلقي

 * ═══════════════════════════════════════════════════════════════ */

/**

 * RingBufferEntry - Single slot in the zero-copy ring

 *

 * User space writes intents here, kernel reads and marks consumed.

 * Lock-free single-producer single-consumer (SPSC) queue.

 */
struct RingBufferEntry {
    uint32_t sequence;           /* Monotonic sequence number */
    uint32_t state;              /* 0=empty, 1=submitted, 2=processing, 3=done */
    struct SystemIntent intent;  /* The intent payload */
    struct IntentResult result;  /* Filled by kernel */
} __attribute__((aligned(64))); /* Cache-line aligned */

/* Ring buffer states */
#define RB_STATE_EMPTY          0
#define RB_STATE_SUBMITTED      1
#define RB_STATE_PROCESSING     2
#define RB_STATE_DONE           3

/* ═══════════════════════════════════════════════════════════════

 * Error Codes | أكواد الأخطاء

 * ═══════════════════════════════════════════════════════════════ */

#define EINVALID_INTENT         (-1000)  /* Malformed intent structure */
#define ETRUST_NONCE_FAIL       (-1001)  /* Trust nonce validation failed */
#define EKAR_POLICY_REJECT      (-1002)  /* Policy engine rejected intent */
#define EKAR_NO_AGENT           (-1003)  /* No suitable agent available */
#define EKAR_TIMEOUT            (-1004)  /* Intent processing timeout */
#define EWORM_SEAL_FAIL         (-1005)  /* Failed to generate WORM seal */

/* ═══════════════════════════════════════════════════════════════

 * Compile-Time Assertions | تأكيدات وقت الترجمة

 * ═══════════════════════════════════════════════════════════════ */

/* Ensure structures are properly sized for efficient copying */
_Static_assert(sizeof(struct SystemIntent) <= 2048,
    "SystemIntent too large - exceeds efficient copy threshold");
_Static_assert(sizeof(struct IntentResult) <= 256,
    "IntentResult too large - should fit in 4 cache lines");
_Static_assert(sizeof(struct RingBufferEntry) % 64 == 0,
    "RingBufferEntry not cache-aligned");

#endif /* ASOS_INTENT_SCHEMA_H */