task_220726_7 — SDK State/Serialization + Daemon Preferences & Capability Detection (Santiago)

[umeradl]

cc @Santiagocetran
Task assigned for Jul 22–28, 2026 (5 working days; deadline Tuesday, July 28). Full spec: Developer/tasks/task_220726_7.md

The task file has the full specification — exact module layouts, function signatures, storage/command shapes, and test plan. This post is just the summary and assignment notice.

Summary

This continues the work already visible in draft PRs #31 (feat/din-sdk) and #32 (feat/din-daemon) — reviewed directly against those branches, not just the PR descriptions, which lag the actual commits (errors.py and manifest.py are further along than PR #31's body currently states).

Per Developer/design/sdk-interface-proposal.md §8's proposed layout, the SDK still needs session.py, wallet.py, state.py, serialize.py, tx.py, worker.py, and the operations/ layer — too much for one week, and the biggest pieces touch private-key/keystore handling directly. This task deliberately splits off the two lowest-risk, self-contained slices:

Part A (#20, SDK): dincli/sdk/state.py (GI-state enums/converters + validate_* predicates, extracted from cli/utils.py the same way the two prior waves extracted ipfs/contracts/manifest/runtime) and dincli/sdk/serialize.py (the to_envelope() + JSON-encoder contract from proposal §3 — uint256-as-string, bytes→hex, enums→name, etc.).

Part B (#21, daemon): preferences (dind preferences show/set, P4-2.1) and hardware-only capability detection (dind capabilities, P4-2.2 — CPU/RAM/disk/GPU-presence plus a bare reachability probe for RPC/IPFS, not a live session call), extending the existing /health resource block rather than duplicating it.

Deliberately not in this task: wallet.py/session.py (DinSession, SignerProvider) and tx.py's send() keystone — the private-key/signing surface from proposal §2/§5b. That's flagged as the next task, with its own review pass given the sensitivity, rather than bundled in alongside unrelated daemon work. See the task file's "Scope boundaries" section for the full list of what's explicitly out.

Reference material

• Developer/design/sdk-interface-proposal.md — §2 (session/signer, next task), §3 (envelope, this task), §5b (tx keystone, next task), §8 (package layout)
• SDK #20 (draft): dincli/sdk foundation — loaders + manifest/runtime + state/serialize #31, dind #21 (draft): daemon scaffold + preferences/capabilities (P4-1.1, P4-2.1/2.2) #32 — the draft PRs this task continues
• start DIN-SDK #20, start DIN daemon #21 — the long-running tracking issues

If anything in the task spec feels ambiguous, or you think of a better strategy for slicing this than what's written — say so in this thread, don't just silently deviate. cc @umeradl.

[umeradl]

@Santiagocetran — hold off on this task for now, something's pending on my side first. I'll take care of it and update the task file once it's done.

Pending on my side:

1. Review of the SDK interface proposal v0.3 (Developer/design/sdk-interface-proposal.md, posted on issue start DIN-SDK #20 on Jul 12 and now living in PR SDK #20 (draft): dincli/sdk foundation — loaders + manifest/runtime + state/serialize #31). I told you on Jul 13 I'd post feedback on start DIN-SDK #20 "soon" so you could freeze the contract — that never actually landed. This task deferred the wallet/session/tx keystone specifically because you're waiting on that sign-off, so it's the right thing to clear before more work stacks up behind it.

I'll post the review on #20 directly, then come back here with the go-ahead (or any scope adjustments) on task_220726_7.

[umeradl]

Posted the review: #20 (issuecomment-5052822588). Go ahead on task_220726_7 — no scope adjustments needed.

Quick summary for reference: §2 (session/signer), §3 (envelope/serialization), §4/§4a (errors), §5b (tx keystone), §6 (plan/apply), and §8 (package layout) are all approved, with a handful of open questions noted per-section (nonce management under §5b is the one I'd weigh heaviest — it's a live gap in get_tx_params()'s nonce fetch today, not just a doc nit). None of those open items touch state.py, serialize.py, preferences, or capability detection, so they don't block this task — they'll matter once you get to wallet.py/session.py/tx.py, which this task already correctly scopes out.

Task file's scope boundaries stand as written. Go ahead and start on Part A + Part B.

[Santiagocetran]

Progress update on task_220726_7 — thanks for the go-ahead above, @umeradl.

✅ Part A landed — SDK state.py + serialize.py (#20, PR #31)

Pushed to feat/din-sdk (PR #31, still draft):

• dincli/sdk/state.py — GI-state converters moved verbatim from cli/utils.py (now a re-export shim, call sites unchanged); added a GIState IntEnum and two validate_* predicates lifted from DinContext's guards, raising the SDK ValidationError. The context.py guards delegate to them with identical output/exit codes — no CLI behavior change.
• dincli/sdk/serialize.py — to_envelope() + metadata-driven encoder implementing every proposal §3 rule (uint256→string, omit, bytes→hex, address→checksummed, enum→name, Decimal→string, None→null).
• 144 unit tests green (+23 new); import-boundary holds across all 11 SDK modules.

⏭️ Deferred to the next task — the wallet/session/tx keystone

As the task spec calls out, the private-key/signing keystone is deliberately not in this slice and is the dedicated next task, flagged for your review given the crypto sensitivity (same treatment as the treasury/fee-router work):

• dincli/sdk/wallet.py, session.py (DinSession), SignerProvider (proposal §2)
• tx.py's send() keystone (proposal §5b) — also blocked on DinSession
• the operations/ role-command refactor — blocked on the above

Your §5b nonce-management note lands with this next task, not the current slice.

🔜 Next up — Part B (daemon, #21, PR #32)

dind preferences show/set + dind capabilities (P4-2.1 / P4-2.2, local-only slice) on feat/din-daemon. That branch will be synced onto the updated feat/din-sdk first (the two PRs are stacked).

Feedback welcome on the envelope shape / encoder rules before the operations/ layer starts consuming it.

[umeradl]

Reviewed PR #31 @ 6eac109 — full review posted on the PR: #31 (review)

Short version: mergeable as-is. state.py's GI-state converters are byte-identical to the pre-move code (checked against DINShared.sol's enum ordinals too — exact match), serialize.py's encoder handles every §3 rule correctly including several edge cases beyond the existing tests, import-boundary test is real (not vacuous), and the 144-test claim reproduces exactly.

Two things worth knowing about before this lands, neither blocking:

• "Zero behavior change" isn't quite accurate — three console.print → logger.* conversions in the moved code are a real (if minor) behavior change: lost rich styling, moved to stderr, now log-level-gated. Recommend softening that claim in the commit messages (not needed Santigo).
• ipfs.py's # TODO(sdk-keystones): IpfsError is mislabeled — it isn't actually blocked on the wallet/session keystone, and it's a real gap for dind's future retry logic today. Worth a quick fix rather than sitting bundled with the deferred private-key work.

Full findings (6 total, all non-blocking) and the two open asks from the earlier design review are in the PR review comment.

[Santiagocetran]

Part B landed — task_220726_7 is now complete on the implementation side.

✅ Part B — daemon preferences + capability detection (#21, PR #32)

Pushed to feat/din-daemon (PR #32, draft; synced onto feat/din-sdk):

• dind preferences show / set — preferences.py (domain, risk_tolerance, min_expected_reward, privacy_constraints) stored as preferences.json; partial updates, defaults on missing/empty file.
• dind capabilities — capabilities.py: CPU/RAM (stdlib os.sysconf + /proc/meminfo, no new dep)/disk, best-effort GPU, and bare socket reachability probes for RPC/IPFS (per boundary Bump lodash from 4.17.21 to 4.18.1 in /hardhat in the npm_and_yarn group across 1 directory #5 — not a live RPC call). Pure score_/compatible_with for later task-matching.
• /health now shares a fast resource_snapshot() (CPU+disk+RAM) — de-duplicated; GPU/network probes kept off the poll path.
• 213 unit tests green (dind + sdk); network-hermetic capability tests; a guard asserts /health runs no socket probe.

Task status

• ✅ Part A (SDK state/serialize) — PR SDK #20 (draft): dincli/sdk foundation — loaders + manifest/runtime + state/serialize #31
• ✅ Part B (daemon preferences/capabilities) — PR dind #21 (draft): daemon scaffold + preferences/capabilities (P4-1.1, P4-2.1/2.2) #32
• ⏭️ Deferred next task, flagged for @umeradl — the wallet/session/tx keystone (wallet.py, session.py, SignerProvider §2, tx.send() §5b) + the operations/ role layer. Your §5b nonce-management note lands here. dind still does no signing / on-chain submission until this lands.

Both PRs remain drafts pending review. Ready for feedback whenever.

[umeradl]

Reviewed PR #32 @ 99f060b — full review posted on the PR: #32 (review)

Short version: mergeable as-is, no correctness blockers. The no-signing/no-wallet-access boundary genuinely holds (grepped dincli/dind/ — no wallet/keystore/web3-signing references anywhere, the one registered job type is a no-op). WAL-mode SQLite job store is properly race-safe, crash recovery is real and tested, /health is correctly kept cheap (verified with a real test asserting no socket probe on the poll path), preferences partial-update semantics are correct. The 213-test claim reproduces exactly.

Six findings, all non-blocking for merge, but two are worth tracking as near-term follow-ups since they undercut this PR's own claims once dind is doing real work: dind start's live-PID check has a real TOCTOU race (two daemons can end up running against the same state dir), and the container healthcheck can't actually detect the "degraded" status the code computes — only a fully-crashed daemon triggers Docker's restart. A third (the example systemd/dind.service unit uses template-only specifiers and won't work as shipped) is a quick fix worth doing before anyone copies it. Full details in the PR review comment.

task_220726_7 is done — both parts landed clean, no scope adjustments needed. Nice work closing this out end to end.

Next task assigned: task_300726_8 — the wallet/session/tx signing keystone. Spec: Developer/tasks/task_300726_8.md, 5 working days (Jul 31–Aug 6). This is DinSession/SignerProvider (§2) + wallet.py + tx.py's send() keystone (§5b) — the security-sensitive slice both of us have been flagging as next. It also folds in the nonce-management gap in get_tx_params() (the open item I weighted heaviest in the §5b review) and the three other open §5b questions. sdk/operations/ and plan/apply (§6) stay out of scope for this one too — flagged as the task after, same as this task deferred the keystone.

Shout if anything in the spec conflicts with what you find on the branch, or if you'd slice it differently.