Skip to content

phase-3-semantic-manifest.md

Latest commit

 

History

History
85 lines (60 loc) · 3.25 KB

phase-3-semantic-manifest.md

File metadata and controls

85 lines (60 loc) · 3.25 KB
Raw

Phase 3 - Semantic Manifest

Goal (Execution Plan §17.3): make the manifest (ADR-002) a first-class, editable, round-trippable artifact. Users can import/export a manifest, edit it (form + raw JSON), and the studio warns when an upgrade makes it stale. Schema migrations keep old manifests loadable.

Slice: export ⇄ import round-trip · form + raw-JSON editor · reviewed edits survive re-analyze · staleness by implementation code hash · versioned schema with a migration framework.

Legend: [ ] todo · [~] in progress · [x] done · status: implemented

packages/spec

Versioning & migrations

  • CURRENT_MANIFEST_VERSION constant
  • migrateManifest(input) - read version, apply ordered N→N+1 migrations, validate the result; typed result with fromVersion/toVersion/error
  • Reject manifests newer than the supported version
  • Unit tests (identity v1, missing version, too-new, invalid)

Staleness

  • manifestCodeHash(manifest, contractId?)
  • isManifestStale(manifest, currentCodeHash, contractId?) (compares stored implementation code hash to the live one)
  • Unit tests (match / mismatch / missing data)

packages/classifier

  • set-description review action
  • mergeReviewed(previous, fresh) - re-analysis refreshes technical fields but preserves human-edited display fields for reviewed operations (ADR-002)
  • buildManifest accepts implementationAddress / implementationCodeHash
  • Unit tests (merge preserves reviewed, refreshes analysis)

apps/studio

Manifest binding

  • Persist codeHash on Project (from the resolver result)
  • computeManifest derives abiSource from provenance and passes implementation address + code hash into the manifest
  • Re-analyze preserves reviewed operations via mergeReviewed

Import / export round-trip

  • Import manifest (file) → migrateManifest → validate → persist
  • Errors shown inline; export already exists (JSON download)

Manifest editor

  • ManifestEditor overlay opened from ProjectView
  • Operations tab: edit title, description, audience, visibility, reviewed
  • Raw JSON tab: edit + validate (safeParseManifest) before applying
  • Save persists; Cancel discards

Staleness banner

  • On open, fetch live code hash (implementation for proxies) and compare
  • Banner offers Re-analyze when stale

Docs & CI

  • ADR-004 - manifest versioning & migration strategy
  • Update PROGRESS.md, docs/roadmap.md, backlog
  • Keep lint/typecheck/test/build/e2e green

Definition of done

  • Export a manifest, re-import it into a fresh project - identical result
  • Edit an operation (form or JSON), save, and see it reflected in the app
  • Re-analyze keeps reviewed edits
  • Upgrading the implementation surfaces a staleness banner
  • Old-version manifests load via migration; all checks green

Deferred (follow-ups)

  • Re-analyze refreshes classification on the current ABI + code hash. Full re-resolution (re-fetching a new ABI after an upgrade) reuses the Phase 2 resolver and is tracked as a follow-up.
  • Raw-JSON editor is textarea-based; a schema-aware editor with inline field hints can come with the Phase 3+ polish.