feat(plugin-stack-persistence): parse persisted metadata at the storage boundary

[ENvironmentSet]

Require parsing mechanisms to be provided with Strategies

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e7cb9607-d13b-447a-ae31-e9ec7434417a

📥 Commits

Reviewing files that changed from the base of the PR and between 42639c0 and 76994b7.

📒 Files selected for processing (7)

• .changeset/fep-2612-parse-metadata.md
• extensions/plugin-stack-persistence/src/StackSnapshotMetadataDefinition.ts
• extensions/plugin-stack-persistence/src/StackSnapshotStorage.ts
• extensions/plugin-stack-persistence/src/StackSnapshotStrategy.ts
• extensions/plugin-stack-persistence/src/composeStrategies.ts
• extensions/plugin-stack-persistence/src/index.ts
• extensions/plugin-stack-persistence/src/stackPersistencePlugin.ts

Disabled knowledge base sources:

• Jira integration is disabled
• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added structured metadata creation and validation for persisted stack snapshots.
  • Added metadata parsing support to safely restore compatible snapshots.
  • Composed persistence strategies now store metadata with schema and version information.
  • Unknown or unsupported stored metadata is safely ignored during loading.

• Breaking Changes

  • Persistence strategies now use the new metadata interface and reuse-checking contract.
  • Snapshot metadata is returned as unknown until successfully validated and parsed.

Walkthrough

스냅샷 메타데이터 생성·파싱 API가 추가되고, composed 전략은 스키마·버전·데이터 엔벨로프를 저장·검증합니다. 저장·복원 흐름은 새 API를 사용하며, 복원 시 파싱된 메타데이터로 재사용 여부를 판단합니다.

Changes

메타데이터 기반 스냅샷 persistence

Layer / File(s)	Summary
메타데이터 계약 및 공개 타입 extensions/plugin-stack-persistence/src/StackSnapshotMetadataDefinition.ts, extensions/plugin-stack-persistence/src/StackSnapshotStorage.ts, extensions/plugin-stack-persistence/src/StackSnapshotStrategy.ts, extensions/plugin-stack-persistence/src/index.ts	Result와 StackSnapshotMetadataDefinition을 추가하고, 전략의 메타데이터·재사용 계약과 스토리지 로드 타입을 변경했습니다. 관련 타입은 타입 전용으로 export됩니다.
Composed 메타데이터 엔벨로프 extensions/plugin-stack-persistence/src/composeStrategies.ts	Composed 메타데이터를 schema, version, data 구조로 생성하며, 입력 구조와 하위 전략별 메타데이터를 검증·파싱합니다.
저장·복원 플러그인 연동 extensions/plugin-stack-persistence/src/stackPersistencePlugin.ts, .changeset/fep-2612-parse-metadata.md	저장 시 metadata.create, 복원 시 metadata.parse를 사용하고 파싱된 레코드로 재사용 여부와 스냅샷을 결정합니다. 변경사항을 changeset에 기록합니다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant stackPersistencePlugin
  participant StackSnapshotStorage
  participant StackSnapshotStrategy

  Caller->>stackPersistencePlugin: 스냅샷 저장
  stackPersistencePlugin->>StackSnapshotStrategy: metadata.create(args)
  StackSnapshotStrategy-->>stackPersistencePlugin: metadata
  stackPersistencePlugin->>StackSnapshotStorage: save(record)

  Caller->>stackPersistencePlugin: 스냅샷 복원
  stackPersistencePlugin->>StackSnapshotStorage: load()
  StackSnapshotStorage-->>stackPersistencePlugin: record
  stackPersistencePlugin->>StackSnapshotStrategy: metadata.parse(record.metadata)
  StackSnapshotStrategy-->>stackPersistencePlugin: parsed metadata
  stackPersistencePlugin->>StackSnapshotStrategy: shouldReuse(parsedRecord)
  StackSnapshotStrategy-->>stackPersistencePlugin: boolean

Loading

Possibly related PRs

• daangn/stackflow#727: 동일한 persistence 흐름에서 전략 및 메타데이터 계약 변경을 다룹니다.
• daangn/stackflow#731: 저장 시 stack을 포함한 메타데이터 생성 경로와 연결됩니다.
• daangn/stackflow#734: composeStrategies.ts의 새 메타데이터 API와 composed 메타데이터 구조 변경에 연결됩니다.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/fep-2612

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

• @stackflow/demo

  yarn add https://pkg.pr.new/daangn/stackflow/@stackflow/plugin-stack-persistence@735.tgz
  

commit: 481e119

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	stackflow-docs	76994b7	Commit Preview URL	Jul 22 2026, 03:30 PM

[cloudflare-workers-and-pages]

Deploying stackflow-demo with    Cloudflare Pages

Latest commit:	76994b7
Status:	⚡️  Build in progress...

View logs

[changeset-bot]

🦋 Changeset detected

Latest commit: 76994b7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@stackflow/plugin-stack-persistence	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR