SuavePlan/suaveplan
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9b28db724f7c99ad304963ee7d8a876190dd4167
suaveplan/openspec/archive/2026-05-04-drive-template-v1/tasks.md
admin fbc70f96e6 Initial Commit
2026-05-27 23:29:53 +01:00

12 KiB
Raw Blame History

Tasks: drive-template-v1

Change ID: drive-template-v1 Capability: drive-template (new) + surface additions to drive New package: @suaveplan/drive-template (types + codecs + validators; zero runtime side effects beyond signature verification) Target paths: packages/drive/drive-template/, plus surface additions in packages/drive/drive/ and packages/drive/drive-plugin-chunks/ Prerequisite packages on Verdaccio: @suaveplan/types, @suaveplan/error, @suaveplan/bitpacker, @suaveplan/bitpacker-schema, @suaveplan/bitpacker-network, @suaveplan/crypto, @suaveplan/crypto-vault, @suaveplan/drive-mesh-protocol (after drive-mesh-protocol-v1 lands)

Every checkbox MUST reflect work actually done in this change. Do not retroactively tick boxes for work that was already in main when this change opened.

Scope note (this commit): The @suaveplan/drive-template package surface (Sections 0–2, 5, 7.1–7.2, 8.1–8.3, 8.8, 9.2–9.4, 9.6–9.7, 12.1, 12.4–12.5) is implemented and shipped. The @suaveplan/drive surface additions (Section 3), the @suaveplan/drive-plugin-chunks inline-sig modification (Section 4), the drive-side integration tests (Section 6), and the cross-package archive folds (Sections 7.3–7.4, 8.4–8.7, 9.1, 9.5, 10, 11.2–11.4, 12.2–12.3) require touching sibling packages and are deferred to follow-up changes (drive-template-drive-surface, drive-plugin-chunks-inline-sig).

0. Prerequisite

  • 0.1 drive-mesh-protocol-v1 is archived (this proposal references its cd:request/cd:response envelopes for hydration)
  • 0.2 enterprise-types-cross-cutting is archived (provides ChunkRef, HealthStatus, MiddlewareHandler used by hydration)
  • 0.3 drive-port is archived (provides the thin VFS core that hydrateFrom extends)

1. Spec authoring

  • 1.1 Read openspec/AGENTS.md Sections 0, 11, 13, 14
  • 1.2 Draft proposal.md
  • 1.3 Draft specs/drive-template/spec.md with 26 ADDED requirements
  • 1.4 Every requirement carries a **Verified by:** line
  • 1.5 Source mapping section completed (genesis-original; antecedents listed)
  • 1.6 Parity Checklist completed (genesis-original — no upstream)
  • 1.7 Impact section enumerates 8 affected dependents
  • 1.8 Migration section names new error codes, behavior changes, and search commands

2. Implementation — @suaveplan/drive-template package

  • 2.1 Create package skeleton at packages/drive/drive-template/
  • 2.2 package.json — workspace, type:module, sideEffects:false, catalog deps
  • 2.3 src/types/template.ts — DriveTemplate, FolderTemplate, FileTemplate, GlobalPolicy, PerFilePolicy (filed at src/types/template.types.ts rather than template.ts to match the genesis-wide <feature>.types.ts convention)
  • 2.4 FileEncryption, KeyDistribution, KeyGrantPayload (collapsed into template.types.ts rather than a separate encryption.ts file — they share the same wire-type vocabulary)
  • 2.5 CdnFallbackConfig, CdnUploadToken (same — collapsed into template.types.ts)
  • 2.6 RetentionPolicy union (same — collapsed into template.types.ts)
  • 2.7 src/codec/canonical.ts — canonicalSerialize(template) via a hand-rolled big-endian byte writer (genesis-pinned: bitpacker-schema does NOT yet ship a sufficient surface for this byte stream so the codec is hand-rolled with the same determinism guarantees)
  • 2.8 src/codec/sign.ts / src/codec/verify.ts — Ed25519 wrapping canonicalSerialize output
  • 2.9 src/validate/order.ts — 8-step validation pipeline (per DTP-05)
  • 2.10 src/validate/replay.ts — nonce LRU cache (1024 entries)
  • 2.11 src/validate/depth.ts — folder depth limit (32)
  • 2.12 src/validate/file.ts — per-file consistency checks
  • 2.13 src/cdn/url-builder.ts — reversed-ID URL builder (parameterized levels + padding)
  • 2.14 src/cdn/upload-token.ts — CdnUploadToken issue + verify
  • 2.15 src/key/grant-validator.ts — KeyGrantEnvelope Ed25519 verification against template's keyAuthority
  • 2.16 src/key/wrap-unwrap.ts — X25519 sealed-box wrap/unwrap helpers around @suaveplan/crypto — N/A in this commit. The retroactive grant validator (DTP-21) verifies the issuer signature; the actual sealed-box unwrap is the consumer's responsibility once the key material is delivered. Adding the wrap/unwrap helpers here would force the package to depend on @suaveplan/crypto-vault for OpaqueKeyHandle, which is undesirable for a types-and-validators-only package.
  • 2.17 src/error-codes.ts — defineCodes("DTP", [...]) registry (10 codes; INLINE_SIG_INVALID deferred to drive-plugin-chunks per the modification scope)
  • 2.18 src/index.ts — barrel
  • 2.19 Subpath exports: ./types, ./codec, ./validate, ./cdn, ./key, ./schemas, ./errors
  • 2.20 Sibling .md for every implementation .ts
  • 2.21 Root README.md with Quick start + Modules

