Skip to content

Edge Contracts and Skills

Jump to bottom
pawaca edited this page Aug 30, 2026 · 1 revision

Edge Contracts & Skills

Mandatory adaptation rules and AI-assisted workflows — from AGENTS.md.

Source: AGENTS.md — the single source of truth for all repository rules.

Overview

dsh-edge wraps published @deepseek-ai/dsh-* packages. Upstream ships fast, Edge has no influence over upstream decisions, and Cloudflare Workers impose hard platform constraints. A layered configuration system governs how both humans and AI agents work with this codebase:

  • CLAUDE.md — a one-line pointer that tells Claude Code to read AGENTS.md. Avoids rule duplication.
  • AGENTS.md — the single source of truth: ownership boundaries, commands, runtime invariants, change discipline, review workflow, release procedure, and git hygiene.
  • .agents/skills/ — three specialized skill files that encode the pre-push, code review, and review-loop workflows as structured instructions.

File Structure

.
├── CLAUDE.md                              # Pointer → AGENTS.md
├── AGENTS.md                              # Repository rules (source of truth)
├── .claude/
│   └── settings.json                      # Claude Code permissions
└── .agents/
    └── skills/
        ├── codex-review-loop/
        │   ├── SKILL.md                   # Review loop skill
        │   ├── scripts/codex-state.sh     # PR state sensor
        │   ├── tests/codex-state.test.sh  # Sensor tests
        │   └── agents/openai.yaml         # Codex agent config
        ├── dsh-code-review/
        │   └── SKILL.md                   # Code review skill
        └── dsh-pre-push-checks/
            ├── SKILL.md                   # Pre-push skill
            └── agents/openai.yaml         # Codex agent config

Contracts Summary

The contracts exist to minimize merge conflicts, maximize upstream leverage, protect durable state, and enforce credential safety. Violations are always blocking.

# Category Rule
R1 [Upstream] Single upstream version
R2 [Upstream] Dual-mode alignment
R3 [Upstream] Durable Object stability
R4 [Perf] No unbounded SQL scans
R5 [Security] Credential safety
R6 [Cordis] Provide after register
R7 [Release] Gzip budget + prebuilt tests
R8 [Release] Patch discipline
R9 [Release] Version identity

Upstream Coupling

R1 — Single Upstream Version

Rule: Keep every @deepseek-ai/dsh-* standalone dependency on one exact upstream version. Upgrade only in an explicit upstream-baseline PR.

Why: Mixed versions create invisible incompatibilities between packages designed and tested together.

✅ Compliance: All 30+ @deepseek-ai/dsh-* packages in standalone/package.json pin to 0.1.1-rc.2. All 7 patches are version-bound.

❌ Violation: Upgrading dsh-tools to 0.1.2 alone while leaving everything else at 0.1.1-rc.2.

R2 — Dual-Mode Alignment

Rule: Keep Direct and Dynamic Loader modes behaviorally aligned except for their command-execution backend and Cloudflare plan requirement.

Why: If the two modes diverge in session behavior or API responses, bugs become plan-specific and untestable in one mode.

✅ Compliance: Integration tests run against both modes. Session creation, event format, and projection broadcast are identical.

❌ Violation: Adding a file-upload feature that only works in Dynamic mode without a stub or graceful degradation in Direct mode.

R3 — Durable Object Stability

Rule: Preserve DO class names, bindings, session/event formats, workspace/VFS state, owner authentication, and public HTTP/WebSocket behavior.

Why: Renaming a DO class or changing a binding loses access to all existing state. Breaking session event formats means users lose their conversations.

✅ Compliance: DshEdgeInstance class name and DSH_EDGE binding stable since v0.1.0. The 5 SQL tables use additive migrations only.

❌ Violation: Renaming DshEdgeInstance to EdgeDurableObject — all existing DO instances become unreachable.

Performance

R4 — No Unbounded SQL Scans

Rule: DO SQL queries on request-serving paths must not use correlated subqueries or per-row scans against unbounded tables. Pre-compute in a materialized table maintained atomically at write time.

Why: DO SQL runs inside the Worker request handler. A full table scan blocks the entire request. DO has no query optimizer.

✅ Compliance: dsh_session_summaries is a materialized table maintained by syncSummaries() at write time. Session listing reads from this table instead of scanning dsh_session_events.

❌ Violation: SELECT s.id, (SELECT MAX(seq) FROM dsh_session_events e WHERE e.session_id = s.id) FROM dsh_sessions s

Security

R5 — Credential Safety

Rule: Never log DSH_EDGE_ACCESS_KEY, bearer tokens, or owner cookies. Resolved values remain request-scoped and are never logged, cached across requests, or written to session events.

Why: Worker logs are accessible via Cloudflare dashboard. Session events are transmitted over WebSocket — embedding credentials broadcasts them to every connected client.

✅ Compliance: EdgeCredentialProvider.describe() returns { configured, source, writable } without the value. Auth failure logs 'The access key is not valid.', never the submitted key.

❌ Violation: console.log('API key resolved:', credential.value). Or storing resolvedApiKey on the DO instance across requests.

Cordis Framework

R6 — Provide After Register

Rule: When registering a cordis sub-registry entry, call ctx.provide(key, value) if another plugin uses ctx.inject([key]). Sub-registry register() only updates internal Maps; it does not trigger inject resolution. Use ctx.effect() to pair registration with provide and clean up on disposal.

Why: Without the paired provide, downstream plugins like StorageDomain never start, and the session store silently hangs on boot.

✅ Compliance: In session-store.ts:

ctx.effect(() => {
  const dispose = ctx.storage.backend.register('durable-object', storageBackend)
  ctx.provide('storage.backend.durable-object', true)
  return () => { dispose(); ctx.provide('storage.backend.durable-object', undefined) }
})

❌ Violation: ctx.storage.backend.register('durable-object', storageBackend) without calling ctx.provide().

Release

R7 — Gzip Budget + Prebuilt Tests

Rule: Direct mode must stay below the repository gzip budget. Release tests must start the promoted prebuilt artifacts, not source entrypoints.

Why: Workers have a hard 10 MiB compressed limit. Testing prebuilt artifacts catches bundler regressions that only manifest in the production build.

✅ Compliance: bundle-size.mjs throws if gzip budget exceeded. Snapshot tests run against bundled output.

❌ Violation: Running integration tests against src/index.ts via Vite dev server instead of the promoted prebuilt Worker.

R8 — Patch Discipline

Rule: Every retained upstream patch needs a version-bound filename, a failing-without-the-patch check, a rationale, and a removal condition.

Why: Without a version-bound filename, patches silently outlive their purpose. Without a failing-without test, patches become no-ops.

✅ Compliance: All 7 patches include the upstream version in their filename: @deepseek-ai__dsh-sandbox@0.1.1-rc.2.patch.

❌ Violation: A patch named fix-llm-streaming.patch with no version binding, no test, no removal condition.

R9 — Version Identity

Rule: The npm package, tag, GitHub Release, deployment identity, and documentation must report the same dsh-edge version. apps/dsh-edge/package.json is the only release-version source.

Why: Version drift between npm, GitHub, and deployment creates confusion about what's actually running.

✅ Compliance: repository-metadata.spec.ts asserts only apps/dsh-edge/package.json has a version. Snapshot tests derive the expected version from this single source.

❌ Violation: Adding "version": "0.7.1" to the root package.json.

Skills

Skills are structured instruction files (SKILL.md) that AI agents load before performing specific workflows. The three skills form a pipeline:

┌─────────────────────┐
│  codex-review-loop   │  Drives the overall PR lifecycle
│                     │  (triage → fix → push → review → CI)
└──────┬──────┬───────┘
       │      │
       ▼      ▼
┌──────────┐ ┌──────────────────┐
│ dsh-code │ │ dsh-pre-push     │
│ -review  │ │ -checks          │
└──────────┘ └──────────────────┘
  Judges       Selects and runs
  findings     checks before push
Skill Purpose When Used
dsh-pre-push-checks Select and run minimum-sufficient checks before pushing Before any push or PR-ready transition
dsh-code-review Review PRs for Edge-specific correctness (8 blocking checks) Judging review findings; deciding merge-readiness
codex-review-loop Drive PR through bounded review and CI convergence After opening/updating a PR

dsh-pre-push-checks

Classifies changed files by owned surface and selects the minimum evidence needed:

  • Runtime/storage/auth → focused unit test + affected integration path
  • Edge client/UI → focused test + browser/runtime snapshot suite
  • Standalone deps/patches/bundle → standalone build + verifier + promote prebuilt artifacts
  • Installer/release → pack + pack:verify outside workspace
  • Docs/governance → pnpm run doc-sync + manual bilingual comparison
  • Cross-cutting → full suite: check, both builds, integration, snapshots, package verify

dsh-code-review

Eight blocking checks specific to dsh-edge PRs:

  1. Upstream composition from exact published packages (no copied source)
  2. Direct/Dynamic artifact parity
  3. Durable Object compatibility
  4. Credential safety (never in durable state, logs, fixtures)
  5. Direct mode gzip budget
  6. Patch discipline (version-bound, justified, tested, removable)
  7. Installer/release cross-platform and secret safety
  8. Product/legal prose — independent project, not DeepSeek-affiliated

codex-review-loop

A state machine that drives PRs through iterative review rounds:

  • One tick per invocation — read snapshot, triage all findings, make one fix batch, push, request review.
  • Finding triage — each finding gets exactly one of: fixed, rebutted, or user-decision.
  • Convergence enforcement — 2nd occurrence → general repair; 3rd → strategy reset; every 2 actionable rounds → checkpoint.
  • Completion contract — ready-to-merge requires stable HEAD, all items handled, review passed, CI green. Never merges automatically.

Developer Workflow

Before Your First Change

  1. Read AGENTS.md — understand ownership boundaries and the 9 contracts above.
  2. Create a worktree for your branch (never work directly on main).
  3. Run pnpm install and pnpm --dir apps/dsh-edge/standalone install --frozen-lockfile.

Before Every Push

  1. Classify your changes by surface (runtime, client, standalone, installer, docs, cross-cutting).
  2. Run the minimum checks for that surface (as defined in dsh-pre-push-checks).
  3. Commit only inspected paths — no blind git add -A.

During PR Review

  1. Review findings are claims, not commands — verify each one's premise before acting.
  2. Assign each finding: fixed, rebutted, or user-decision.
  3. Track problem families — if the same family appears twice, stop patching and write one general repair.
  4. Never merge the PR yourself — report readiness and let the maintainer decide.

Release Checklist

  1. Write bilingual release notes + i18n pairing → pnpm run doc-pairs -- --write
  2. Merge release PR to main (squash merge)
  3. Tag: git tag dsh-edge-v<version> && git push origin dsh-edge-v<version>
  4. Verify: npm view dsh-edge@<version> and gh release view dsh-edge-v<version>

Contracts vs. conventions. These rules are not style preferences — they are invariants that protect durable state, credential safety, and upgrade paths. The underlying principle is maximize upstream capability leverage: use published packages as-is, write the smallest possible adapter layer, and ensure that adapter can absorb upstream changes without rewriting.

English

中文

Clone this wiki locally