Implement C transport library and Common Lisp client bridge #3

New issue

Open

opened 2026-08-03 07:47:06 +00:00 by lost-rob0t · 1 comment

lost-rob0t commented

2026-08-03 07:47:06 +00:00

(Migrated from github.com)

Depends on

#1
merged replay-backed client core from PR #15

Issue #2 is not a prerequisite for fixture-only C transport work. Compatibility manifests and upstream-oracle selection must not block this implementation.

Goal

Implement libcldiscordcurl behind the committed ABI and connect it to the existing Common Lisp client transport protocol, producing a runnable Common Lisp client that uses the C transport library against local fixture servers without contacting Discord.

Required first vertical slice

build a real shared libcldiscordcurl C library under Nix
implement ABI/native-version reporting
implement runtime create, bounded event queue, poll, shutdown, and destroy
copy accepted input buffers before returning from submission calls
perform one bounded HTTP GET against a loopback fixture server
emit headers/body/terminal events through the polling ABI
add a Common Lisp adapter for the C transport library that implements the existing transport-* generic functions
drive the existing client lifecycle through the C transport adapter in an integration test
document one runnable fixture-backed client example

Follow-on scope in this issue

opaque request and socket identifiers
bounded command queue and worker execution
cancellation with exactly one terminal event
WebSocket open, fragmented receive, send, close, and cancellation against a loopback fixture server
stable immediate and asynchronous error categories
credential-safe error and debug strings
clean shutdown under concurrent load

Constraints

do not connect to Discord or require an account token
do not work on compatibility manifests unless implementation needs a tiny named local fixture profile
no raw CURL*, socket descriptor, callback pointer, or native allocation address crosses the public boundary
no C worker thread calls arbitrary Lisp code
each returned event has exactly one documented owner and release path
queue saturation returns structured overload and never silently drops terminal events
unknown transport profiles fail closed
all network operations are loopback-only in default tests and CI

Exit gate

Common Lisp starts the client through the C transport library, receives deterministic fixture events, and shuts down cleanly
fragmented HTTP and WebSocket payloads reconstruct exactly
cancellation and shutdown produce exactly one terminal event per accepted operation
ABI mismatch fails before network activity
repeated fixture connections complete without leaked handles
C, Lisp integration, ASDF, and Nix checks pass
the PR merges immediately when green under AGENTS.md

## Depends on - #1 - merged replay-backed client core from PR #15 Issue #2 is not a prerequisite for fixture-only C transport work. Compatibility manifests and upstream-oracle selection must not block this implementation. ## Goal Implement `libcldiscordcurl` behind the committed ABI and connect it to the existing Common Lisp client transport protocol, producing a runnable Common Lisp client that uses the C transport library against local fixture servers without contacting Discord. ## Required first vertical slice - build a real shared `libcldiscordcurl` C library under Nix - implement ABI/native-version reporting - implement runtime create, bounded event queue, poll, shutdown, and destroy - copy accepted input buffers before returning from submission calls - perform one bounded HTTP GET against a loopback fixture server - emit headers/body/terminal events through the polling ABI - add a Common Lisp adapter for the C transport library that implements the existing `transport-*` generic functions - drive the existing client lifecycle through the C transport adapter in an integration test - document one runnable fixture-backed client example ## Follow-on scope in this issue - opaque request and socket identifiers - bounded command queue and worker execution - cancellation with exactly one terminal event - WebSocket open, fragmented receive, send, close, and cancellation against a loopback fixture server - stable immediate and asynchronous error categories - credential-safe error and debug strings - clean shutdown under concurrent load ## Constraints - do not connect to Discord or require an account token - do not work on compatibility manifests unless implementation needs a tiny named local fixture profile - no raw `CURL*`, socket descriptor, callback pointer, or native allocation address crosses the public boundary - no C worker thread calls arbitrary Lisp code - each returned event has exactly one documented owner and release path - queue saturation returns structured overload and never silently drops terminal events - unknown transport profiles fail closed - all network operations are loopback-only in default tests and CI ## Exit gate - Common Lisp starts the client through the C transport library, receives deterministic fixture events, and shuts down cleanly - fragmented HTTP and WebSocket payloads reconstruct exactly - cancellation and shutdown produce exactly one terminal event per accepted operation - ABI mismatch fails before network activity - repeated fixture connections complete without leaked handles - C, Lisp integration, ASDF, and Nix checks pass - the PR merges immediately when green under `AGENTS.md`

lost-rob0t commented

2026-08-03 09:47:07 +00:00

(Migrated from github.com)

Next-layer execution prompt

You are implementing Issue #3 in lost-rob0t/cl-discord-self.

Read the repository-root AGENTS.md completely before changing anything. Treat its merge-on-green policy as mandatory. Read Issue #3 and the merged client-core implementation from PR #15. Do not work on compatibility manifests, upstream-oracle selection, StarIntel adapters, or live Discord connectivity in this pass.

Objective

Deliver the first runnable Common Lisp client path that uses the C transport library against loopback fixture servers.

Branch

Create or use codex/issue-3-c-transport-a1 from the current main. Do not stack on another unmerged branch.

Required implementation

