Core domain invariants for TaskStream authority

[devkade]

Summary

Implement the first domain model and invariant tests for the #236 TaskStream kernel.

Parent: #236

Scope

Implement core domain objects:

TaskStream
Run
RuntimeSession
TaskStreamContract
RunContract
EvidenceRecord
VerificationResult
CompletionDecision
ArtifactRef
EventEnvelope

Implement domain errors and value objects:

StreamId
RunId
RuntimeSessionId
EvidenceId
VerificationId
CompletionDecisionId
ArtifactId
ContractVersion
DecisionAuthority

Required invariants

• Runtime output cannot complete a Run.
• CompletionDecision requires kernel authority.
• CompletionDecision requires non-empty evidence refs.
• CompletionDecision requires accepted/passing verification.
• Run uses an immutable contract snapshot.
• ArtifactRef requires stable path/URI plus digest.
• EventEnvelope carries bounded accountability facts, not raw transcripts by default.

Non-goals

• No SQLite.
• No MCP.
• No Pi adapter.
• No CLI.
• No GitHub/Discord semantics.

Acceptance criteria

• Domain invariant tests exist.
• Domain errors are explicit and typed.
• Core has no adapter dependencies.
• cargo test -p ilchul-core passes.

[devkade]

AI-understood issue summary

Issue #239 asks for the first Rust core-domain slice under parent #236: define the TaskStream authority model and invariant tests in ilchul-core. The important boundary is that runtime output is only observation/evidence input; completion must be a kernel-owned CompletionDecision backed by non-empty evidence refs and accepted/passing verification.

Why this issue is needed

• Parent SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 resets the project toward a Rust-first TaskStream kernel, but the current repo is still TypeScript-first: package.json:24 through package.json:34 define npm-based validation, and there is no root Rust workspace/Cargo package visible in the current checkout.
• Existing domain code already distinguishes lifecycle/evidence/quality, but it is a projection over WorkflowState, not a durable Rust authority model: src/domain/run-contract.ts:49, src/domain/run-contract.ts:69, src/domain/run-contract.ts:70, and src/domain/run-contract.ts:73 show the current RunContract view shape.
• Existing docs explicitly say readiness/output cannot become completion authority: docs/learning-runtime-boundaries.md:80, docs/learning-runtime-boundaries.md:102, docs/learning-runtime-boundaries.md:106, and docs/learning-runtime-boundaries.md:116 support this issue’s “runtime output cannot complete a Run” invariant.
• The issue gives the implementation agent a narrow first domain slice before SQLite/MCP/Pi/CLI concerns are introduced, which should reduce the risk of adapter semantics leaking into the authority model.

Why this issue may not be needed

• If the project were staying in the current TypeScript workflow harness, the current model already has evidence records, artifact refs, lifecycle validation, RunContract projections, and tests around them (src/domain/types.ts:49, src/domain/types.ts:74, src/domain/workflow-validation.ts:5, test/evidence-artifact-ref-validation.test.ts:6).
• If Rust workspace scaffold + DDD core skeleton #238 has not yet landed the Rust workspace, Core domain invariants for TaskStream authority #239 may need to wait or include only the ilchul-core crate subset from that scaffold; otherwise the implementation agent may spend time on workspace structure instead of invariants.
• The existing TS code is useful as design evidence, but it should not be treated as the implementation target for this issue because acceptance requires cargo test -p ilchul-core.

Expected Outcome

After /approve, the implementation agent will leave a minimal Rust core crate with:

• Domain objects: TaskStream, Run, RuntimeSession, TaskStreamContract, RunContract, EvidenceRecord, VerificationResult, CompletionDecision, ArtifactRef, and EventEnvelope.
• Explicit typed domain errors and value objects: StreamId, RunId, RuntimeSessionId, EvidenceId, VerificationId, CompletionDecisionId, ArtifactId, ContractVersion, and DecisionAuthority.
• Invariant tests proving runtime output cannot complete a run; completion decisions require kernel authority, evidence refs, and accepted/passing verification; run contracts are immutable snapshots; artifact refs require stable path/URI plus digest; and event envelopes carry bounded accountability facts rather than raw transcripts by default.
• No SQLite, MCP, Pi adapter, CLI, GitHub, or Discord semantics in core.
• cargo test -p ilchul-core passing.

Evidence-based implementation plan

Feasibility grounded in research

In-repo reusable code/patterns:

• RunContractView already captures goal/lifecycle/constraints/artifacts/evidence/expectations/completion/quality as a projection (src/domain/run-contract.ts:49, src/domain/run-contract.ts:58, src/domain/run-contract.ts:65, src/domain/run-contract.ts:69, src/domain/run-contract.ts:70, src/domain/run-contract.ts:71, src/domain/run-contract.ts:73). The implementation agent should reuse the vocabulary, not the TS implementation.
• Current projection code clones artifacts and evidence when projecting a contract (src/domain/run-contract.ts:110, src/domain/run-contract.ts:111, src/domain/run-contract.ts:233, src/domain/run-contract.ts:236, src/domain/run-contract.ts:237, src/domain/run-contract.ts:238). This is evidence for the immutable snapshot requirement: the Rust Run should own an immutable RunContract snapshot rather than borrowing a mutable stream contract.
• Existing ArtifactRef is too weak for Core domain invariants for TaskStream authority #239 because it has only name/path/required (src/domain/types.ts:49, src/domain/types.ts:50, src/domain/types.ts:51, src/domain/types.ts:52). The implementation agent should strengthen the Rust version with stable path/URI plus digest.
• Existing ValidationEvidence already has fields that map well to normalized EvidenceRecord: command, exit code, artifact refs, changed files, acceptance criteria, actor, authority, and snapshot hash (src/domain/types.ts:74, src/domain/types.ts:79, src/domain/types.ts:80, src/domain/types.ts:84, src/domain/types.ts:85, src/domain/types.ts:86, src/domain/types.ts:90, src/domain/types.ts:91, src/domain/types.ts:92).
• Existing state-machine logic treats only review evidence with approval/pass verdicts as resolving pending decisions (src/domain/state-machine.ts:265, src/domain/state-machine.ts:269, src/domain/state-machine.ts:270). This is directly relevant to modeling CompletionDecision as authority plus verification/evidence, not runtime text.
• Existing validation code already distinguishes approval/pass and requires fresh command evidence for Ralph closeout (src/domain/workflow-validation.ts:86, src/domain/workflow-validation.ts:102, src/domain/workflow-validation.ts:130, src/domain/workflow-validation.ts:136, src/domain/workflow-validation.ts:138, src/domain/workflow-validation.ts:153, src/domain/workflow-validation.ts:157, src/domain/workflow-validation.ts:160, src/domain/workflow-validation.ts:161). This can guide the negative invariant tests.
• Existing architecture tests enforce that the domain layer avoids Pi, filesystem, tmux, git command, and process-adapter dependencies (test/architecture.test.ts:84, test/architecture.test.ts:85, test/architecture.test.ts:86, test/architecture.test.ts:87, test/architecture.test.ts:88, test/architecture.test.ts:89). The implementation agent should add an analogous Rust boundary check only if it is cheap; at minimum keep ilchul-core dependency-light.
• Existing event-boundary documentation says event logs should be semantic, append-only, replayable runtime/accountability records (docs/learning-runtime-boundaries.md:121, docs/learning-runtime-boundaries.md:123, docs/learning-runtime-boundaries.md:126, docs/learning-runtime-boundaries.md:127, docs/learning-runtime-boundaries.md:128). This supports EventEnvelope carrying bounded facts and artifact refs, not raw transcripts.

External references / libraries:

• thiserror is suitable for explicit typed domain errors: Error in thiserror - Rust - https://docs.rs/thiserror/latest/thiserror/derive.Error.html.
• serde is suitable for serializable value/domain structs if projections or test fixtures need JSON: Using derive · Serde - https://serde.rs/derive.html.
• uuid can back typed IDs if the project wants UUID-based IDs rather than string newtypes: uuid - Rust - https://docs.rs/uuid/latest/uuid/.
• newtype_uuid is a possible typed-UUID helper, but simple local newtypes may be clearer for core invariants: newtype_uuid - Rust - https://docs.rs/newtype-uuid.
• camino can represent stable UTF-8 paths if core needs path-like values without OS-string leakage: camino - Rust - https://docs.rs/camino/latest/camino/.
• sha2 or blake3 can support digest creation/validation in later artifact code, but Core domain invariants for TaskStream authority #239 can model digests as validated strings without computing them in core: sha2 - Rust - https://docs.rs/sha2/latest/sha2/ and blake3 - Rust - https://docs.rs/blake3/.
• No turnkey external TaskStream-authority domain library was found; the right approach is a small local model with optional support crates for errors/serialization/IDs.

Concrete step-by-step plan for the implementation agent

