Build original Ada port core, V client, and x86-64 boot milestone

docs/ARCHITECTURE.md

@@ -0,0 +1,52 @@
+# Open Agila architecture direction
+
+Status: original implementation, early boot and host-port milestone. This document separates implemented mechanisms from the proposed architecture.
+
+## Design references
+
+[OpenStep](https://www.gnustep.org/resources/OpenStepSpec/OpenStepIntro/TXT.html) describes an OS-independent object-oriented application layer, including Foundation and Application Kit. Agila will define its own Ada/V framework contracts first; compatibility requires separately scoped conformance tests.
+
+[MINIX architecture](https://wiki.minix3.org/doku.php?id=developersguide:overviewofminixarchitecture) separates a small privileged kernel from user-mode drivers and services, with explicit communication and authority checks. Open Agila's target is a small kernel and restartable services, not reuse of MINIX code or its exact IPC ABI.
+
+The owner has a specific Open Amiga repository. Its URL/path, license, APIs, and tested targets are pending. No alternative project has been substituted, and no integration or compatibility claim is made.
+
+## Target structure
+
+```mermaid
+flowchart TD
+  Apps[Applications in V / Flying V and Ada] --> Frameworks[Agila application and foundation contracts]
+  Frameworks --> Services[User services: UI, files, network, audio]
+  Services --> IPC[Versioned IPC and scoped resource grants]
+  IPC --> Kernel[Ada kernel: address spaces, scheduling, IPC, interrupts]
+  Drivers[User device drivers] --> IPC
+  Kernel --> Hardware[CPU, memory and devices]
+```
+
+Only the bounded port mechanism and minimal boot path are implemented here. The service, syscall, framework, scheduler, and driver layers in this diagram are future work.
+
+## Current mechanism
+
+`Agila_Ports.Manager` owns eight independent ports. Each holds four `(sender, value)` messages. Operations are non-blocking: a full queue returns `Full`; an empty queue returns `Empty`. Each port has an owner and at most one additional allowed sender. Only the owner can receive, grant, revoke, or close. Granting a different sender replaces the previous extra grant. Revocation prevents future sends; already queued messages remain queued.
+
+The handle encodes a slot and generation. Closing clears queued data and advances the generation. A stale handle cannot address a reopened port. A slot retires at generation exhaustion instead of wrapping and making an ancient handle valid again. This is a reference-validity mechanism, not an unforgeable capability.
+
+The host adapter accepts identity integers from its caller and stores a single global manager. It is deliberately single-threaded. A real syscall boundary must derive the caller from trusted scheduler state, validate user buffers, and synchronize shared state. An application that can choose its own identity can impersonate another caller in this demonstration.
+
+## Boot boundary
+
+The BIOS/Multiboot entry starts in 32-bit mode, installs a GDT, creates temporary identity mappings for the first GiB, enables long mode, establishes a stack, and calls Ada. It assumes an x86-64-capable target. The mapping uses writable, executable 2 MiB pages and does not establish user/kernel protection.
+
+The Ada entry verifies the Multiboot magic and exercises the port core before reporting success. The small C file only supplies compiler memory-copy/fill routines; it is not a memory allocator. Runtime checks remain enabled in host tests. The bare-metal build suppresses GNAT runtime checks because exception handling and the runtime are not yet ported. Explicit boot test conditions remain active. This is not a proof that every unchecked Ada execution is safe.
+
+## Language roles
+
+- Ada: explicit kernel data structures and policies, bounded operations, contracts/tests, later scheduling and memory mechanisms.
+- Standard V: host tools and initial application/service clients through documented interfaces.
+- Flying V: a separate Agila application language, used only through its actual published SDK/toolchain contracts.
+- Assembly and minimal C: necessary startup/ABI support, kept small and reviewed.
+
+Future service interfaces should use versioned fixed-width fields and validated lengths rather than exposing Ada record layouts, V objects, host pointers, or compiler-specific enums across address spaces.
+
+## Evidence before claims
+
+A host check demonstrates data-structure behavior under a host runtime. A QEMU boot check demonstrates a particular virtual machine and code path. Neither proves user-mode isolation, fault recovery, compatibility, or physical-device support. Those require the explicit tests in the roadmap.

docs/GOAL.txt

@@ -0,0 +1,26 @@
+Build Open Agila and grow its developer community
+
+Objective
+Develop Open Agila into a reproducibly buildable, open operating system, primarily in Ada and V. Use OpenStep as an application-framework reference and MINIX as a reference for a small kernel, explicit IPC, least authority, and restartable services. Inspect the specific Open Amiga repository supplied by the owner before deciding what to integrate. Do not substitute AROS or a different Amiga project without that evidence.
+
+Begin with the existing Agila Forge repositories and preserve their history, licenses, and working behavior. Keep Open Agila development distinct from private Agila OS components. Do not publish private source, credentials, or unexplained third-party binaries. Keep Flying V distinct from standard V and use its actual compiler/SDK contracts.
+
+Build in verifiable milestones
+1. Audit current code and publish an architecture, source inventory, supported-target matrix, and backlog with testable acceptance criteria.
+2. Make the existing host build repeatable. Implement a bounded Ada message-port core, explicit access checks, and a V client through a documented ABI. Test errors, capacity limits, stale handles, and invalid requests as well as successful behavior.
+3. Produce a minimal x86-64 QEMU boot target with serial output and a bounded smoke test. Clearly distinguish bare-metal boot evidence from host simulations.
+4. Progress toward memory management, exception/interrupt handling, scheduling, separate address spaces, IPC syscalls, restartable user services, storage, networking, and device drivers. State what is implemented, simulated, untested, or planned. Add real isolation tests before describing a service as isolated.
+5. Build the application/runtime layer and OpenStep-informed framework contracts in Ada and V/Flying V. Develop compatibility only against an identified specification and executable conformance tests. Integrate the owner's Open Amiga source only after reviewing its APIs, provenance, and license.
+6. Add CPU/GPU topology, memory mappings, synchronization, and measured workload placement as hardware support becomes available. Label simulated measurements and untested hardware honestly.
+
+Expand Agila Forge
+Publish working source, build instructions, examples, tests, architecture decisions, and contribution guides. Organize real starter tasks and larger milestones with acceptance criteria. Make it easy for a new developer to clone, build, reproduce a test, submit a patch, and explain the result. Preserve the restored repositories and hosting protections. Do not enable execution of untrusted CI jobs on the production Forge host.
+
+Expand Agila University
+Turn each verified implementation milestone into English, Tagalog, and Bisaya lessons of approximately 15 minutes, with runnable browser exercises where supported, automated checks, feedback, and links to the exact source. Retain lesson and track completion certificates. Connect learning tracks to projects and real Forge contributions. A certificate records completed checks; tested code, explanations, documentation, and portfolio work provide additional evidence of skill. No human mentor is required for lesson progression.
+
+Definition of progress
+Report exact commits, reproducible commands, test results, supported targets, and remaining work. Do not call a host prototype a bootable OS, a boot demo a complete operating system, or a model a measured hardware result. Avoid promises of full compatibility or professional mastery without evidence. Continue useful independent work while a specific integration detail is awaiting clarification.
+
+Long-term success
+A growing pool of developers can independently understand, test, maintain, and extend Open Agila: applications, websites, server systems, OS components, and AI runtimes. Judge success through working contributions and understanding, including the ability to review AI-generated code.

docs/HOST_ABI.md

@@ -0,0 +1,15 @@
+# Host port ABI v0
+
+This ABI exists to test Ada/V interoperability. It is not a syscall ABI and is not stable for production applications.
+
+The C header in `include/agila_ports.h` is the shared declaration. All identity, handle, and message-value fields are `uint32_t`. Status values are C `int`: 0 success, 1 invalid handle, 2 permission denied, 3 full, 4 empty, 5 exhausted, 6 invalid argument. The Ada library uses GNAT's automatic elaboration for a shared standalone library.
+
+`agila_port_create(owner)` returns a nonzero handle or zero if the owner is zero or every slot is active/retired. The core Ada API distinguishes those failures; the initial host wrapper intentionally has the smaller return shape.
+
+The owner can grant one additional sender, replace that sender, revoke that exact grant, receive, and close. The owner retains its own send permission. Sender zero is invalid. Revocation does not remove accepted messages. Closing clears the queue and invalidates the handle. A rejected operation does not insert or remove a message.
+
+`agila_port_receive(handle, caller, value)` requires either a valid writable pointer to a `uint32_t`, or NULL. NULL returns invalid argument. On other failures a valid output pointer receives zero. Arbitrary invalid pointers are outside this trusted host ABI contract; the wrapper does not attempt to probe application memory. A future kernel API must validate/copy user buffers through a different boundary.
+
+Calls must be serialized by the host application. The library does not implement locking, separate processes, caller authentication, transport, persistence, or shared-memory ownership. The generation-checked handle is not a secret authorization token.
+
+The V demonstration covers denied sends, grant, send/receive, revocation, close, and stale-reference rejection. The C test covers NULL and full-width unsigned values. The Ada tests cover ring wrap, FIFO order, exhaustion, permission failures, and independent ports.

docs/ROADMAP.md

@@ -0,0 +1,28 @@
+# Roadmap and acceptance evidence
+
+Each milestone should include source, tests, an exact build command, and an accompanying University lesson. The remaining work is substantial; the first boot milestone is not a complete OS.
+
+| Milestone | State | Acceptance evidence |
+| --- | --- | --- |
+| M0: honest source inventory and host build | Implemented | `make run` accurately reports placeholders; build instructions reproduce |
+| M1: bounded Ada ports and V interoperability | Implemented | `make test` passes normal, denied, boundary, stale-reference, and ABI checks |
+| M2: x86-64 virtual-machine boot | Implemented | `make boot-test` checks long-mode Ada entry, shared port-core tests, serial proof and exit status |
+| M3: exceptions and physical-memory inventory | Planned | Controlled exceptions produce structured diagnostics; parse Multiboot memory data with bounds; never allocate reserved/kernel/page-table/stack regions |
+| M4: page allocator and protected address spaces | Planned | Reuse/free exhaustion tests; read-only and unmapped access faults; separate users cannot read each other's pages; executable/write policies defined |
+| M5: timer, context switching and scheduling | Planned | Two tasks make progress; register/context preservation; bounded queues; starvation/cancellation cases documented |
+| M6: syscall IPC and service restart | Planned | Identity comes from trusted task state; invalid user pointers fail safely; service crash/restart does not corrupt another service; stale endpoint references fail |
+| M7: storage, network and devices | Planned | Disposable virtual disk/network tests; crash/recovery and corruption cases; no physical-disk experiments without explicit approval |
+| M8: application/framework contracts | Planned | Versioned Ada/V APIs, event loop, lifetime rules, serialization tests, and a working sample application |
+| M9: Open Amiga integration | Awaiting source | Identify owner's repository, license, architecture and build; choose bounded component and test compatibility explicitly |
+| M10: additional ISAs and CPU/GPU placement | Planned | Independent target boots, measured topology/transfer/latency evidence, synchronization tests; unsupported targets clearly labeled |
+
+## Useful first contributions
+
+1. Add an independently written randomized FIFO reference-model test and demonstrate that a deliberate queue bug is caught.
+2. Test replacement of an allowed sender and the policy for messages already queued before revocation.
+3. Add a boot-failure fixture or reproducible fault injection so the smoke test is shown to reject a false pass.
+4. Improve translated build instructions with actual commands and captured output from a clean machine.
+5. Design bounded parsing of the bootloader memory map with malformed/truncated fixtures before touching an allocator.
+6. Specify a versioned service-message format with length, operation, request ID, and serialization test vectors.
+
+Every task should identify the relevant files, expected behavior, tests to run, and limits. Review must assess whether evidence establishes the claimed property, not just whether a demo prints a success message.

docs/VALIDATION.md

@@ -0,0 +1,34 @@
+# Milestone validation — 1 November 2026
+
+Target: Ubuntu 24.04 x86-64 development environment; GCC/GNAT 13; V 0.5.2 (`7647ce1`); QEMU TCG, `qemu64`, one virtual CPU, 64 MiB guest memory, BIOS/GRUB Multiboot. Builds and QEMU ran as an unprivileged account, not as the web or Forge service.
+
+Commands:
+
+```sh
+make test V=/opt/agila-v/v
+make boot-test
+```
+
+Observed host results:
+
+```text
+ADA_PORTS_OK: FIFO, wrap, full/empty, grants, revocation, stale handles, exhaustion, port separation
+ADA_V_PORTS_OK value=42
+Host ABI demo: caller IDs are trusted inputs; no process isolation is claimed.
+```
+
+The C ABI test exited successfully after checking NULL output, full-width unsigned payload, empty output, and close behavior. Host Ada checks and overflow checks were enabled.
+
+Observed virtual-machine result:
+
+```text
+OPEN_AGILA_X86_64_ADA
+ADA_PORTS_BOOT_TESTS_OK
+Boot milestone: one address space; no user services or desktop yet.
+AGILA_BOOT_OK
+QEMU_BOOT_SMOKE_PASS
+```
+
+QEMU exited with status 33, the success code produced by the configured debug-exit device. The smoke test requires that exit status and all three success markers. It fails on timeout, a missing image, a wrong exit status, or missing proof text.
+
+This validates the listed code paths on this virtual-machine target. It does not validate user-space isolation, arbitrary input pointers, concurrent callers, generation-counter exhaustion after hundreds of millions of closes, UEFI, physical hardware, other ISAs, GPU work, or framework compatibility.