fix(plugin-stack-persistence): report metadata parse failures

[ENvironmentSet]

Summary

• Report storage and metadata parse failures through the existing onRecordLoadError callback as distinct error types.
• Add optional detail to failed metadata parse results and preserve nested composed-strategy details.
• Export StackSnapshotMetadataParseError and update the package changeset.

[changeset-bot]

⚠️ No Changeset found

Latest commit: af3604c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 1 package

Name	Type
@stackflow/plugin-stack-persistence	Major

Click here to learn what changesets are, and how to add one.

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

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 4a3f08fd-bb28-4107-9292-a8616bc8cf57

📥 Commits

Reviewing files that changed from the base of the PR and between b44aba9 and af3604c.

📒 Files selected for processing (6)

• .changeset/fep-2612-parse-metadata.md
• extensions/plugin-stack-persistence/src/StackSnapshotMetadataDefinition.ts
• extensions/plugin-stack-persistence/src/composeStrategies.ts
• extensions/plugin-stack-persistence/src/errors.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 detailed metadata parsing errors, including context about the validation failure and affected strategy.
  • Added a dedicated error type for snapshot metadata parsing failures.

• Bug Fixes

  • Metadata parsing failures are now reported through the record-load error callback instead of being silently ignored.
  • Improved validation for metadata schema, version, data structure, and composed strategy contents.

• Documentation

  • Updated persistence strategy documentation to describe expanded metadata handling and error reporting.

Walkthrough

Metadata parsing now returns structured failure details, including composed-strategy context. Snapshot loading wraps metadata parse failures in an exported error and reports them through onRecordLoadError.

Changes

Metadata error reporting

Layer / File(s)	Summary
Structured metadata validation extensions/plugin-stack-persistence/src/StackSnapshotMetadataDefinition.ts, extensions/plugin-stack-persistence/src/composeStrategies.ts	Metadata parse failures now carry optional details for invalid envelopes, mismatched strategy keys, and underlying strategy errors.
Persistence load error propagation extensions/plugin-stack-persistence/src/errors.ts, extensions/plugin-stack-persistence/src/index.ts, extensions/plugin-stack-persistence/src/stackPersistencePlugin.ts, .changeset/fep-2612-parse-metadata.md	Metadata parse failures are exposed as StackSnapshotMetadataParseError, accepted by onRecordLoadError, and reported during snapshot loading. Documentation reflects the updated behavior.

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

Sequence Diagram(s)

sequenceDiagram
  participant Storage
  participant provideSnapshot
  participant MetadataStrategy
  participant onRecordLoadError
  provideSnapshot->>Storage: Load snapshot record
  Storage-->>provideSnapshot: Return record
  provideSnapshot->>MetadataStrategy: Parse record metadata
  MetadataStrategy-->>provideSnapshot: Return failure detail
  provideSnapshot->>onRecordLoadError: Report StackSnapshotMetadataParseError
  provideSnapshot-->>Storage: Return null

Loading

Possibly related PRs

• daangn/stackflow#734: Introduced the composed strategy functionality extended by this metadata validation work.
• daangn/stackflow#735: Refined the same metadata result-detail and persistence error-reporting workflow.

✨ 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 fix/plugin-stack-persistence-metadata-parse-error

---

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@737.tgz
  

commit: 7625dd4

[cloudflare-workers-and-pages]

Deploying stackflow-demo with    Cloudflare Pages

Latest commit:	af3604c
Status:	⚡️  Build in progress...

View logs

[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	af3604c	Commit Preview URL	Jul 24 2026, 07:05 AM