1. Confirm/scaffold only the minimal core crate needed for this issue. If Rust workspace scaffold + DDD core skeleton #238 already created the workspace, work inside core / ilchul-core. If not, create only the minimum workspace/core package necessary for cargo test -p ilchul-core; do not add store/MCP/Pi/CLI crates in this issue.
2. Add domain modules inside ilchul-core. Suggested split: ids, errors, artifact, contract, evidence, verification, completion, event, and stream/run. Keep all APIs adapter-neutral.
3. Implement value objects as validated constructors. StreamId, RunId, RuntimeSessionId, EvidenceId, VerificationId, CompletionDecisionId, ArtifactId, and ContractVersion should not expose unchecked empty values. Use local newtypes by default; consider uuid only if the project already chose UUIDs in Rust workspace scaffold + DDD core skeleton #238.
4. Implement explicit typed errors. Use a DomainError enum with cases such as empty id, invalid contract version, missing artifact locator, missing digest, runtime completion attempt, non-kernel authority, missing evidence refs, and unacceptable verification. thiserror is appropriate if adding one dependency is acceptable (Error in thiserror - Rust - https://docs.rs/thiserror/latest/thiserror/derive.Error.html).
5. Model authority distinctly from runtime observations. Add DecisionAuthority with a kernel/Ilchul authority variant and non-authoritative runtime/adapter/human observation variants as needed. CompletionDecision::new(...) should accept only kernel authority and reject any runtime/session authority.
6. Make Run own an immutable contract snapshot. Mirror the current TS projection’s copy behavior (src/domain/run-contract.ts:110, src/domain/run-contract.ts:111, src/domain/run-contract.ts:233). In Rust, prefer owned RunContract fields and no mutating setters that can alter the run’s contract after construction.
7. Separate runtime output from evidence and verification. RuntimeSession may record observed output summaries/events, but it should have no method that marks Run complete. Only a core function like CompletionDecision::decide_completed(...) or Run::complete_with_decision(...) should produce completion, and it must require accepted evidence refs plus a passing/accepted VerificationResult.
8. Define ArtifactRef with stable locator plus digest. Replace the current weak TS shape (src/domain/types.ts:49) with Rust fields like id, locator (Path or Uri enum), digest, and optional summary/media kind. Constructors should reject empty locators and empty digest strings. Core should not read files or calculate hashes in this issue.
9. Define EventEnvelope as bounded accountability facts. Include event id/type, stream/run/session ids as appropriate, timestamp/source/actor/authority, compact summary/facts, artifact refs, and related evidence/verification/decision ids. Do not include raw transcript/stdout fields by default. Use the event model docs as boundary evidence (docs/learning-runtime-boundaries.md:121, docs/learning-runtime-boundaries.md:123).
10. Write invariant-first tests. Add tests for every required invariant in the issue body, especially negative tests: runtime authority cannot create completion; empty evidence refs fail; failed/inconclusive verification fails; mutating the original stream contract after run creation cannot change the run snapshot; artifact refs without digest fail; event envelope rejects or omits raw transcript bodies.
11. Keep the core dependency boundary narrow. ilchul-core should not depend on SQLite, MCP SDKs, Pi/Node packages, filesystem adapters, GitHub, Discord, or CLI crates. If serde is used, keep it as a serialization feature or lightweight core dependency; avoid pulling in adapter concerns.
12. Run validation. The implementation agent should run cargo test -p ilchul-core. If a workspace-level cargo test is cheap after Rust workspace scaffold + DDD core skeleton #238, run that too, but the acceptance gate for this issue is specifically cargo test -p ilchul-core.

Risks / assumptions surfaced by research

• The current checkout appears to lack a Rust workspace, so this issue may depend on Rust workspace scaffold + DDD core skeleton #238 landing first. Conservative assumption: implement only the minimal ilchul-core scaffold if Rust workspace scaffold + DDD core skeleton #238 is absent.
• Existing TypeScript ArtifactRef and ValidationEvidence are useful vocabulary but not strict enough for Core domain invariants for TaskStream authority #239; copying them directly would miss digest and authority invariants.
• Avoid over-modeling future storage/MCP/runtime concerns. SQLite, MCP, Pi adapter, CLI, GitHub, and Discord semantics are explicitly out of scope.
• If serde derives are added to invariant-protected types, make deserialization go through validated constructors or raw DTO conversion; otherwise deserialization could bypass value-object invariants.

Assumptions / human decisions to resolve asynchronously before /approve

• Assumption: this issue may create a minimal Rust workspace/core crate only if Rust workspace scaffold + DDD core skeleton #238 is not merged yet; otherwise it should build on Rust workspace scaffold + DDD core skeleton #238.
• Assumption: local newtypes are preferred over a typed-ID dependency for the first slice unless maintainers have already chosen UUID semantics.
• Assumption: support crates thiserror and optionally serde are acceptable in ilchul-core; digest computation libraries should wait for artifact/store work unless tests need them.

Approval reminder

Implementation starts only after a human comment containing /approve. This comment is a planning handoff; the implementation agent will use the issue body and this discussion as its starting context.

Agent Signature

[devkade]

/approve

[devkade]

Completed by the merged feature PR for this issue. Closing manually because the PR body did not include a GitHub closing keyword before Dani was updated to add Closes #<issue>.