Phase 0: bootstrap repository and freeze public contracts #12

Merged

lost-rob0t merged 32 commits from codex/issue-1-phase-0-contracts-a1 into main

2026-08-03 09:21:03 +00:00

lost-rob0t commented

2026-08-03 07:57:43 +00:00

(Migrated from github.com)

Closes #1

Implemented

establishes the standalone, reusable, read-only library boundary
adds MIT licensing, upstream attribution, and a porting inventory that does not falsely claim translated code
pins Nixpkgs and commits flake.lock
adds ASDF systems, public packages, stable typed condition categories, and offline unit smoke checks
freezes libcldiscordcurl ABI version 1 with opaque handles and fixed-width public fields/results
adds struct_size versioning to every public ABI struct before implementation begins
defines explicit ownership, poll, cancellation, terminal-event, shutdown-timeout, and destruction preconditions
defines compatibility-manifest, dispatch-event, replay-record, and fixture-set schemas
establishes unit, replay, compatibility, integration, native, and fixture test boundaries
adds pull-request and main GitHub Actions CI using the deterministic Nix check set
tracks release publication separately in #13, blocked on Profile A (#8)

Architecture boundaries touched

native transport ABI only; no native implementation
protocol-neutral Common Lisp contracts only
CI validation only; no deployment or release credentials
no RabbitMQ, CouchDB, StarIntel document, dataset, target-policy, or LEO-specific authorization dependency
no live Discord transport, send API, interaction automation, command framework, or mass-account behavior

Validation executed

strict C11 native-header smoke — PASS
strict C++17 native-header smoke — PASS
ABI layout assertions for leading struct_size and fixed-width event type — PASS
Python JSON parsing for all four schemas/*.schema.json documents — PASS
nix flake check -L on x86_64-linux — PASS locally
ASDF compile/load and asdf:test-system "cl-discord-self" through Nix — PASS locally
GitHub Actions CI run #5 on head 7731cfe5ea095e9471fe512692a99444a783e1fd — PASS

Nix omitted aarch64-linux builds on the x86_64-linux host, as expected. Cross-system evaluation is not claimed.

CI contract

triggers on pull requests, pushes to main, and manual dispatch
workflow token has contents: read only
checkout credentials are not persisted
superseded runs are cancelled
job timeout is 30 minutes
nix flake check -L --no-update-lock-file is the sole build/test entrypoint
CI fails if flake.lock changes
no live Discord account, token, or external Discord endpoint is used

Pinned/generated inputs

Nixpkgs: 148bab9c1c3c53136ecb44a6ea356a0ed5b39b06
lockfile revision: 148bab9c1c3c53136ecb44a6ea356a0ed5b39b06
discord.py-self compatibility commit: intentionally not invented here; Issue #2 selects and records it
generated models: none in this revision
translated upstream implementation modules: none in this revision

Remaining review gate

independent approval of ABI ownership, struct versioning, queue reservation, cancellation races, poll-buffer lifetime, and shutdown semantics

The implementation pass is complete and CI is active. Merge remains blocked on that independent review gate.

Closes #1 ## Implemented - establishes the standalone, reusable, read-only library boundary - adds MIT licensing, upstream attribution, and a porting inventory that does not falsely claim translated code - pins Nixpkgs and commits `flake.lock` - adds ASDF systems, public packages, stable typed condition categories, and offline unit smoke checks - freezes `libcldiscordcurl` ABI version 1 with opaque handles and fixed-width public fields/results - adds `struct_size` versioning to every public ABI struct before implementation begins - defines explicit ownership, poll, cancellation, terminal-event, shutdown-timeout, and destruction preconditions - defines compatibility-manifest, dispatch-event, replay-record, and fixture-set schemas - establishes unit, replay, compatibility, integration, native, and fixture test boundaries - adds pull-request and `main` GitHub Actions CI using the deterministic Nix check set - tracks release publication separately in #13, blocked on Profile A (#8) ## Architecture boundaries touched - native transport ABI only; no native implementation - protocol-neutral Common Lisp contracts only - CI validation only; no deployment or release credentials - no RabbitMQ, CouchDB, StarIntel document, dataset, target-policy, or LEO-specific authorization dependency - no live Discord transport, send API, interaction automation, command framework, or mass-account behavior ## Validation executed - strict C11 native-header smoke — PASS - strict C++17 native-header smoke — PASS - ABI layout assertions for leading `struct_size` and fixed-width event type — PASS - Python JSON parsing for all four `schemas/*.schema.json` documents — PASS - `nix flake check -L` on x86_64-linux — PASS locally - ASDF compile/load and `asdf:test-system "cl-discord-self"` through Nix — PASS locally - GitHub Actions CI run #5 on head `7731cfe5ea095e9471fe512692a99444a783e1fd` — PASS Nix omitted `aarch64-linux` builds on the x86_64-linux host, as expected. Cross-system evaluation is not claimed. ## CI contract - triggers on pull requests, pushes to `main`, and manual dispatch - workflow token has `contents: read` only - checkout credentials are not persisted - superseded runs are cancelled - job timeout is 30 minutes - `nix flake check -L --no-update-lock-file` is the sole build/test entrypoint - CI fails if `flake.lock` changes - no live Discord account, token, or external Discord endpoint is used ## Pinned/generated inputs - Nixpkgs: `148bab9c1c3c53136ecb44a6ea356a0ed5b39b06` - lockfile revision: `148bab9c1c3c53136ecb44a6ea356a0ed5b39b06` - `discord.py-self` compatibility commit: intentionally not invented here; Issue #2 selects and records it - generated models: none in this revision - translated upstream implementation modules: none in this revision ## Remaining review gate - independent approval of ABI ownership, struct versioning, queue reservation, cancellation races, poll-buffer lifetime, and shutdown semantics The implementation pass is complete and CI is active. Merge remains blocked on that independent review gate.

lost-rob0t commented

2026-08-03 08:07:17 +00:00

(Migrated from github.com)

The first real nix flake check run failed in asdf-smoke. Root cause was the SBCL-unsafe string DEFCONSTANT in src/core.lisp; SBCL rejects the non-EQL string value when ASDF compiles and loads the file.

Fix pushed in d8443a0a56bf5fa8fa6336437441b68687176450 by changing the public version string to a documented DEFPARAMETER.

Status remains unverified until nix flake check -L is rerun on the updated branch.

The first real `nix flake check` run failed in `asdf-smoke`. Root cause was the SBCL-unsafe string `DEFCONSTANT` in `src/core.lisp`; SBCL rejects the non-`EQL` string value when ASDF compiles and loads the file. Fix pushed in `d8443a0a56bf5fa8fa6336437441b68687176450` by changing the public version string to a documented `DEFPARAMETER`. Status remains **unverified** until `nix flake check -L` is rerun on the updated branch.

lost-rob0t commented

2026-08-03 08:09:28 +00:00

(Migrated from github.com)

Local validation update from the repository owner:

git pull --ff-only advanced the branch to d8443a0a56bf5fa8fa6336437441b68687176450.
nix flake check -L completed successfully on x86_64-linux.
The ASDF smoke check compiled and loaded src/packages.lisp, src/conditions.lisp, src/core.lisp, and tests/unit/smoke.lisp without error.
Nix emitted only the expected warning that aarch64-linux checks were omitted on the current host; use --all-systems for cross-system evaluation.
The worktree was reported dirty during the check, so git status --short should be reviewed before the branch is considered clean. This is likely the newly generated flake.lock and must not be silently ignored.

The original SBCL string DEFCONSTANT blocker is resolved. Remaining gate: review/commit the lockfile if present, then independent ABI review before merge.

Local validation update from the repository owner: - `git pull --ff-only` advanced the branch to `d8443a0a56bf5fa8fa6336437441b68687176450`. - `nix flake check -L` completed successfully on x86_64-linux. - The ASDF smoke check compiled and loaded `src/packages.lisp`, `src/conditions.lisp`, `src/core.lisp`, and `tests/unit/smoke.lisp` without error. - Nix emitted only the expected warning that `aarch64-linux` checks were omitted on the current host; use `--all-systems` for cross-system evaluation. - The worktree was reported dirty during the check, so `git status --short` should be reviewed before the branch is considered clean. This is likely the newly generated `flake.lock` and must not be silently ignored. The original SBCL string `DEFCONSTANT` blocker is resolved. Remaining gate: review/commit the lockfile if present, then independent ABI review before merge.

lost-rob0t commented

2026-08-03 08:23:02 +00:00

(Migrated from github.com)

Implementation audit before review:

added leading struct_size fields and v1 size constants so public structs can grow without silently breaking older FFI callers;
replaced ABI-visible enum/function result widths with fixed-width integers;
defined process-lifetime ownership for version strings;
defined create failure output behavior and accepted-operation ID rules;
defined cancellation races as exactly one authoritative terminal event;
defined poll return/output semantics and immutable event-buffer lifetime;
required reserved queue capacity for terminal events and RUNTIME_STOPPED;
defined shutdown timeout continuation and strict destroy preconditions;
expanded native smoke checks to strict C11 and C++17 layout validation;
CI run #5 passed on head 7731cfe5ea095e9471fe512692a99444a783e1fd.

This self-audit does not satisfy the repository's independent-review gate. The PR is being moved out of draft so an independent reviewer can specifically challenge those contracts before merge.

Implementation audit before review: - added leading `struct_size` fields and v1 size constants so public structs can grow without silently breaking older FFI callers; - replaced ABI-visible enum/function result widths with fixed-width integers; - defined process-lifetime ownership for version strings; - defined create failure output behavior and accepted-operation ID rules; - defined cancellation races as exactly one authoritative terminal event; - defined poll return/output semantics and immutable event-buffer lifetime; - required reserved queue capacity for terminal events and `RUNTIME_STOPPED`; - defined shutdown timeout continuation and strict destroy preconditions; - expanded native smoke checks to strict C11 and C++17 layout validation; - CI run #5 passed on head `7731cfe5ea095e9471fe512692a99444a783e1fd`. This self-audit does not satisfy the repository's independent-review gate. The PR is being moved out of draft so an independent reviewer can specifically challenge those contracts before merge.

lost-rob0t (Migrated from github.com) reviewed

2026-08-03 09:20:53 +00:00

lost-rob0t (Migrated from github.com) left a comment

Repository owner explicitly authorized merge after CI passed. No separate GitHub approval review was submitted. Proceeding under that owner override; the ABI contract remains subject to follow-up implementation review as native code is added.