Build a real shared libcldiscordcurl C library under Nix using the committed public header.
Implement cdc_abi_version, runtime/C-library version reporting, cdc_runtime_create, cdc_poll, bounded shutdown, and destroy.
Implement a bounded event queue with explicit ownership. cdc_poll returns one C-allocated event transferred to the caller; cdc_event_free releases it exactly once.
Implement one bounded HTTP GET operation against a loopback fixture server. Copy all accepted request buffers before returning from cdc_http_submit.
Emit deterministic HTTP headers, body fragments, and exactly one terminal event through the polling ABI.
Reject ABI mismatch and unknown transport profiles before network activity.
Add a Common Lisp adapter for the C transport library implementing the existing transport-open, transport-receive, transport-send, transport-close, and transport-open-p protocol where applicable. Do not expose C pointers through the public Lisp API.
Drive the existing make-client / start-client / run-client / poll-event / stop-client lifecycle through the C transport adapter in an integration test.
Add a local fixture server and tests that require no token, cookie, Discord account, or external network.
Document one runnable fixture-backed client example.

Engineering constraints

Use libcurl through the C transport library only.
No C worker thread may invoke arbitrary Lisp callbacks.
No raw CURL*, socket descriptor, callback pointer, or allocation address crosses the ABI.
Queue capacity and response size are bounded.
Terminal events are never silently dropped.
Diagnostics must not contain authorization headers, cookies, message bodies, proxy passwords, or pointer values.
All CI network activity must be loopback-only.
Do not add placeholders or success stubs. A partial slice must execute end-to-end.

Validation

Run and record:

strict C11 and C++ header checks
C unit tests
fixture HTTP integration tests
ASDF compile/load and Lisp tests
Common Lisp client integration test through the C transport library
nix flake check -L --no-update-lock-file
lockfile drift check

Review the complete diff for ownership leaks, unbounded queues, secret exposure, hidden C handles, unrelated work, and accidental live-network access.

PR and merge

Open a non-draft PR linked to Issue #3 once the vertical slice is complete. Include exact commands and results, skipped checks, ownership rules, and remaining WebSocket follow-up. Watch the exact current head SHA. When CI is green, GitHub reports the PR mergeable, and there is no unresolved blocking thread or explicit blocker, merge immediately. Repository auto-merge is disabled, so perform a direct merge using the verified head SHA. Then continue from updated main.

## Next-layer execution prompt You are implementing Issue #3 in `lost-rob0t/cl-discord-self`. Read the repository-root `AGENTS.md` completely before changing anything. Treat its merge-on-green policy as mandatory. Read Issue #3 and the merged client-core implementation from PR #15. Do not work on compatibility manifests, upstream-oracle selection, StarIntel adapters, or live Discord connectivity in this pass. ### Objective Deliver the first runnable Common Lisp client path that uses the C transport library against loopback fixture servers. ### Branch Create or use `codex/issue-3-c-transport-a1` from the current `main`. Do not stack on another unmerged branch. ### Required implementation 1. Build a real shared `libcldiscordcurl` C library under Nix using the committed public header. 2. Implement `cdc_abi_version`, runtime/C-library version reporting, `cdc_runtime_create`, `cdc_poll`, bounded shutdown, and destroy. 3. Implement a bounded event queue with explicit ownership. `cdc_poll` returns one C-allocated event transferred to the caller; `cdc_event_free` releases it exactly once. 4. Implement one bounded HTTP GET operation against a loopback fixture server. Copy all accepted request buffers before returning from `cdc_http_submit`. 5. Emit deterministic HTTP headers, body fragments, and exactly one terminal event through the polling ABI. 6. Reject ABI mismatch and unknown transport profiles before network activity. 7. Add a Common Lisp adapter for the C transport library implementing the existing `transport-open`, `transport-receive`, `transport-send`, `transport-close`, and `transport-open-p` protocol where applicable. Do not expose C pointers through the public Lisp API. 8. Drive the existing `make-client` / `start-client` / `run-client` / `poll-event` / `stop-client` lifecycle through the C transport adapter in an integration test. 9. Add a local fixture server and tests that require no token, cookie, Discord account, or external network. 10. Document one runnable fixture-backed client example. ### Engineering constraints - Use libcurl through the C transport library only. - No C worker thread may invoke arbitrary Lisp callbacks. - No raw `CURL*`, socket descriptor, callback pointer, or allocation address crosses the ABI. - Queue capacity and response size are bounded. - Terminal events are never silently dropped. - Diagnostics must not contain authorization headers, cookies, message bodies, proxy passwords, or pointer values. - All CI network activity must be loopback-only. - Do not add placeholders or success stubs. A partial slice must execute end-to-end. ### Validation Run and record: - strict C11 and C++ header checks - C unit tests - fixture HTTP integration tests - ASDF compile/load and Lisp tests - Common Lisp client integration test through the C transport library - `nix flake check -L --no-update-lock-file` - lockfile drift check Review the complete diff for ownership leaks, unbounded queues, secret exposure, hidden C handles, unrelated work, and accidental live-network access. ### PR and merge Open a non-draft PR linked to Issue #3 once the vertical slice is complete. Include exact commands and results, skipped checks, ownership rules, and remaining WebSocket follow-up. Watch the exact current head SHA. When CI is green, GitHub reports the PR mergeable, and there is no unresolved blocking thread or explicit blocker, merge immediately. Repository auto-merge is disabled, so perform a direct merge using the verified head SHA. Then continue from updated `main`.