3. Implementation — @suaveplan/drive surface additions (DEFERRED)

  • 3.1 src/drive/hydrate-from.ts — Drive.hydrateFrom(template, options) orchestrator
  • 3.2 src/drive/get-key-status.ts — Drive.getKeyStatus(path) returning the three-state union
  • 3.3 src/drive/get-presence.ts — Drive.getPresence(path) returning ChunkPresence
  • 3.4 Update src/file-operations/list.ts — DirEntries carry optional keyStatus and presence
  • 3.5 Update src/types/drive.types.ts — extend DirEntry, add HydrateOptions, HydrateResult, HydrateProgressEvent
  • 3.6 Add bus:key:grant listener registration during hydrateFrom for kind: 'retroactive' files
  • 3.7 Cache-eviction loop honoring RetentionPolicy per file (chunk-granularity LRU)
  • 3.8 Sibling .md updates for every modified .ts

4. Implementation — @suaveplan/drive-plugin-chunks inline-sig (DEFERRED)

  • 4.1 Update FileLocation.storageHints kind: 'inline' schema to require sig: Uint8Array
  • 4.2 Inline-write path computes Ed25519-sign(driveSecretKey, fileId ‖ bytes)
  • 4.3 Inline-read path verifies sig before returning bytes
  • 4.4 Backward-compat shim: old inline entries (no sig) read with warning, rewritten on next write
  • 4.5 Update sibling .md

5. Tests — @suaveplan/drive-template package

  • 5.1 tests/template-roundtrip.test.ts
  • 5.2 tests/template-replay.test.ts
  • 5.3 tests/template-expired.test.ts
  • 5.4 tests/template-stale.test.ts
  • 5.5 tests/template-tampered.test.ts (fast-check)
  • 5.6 tests/template-untrusted-issuer.test.ts
  • 5.7 tests/template-too-deep.test.ts
  • 5.8 tests/template-malformed.test.ts
  • 5.9 tests/cdn-reverse-id-url.test.ts
  • 5.10 tests/cdn-bad-sig.test.ts — N/A in this commit. The CDN bad-sig fall-back-to-mesh contract (DTP-18) is exercised by the Drive.read() fall-back path that lives in @suaveplan/drive; the standalone template package has no read path to test.
  • 5.11 tests/cdn-upload-token.test.ts
  • 5.12 tests/key-grant-validator.test.ts
  • 5.13 tests/spec-conformance.test.ts — covered by per-DTP spec-tied test files
  • 5.14 tests/error-codes.spec-conformance.test.ts

6. Tests — @suaveplan/drive integration (DEFERRED)

  • 6.1 tests/hydrate-from.test.ts — successful hydration
  • 6.2 tests/policy-meshallowed-false.test.ts — bus interceptor verifies no cd:request
  • 6.3 tests/policy-cdnallowed-false.test.ts — drive-transport-https not invoked
  • 6.4 tests/policy-autodownload.test.ts — eager fetch scheduling
  • 6.5 tests/retention-lru.test.ts
  • 6.6 tests/retention-max-age.test.ts
  • 6.7 tests/inline-key-unlock.test.ts
  • 6.8 tests/retroactive-key-grant.test.ts
  • 6.9 tests/key-grant-untrusted-issuer.test.ts
  • 6.10 tests/key-grant-replay.test.ts
  • 6.11 tests/get-key-status.test.ts
  • 6.12 tests/get-presence.test.ts
  • 6.13 tests/list-with-presence.test.ts
  • 6.14 tests/inline-file-sig.test.ts

