Add structural-history Echo package descriptor

[flyingrobots]

Summary

• Add a deterministic structural-history Echo package descriptor derived from the schema authority manifest and package identity
• Add a Graft-local descriptor drift checker and wire it into pnpm schema:structural-history:check
• Add focused contract tests and a design packet documenting why this slice requires no Echo runtime change

Echo impact

No Echo repo changes are required. This slice only records the package facts Graft expects to hand to Echo later; it does not install a package, invoke Echo storage, or require a TypeScript Echo client.

Validation

Not run locally. CI and git hooks cover this branch.

Summary by CodeRabbit

Release Notes

• Chores

  • Implemented automated validation tooling for structural history schema package descriptors to ensure configuration consistency and prevent descriptor drift between expected and actual configurations.

• Tests

  • Added comprehensive test coverage for schema descriptor validation, verifying deterministic generation, boundary configuration, and mismatch detection.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b21627c8-b432-4ce1-8c21-30f6143bcfb8

📥 Commits

Reviewing files that changed from the base of the PR and between c03c818 and 5bd5e32.

⛔ Files ignored due to path filters (3)

• CHANGELOG.md is excluded by !**/*.md
• docs/design/CORE_graft-structural-history-echo-package-descriptor.md is excluded by !**/*.md
• docs/method/backlog/asap/CORE_graft-structural-history-echo-package-descriptor.md is excluded by !**/*.md

📒 Files selected for processing (4)

• package.json
• schemas/graft-structural-history.echo-package.json
• scripts/check-structural-history-echo-package.ts
• test/unit/contracts/graft-structural-history-echo-package.test.ts

---

📝 Walkthrough

Walkthrough

This PR introduces a deterministic validator for the Echo structural-history package descriptor. It defines the descriptor JSON file, implements a CLI checker that validates descriptor consistency against schema manifests, includes path-validation logic, and adds comprehensive test coverage with npm script integration.

Changes

Echo Descriptor Validation

Layer / File(s)	Summary
Echo Descriptor & Validation Contract schemas/graft-structural-history.echo-package.json, scripts/check-structural-history-echo-package.ts (types/constants)	Defines the Echo package descriptor JSON with package identity, schema/artifact hashes and paths, runtime configuration, and contract surface. TypeScript interfaces and constants specify the expected descriptor shape.
Echo Package Descriptor Checker Implementation scripts/check-structural-history-echo-package.ts (manifest reading, descriptor construction, validation, CLI), package.json	Reads graft package and schema manifests, deterministically constructs the expected descriptor, validates path structure (repo-root-relative POSIX, no .. traversal), performs byte-for-byte comparison, and reports violations. Integrated into schema:structural-history:check npm script.
Echo Package Descriptor Validation Tests test/unit/contracts/graft-structural-history-echo-package.test.ts	Tests deterministic descriptor derivation with zero violations, validates descriptor structure and path constraints, detects descriptor version drift, and manages temporary workspace fixtures.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• flyingrobots/graft#62: Modifies the check-structural-history-schema-artifacts.ts script that is executed before the new echo-package check in the schema:structural-history:check npm script.

Poem

🐇 A descriptor springs to life so bright,
With paths that point both wrong and right,
We validate each echo's call—
A rabbit checks it all, for all! 🌙

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and directly describes the main change: adding a structural-history Echo package descriptor, which is the primary purpose reflected across all modified and new files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 cycle/CORE_graft-structural-history-echo-package-descriptor

---

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 and usage tips.}

[flyingrobots]

@codex Code Lawyer self-audit found one blocking issue before merge.

Severity	Source	File	Lines	Issue	Mitigation
P1	CI/Self	scripts/check-structural-history-echo-package.ts	L162	@typescript-eslint/restrict-template-expressions rejects interpolating the numeric index directly into a template literal, causing Node 20 CI lint to fail.	Convert index to a string before interpolation, then rerun the relevant lint gate.

[flyingrobots]

Code Lawyer Activity Summary

Item	Severity	Source	File	Commit	Outcome
Numeric template literal violated lint policy	P1	CI/Self	scripts/check-structural-history-echo-package.ts	5bd5e321	Fixed by stringifying the flatMap index before interpolation; pnpm lint passed locally.

Merge gate remains dependent on refreshed CI for commit 5bd5e321 and CodeRabbit cooldown state.