phase 0 setup: agent defs cleaned, AGENTS.md, initial phase-0.md draft
- sdd_process.md + coordinator.md: stale @alkdev/alkblobs name from the copy fixed to @alkdev/alkstore - implementation-specialist.md: copied alkcall-family conventions (OperationEnv, vendored core types, BAST/wire formats) replaced with crate-neutral rules + an ADR-escalation rule - code-reviewer.md: stale tls/iroh/acme feature list removed; anyhow posture corrected; db-specific review checks added - AGENTS.md: phase-0 posture (no crate yet, no README, POC/discipline conventions, OQ-ST-NN register, reference checkouts) - docs/research/phase-0.md: initial draft — vision, prior art (honker, pgboss-rs read incl. verified pgboss-rs LISTEN/NOTIFY absence), open questions OQ-ST-01..08, phase 0 plan
This commit is contained in:
1 parent
5bcd1b7a2f
commit
f6531b5532
6 files changed
+504
-56
No files matched your search
@@ -111,13 +111,15 @@ cargo fmt --check # Format check
|
||||
For this project, also verify:
|
||||
|
||||
- No comments in code (per project convention)
|
||||
- Error handling uses `anyhow::Result` (application) / `thiserror` (library) — no
|
||||
- Error handling uses `thiserror` (library crate) — no
|
||||
panics in library code
|
||||
- Feature flags are used correctly (`tls`, `iroh`, `acme`) — base crate compiles
|
||||
lean
|
||||
- Feature flags are used correctly — base crate compiles lean
|
||||
- Public API is well-documented with `///` doc comments where appropriate
|
||||
- Module structure follows Rust conventions (`mod.rs`, `lib.rs`)
|
||||
- No unnecessary `unwrap()` or `expect()` in library code
|
||||
- For database code: SQL injection safety (parameterized queries only, no
|
||||
string-built SQL), connection/pool handling under cancellation (no
|
||||
panics poisoning a shared pool), and migration/DDL ordering
|
||||
|
||||
#### E. Security
|
||||
|
||||
|
||||
@@ -191,7 +191,7 @@ also include:
|
||||
Example prompt template:
|
||||
|
||||
```
|
||||
You are an implementation specialist for the @alkdev/alkblobs project.
|
||||
You are an implementation specialist for the @alkdev/alkstore project.
|
||||
|
||||
Your task: {{task}}
|
||||
|
||||
@@ -204,7 +204,7 @@ Your task: {{task}}
|
||||
7. Push: git push origin $(git branch --show-current)
|
||||
8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
|
||||
|
||||
Key project constraints (@alkdev/alkblobs):
|
||||
Key project constraints (@alkdev/alkstore):
|
||||
- Rust: use cargo build, cargo clippy, cargo fmt, cargo test
|
||||
- No comments in code
|
||||
- thiserror for error types
|
||||
|
||||
@@ -207,7 +207,9 @@ This is especially important for complex tasks that span many file operations.
|
||||
|
||||
## Project Conventions
|
||||
|
||||
Read `AGENTS.md` at project root for full details. Key rules:
|
||||
Read `AGENTS.md` at project root for full details. Key rules (the
|
||||
cross-crate, stable ones — crate-specific conventions live in `AGENTS.md`
|
||||
and evolve with the project):
|
||||
|
||||
1. **No comments in code** — Per project convention. Doc comments (`///`, `//!`)
|
||||
are fine and expected on public API.
|
||||
@@ -217,55 +219,19 @@ Read `AGENTS.md` at project root for full details. Key rules:
|
||||
operation does not cascade to other operations.
|
||||
3. **`tokio` is the async runtime** — all I/O is async. Use `tokio::sync`
|
||||
primitives (`oneshot`, `mpsc`) for request correlation and subscription
|
||||
channels; `parking_lot` for short-held internal locks (`PendingRequestMap`).
|
||||
4. **No secret material on the wire** — `call.requested`/`call.responded`
|
||||
payloads and `OperationContext.metadata` carry no private keys, API keys, or
|
||||
decrypted credentials. Outbound credentials flow through `Capabilities`
|
||||
injected at the assembly layer → `HandlerRegistration.capabilities` →
|
||||
`OperationContext.capabilities` → handler.
|
||||
5. **No-env-vars invariant** — no handler reads outbound credentials from any
|
||||
source other than `OperationContext.capabilities`. This is a spec-level
|
||||
invariant, not a runtime convention.
|
||||
6. **`OperationEnv` must remain a trait** — the trait-based design enables
|
||||
registry layering (session overlays, connection overlays, peer-keyed
|
||||
composition). Do not make it concrete or hardcode the global registry.
|
||||
7. **Wire formats are stable** — `EventEnvelope` (`{ type, id, payload }` +
|
||||
length-prefixed JSON framing) and the channels 8-byte chunk header
|
||||
(`[channel_id:u32 BE][length:u32 BE][payload]`) are one-way doors. New event
|
||||
types may be added; existing shapes must not change.
|
||||
8. **Producer/consumer, not server/client** — both sides of a call or channels
|
||||
connection can initiate. Use "producer"/"consumer" or "accept side"/"connect
|
||||
side," not "server"/"client."
|
||||
9. **Vendored core types** — `Connection`, `ProtocolHandler`, `BiStream`,
|
||||
`BidiStreamSource`, `AuthContext`, `IdentityProvider`, `Identity`,
|
||||
`AuthToken`, `Capabilities`, `OwnershipProvider`, `HandlerError`,
|
||||
`StreamError` live in this crate. Do not add a separate `alkcore` dependency.
|
||||
Keep them lean (no TLS, no transport coupling, no endpoint/accept-loop).
|
||||
10. **BAST documents for wire formats** — every binary wire format carries a
|
||||
BAST (Binary Abstract Syntax Tree) document as its machine-readable spec
|
||||
(e.g. the channels chunk header's `docs/architecture/chunk-header.bast.json`,
|
||||
embedded as `CHUNK_HEADER_BAST`). BAST is plain JSON — no dependency
|
||||
required to author or consume it. The `alktype` crate compiles BAST into
|
||||
readers/writers/validators; future codegen derives language-specific
|
||||
implementations. Trivial or hot-path formats (chunk header, tty framing)
|
||||
stay hand-rolled with the BAST doc as the contract; complex formats (sftp)
|
||||
use the alktype engine or codegen. Do not roll your own offset map or
|
||||
validator for complex formats.
|
||||
11. **Feature flags** — transports may be feature-gated if the need arises. The
|
||||
base crate should compile lean (no `quinn`, no `iroh` unless the feature is
|
||||
on). Verify both `cargo test` (default) and `cargo test --all-features` pass
|
||||
if features are added.
|
||||
12. **Abort cascades to descendants** — `call.aborted` for a parent cascades to
|
||||
all non-terminal descendants. Default `abort-dependents`;
|
||||
`continue-running` opt-in. The composing handler decides the child's policy,
|
||||
not the wire caller.
|
||||
13. **Peer authorization via `AccessControl`** — a remote peer's call is
|
||||
authorized by `AccessControl::check(peer_identity)`. No `remote_safe` flag,
|
||||
no `trusted_peer` bypass. `Visibility::Internal` ops are never wire-callable.
|
||||
14. **Naming conventions** — Rust standard: `snake_case` for functions/variables/
|
||||
modules, `PascalCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
|
||||
15. **Module structure** — one module per file under `src/`, re-exported from
|
||||
`src/lib.rs`. Public API surface is `lib.rs` re-exports.
|
||||
channels; `parking_lot` for short-held internal locks.
|
||||
4. **Naming conventions** — Rust standard: `snake_case` for functions/variables/
|
||||
modules, `PascalCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
|
||||
5. **Module structure** — one module per file under `src/`, re-exported from
|
||||
`src/lib.rs`. Public API surface is `lib.rs` re-exports.
|
||||
6. **Feature flags** — optional dependencies (e.g. the postgres engine) may be
|
||||
feature-gated if the need arises. The base crate should compile lean.
|
||||
Verify both `cargo test` (default) and `cargo test --all-features` pass
|
||||
if features are added.
|
||||
7. **Decisions land in ADRs** — if you discover a decision the architecture
|
||||
didn't make (an undocumented trade-off, an interface shape you must
|
||||
choose), do not decide it silently: notify the coordinator (`level:
|
||||
"blocking"` if it changes the API surface) so an ADR gets written.
|
||||
|
||||
## Key Principles
|
||||
|
||||
|
||||
Reference in new issue
Block a user