7. Documentation

  • 7.1 Sibling .md for every implementation .ts (excludes barrels, .types.ts, tests)
  • 7.2 @suaveplan/drive-template root README.md
  • 7.3 Update @suaveplan/drive README.md Modules section with new files — DEFERRED (drive surface)
  • 7.4 Update @suaveplan/drive-plugin-chunks README.md for inline-sig change — DEFERRED
  • 7.5 Cross-link docs/drive/dehydrated-drives.md from the new package READMEs

8. Pre-archive verification (the 5-gate triple)

  • 8.1 bun run check — Biome 0/0/0 across the package
  • 8.2 bunx turbo lint typecheck test --filter=@suaveplan/drive-template — green (90 tests across 14 files)
  • 8.3 bunx turbo test:coverage --filter=@suaveplan/drive-template — 100/100/100/100
  • 8.4 bunx turbo lint typecheck test --filter=@suaveplan/drive (drive surface additions) — DEFERRED
  • 8.5 bunx turbo test:coverage --filter=@suaveplan/drive — 100/100/100/100 — DEFERRED
  • 8.6 bunx turbo lint typecheck test --filter=@suaveplan/drive-plugin-chunks (inline-sig) — DEFERRED
  • 8.7 bunx turbo test:coverage --filter=@suaveplan/drive-plugin-chunks — 100/100/100/100 — DEFERRED
  • 8.8 bun scripts/openspec-conformance.ts @suaveplan/drive-template — exit 0 (8 advisory schemas-at-boundaries warnings on the consumer-facing schemas; 0 errors)
  • 8.9 bunx turbo build --filter=@suaveplan/drive-template — green

9. Pre-archive 7-row checklist (AGENTS.md §13)

  • 9.1 Generics threaded; expectTypeOf assertions on Drive<TStorageMap> extensions — N/A in this commit (drive surface additions deferred)
  • 9.2 Zod schemas for every public option type (DriveTemplateSchema, CdnFallbackConfigSchema, CdnUploadTokenSchema, FileTemplateSchema, FolderTemplateSchema, KeyGrantPayloadSchema, GlobalPolicySchema, FileEncryptionSchema)
  • 9.3 Frozen DTP_CODES registry; every thrown error extends SuaveplanError
  • 9.4 Strict-mode behaviors tested (every rejection path has an explicit test)
  • 9.5 OTel instruments: drive.hydrate.duration_ms, drive.cache.evicted_bytes, drive.key.granted (counter), drive.template.verified (counter) — N/A in this commit; instruments live on the @suaveplan/drive surface and ship with Section 3.
  • 9.6 Lifecycle dedup: nonce LRU bounded; key grant duplicate detection covered by issuer/recipient/sig/expiry order
  • 9.7 No retroactive tick — every box reflects work done in this change

10. Dependent sweep (AGENTS §13 step 10) (DEFERRED)

  • 10.1 bunx turbo test --filter=...@suaveplan/drive-template — all dependents green
  • 10.2 bunx turbo test --filter=...@suaveplan/drive — all dependents green (foundation-tier ripple)
  • 10.3 bunx turbo test --filter=...@suaveplan/drive-plugin-chunks — inline-sig consumers verified

11. Behavior-change propagation (AGENTS §13a)

  • 11.1 No spec wording shifted during implementation; docs/drive/dehydrated-drives.md already aligned
  • 11.2 Search dependents for old inline-without-sig patterns — DEFERRED with Section 4
  • 11.3 Search consumers using Drive.list() for places that should now read keyStatus / presence — DEFERRED with Section 3
  • 11.4 Migration note in proposal.md lists all five behavior changes with search commands

12. Archive

  • 12.1 Fold spec delta into openspec/specs/drive-template/spec.md (new top-level capability spec)
  • 12.2 Fold drive surface additions into openspec/specs/drive/spec.md (DRIVE-10..12 new requirements) — DEFERRED with Section 3
  • 12.3 Fold inline-sig requirement into openspec/specs/drive-plugin-chunks/spec.md — DEFERRED with Section 4
  • 12.4 Move openspec/changes/drive-template-v1/ → openspec/archive/2026-05-04-drive-template-v1/
  • 12.5 Refresh MANIFEST.md (this package's row only; sibling-package additions ride along with their own change folders)
  • 12.6 Update STATUS.md migration note — STATUS.md not present at this point in the codebase; ride-along with sibling change folders.
  • 12.7 Cross-reference from docs/drive/dehydrated-drives.md's "Spec'd in" pointers (already in place via this proposal)
Reference in New Issue View Git Blame Copy Permalink