hoist gather/pull semantics into ghost-core for embedded consumers#220
Closed
nahiyankhan wants to merge 1 commit into
Closed
hoist gather/pull semantics into ghost-core for embedded consumers#220nahiyankhan wants to merge 1 commit into
nahiyankhan wants to merge 1 commit into
Conversation
…host-core
Governed hosts embedding Ghost as a library (e.g. Summon) previously
mirrored CLI-internal behavior and drifted. Move the semantics down a
layer so embedders consume them instead of reimplementing them:
- buildGatherMenu(catalog, { includeWild }) in ghost-core returns
{ entries, wildAvailable, wildIncluded } — the gather menu with the
wild-posture gate as a pure function; the gather command consumes it
- orderPulledNodes / steeringBucket (steering order: index → concrete →
steady/wild → guard, stable within bucket) exported from ghost-core;
the pull command consumes them
- observability event types + pure stampGhostEvent exported from
./fingerprint so embedders can record tape-shaped events in their own
receipts without writing into a fingerprint package directory
- LoadedCheck exported from ./fingerprint
- #ghost-core / #scan types conditions repointed at shipped dist/
declarations instead of unshipped src/
- docs/embedded-consumers.md: the contract page naming which behaviors
are semantics every consumer must honor vs CLI presentation
CLI output is bit-identical; tests cover the new exports.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Category: new-feature
User Impact: Hosts that embed Ghost as a library can now consume gather/pull semantics directly instead of re-implementing CLI behavior.
Problem: Governed hosts (UI-generation servers, review-orchestration services) that embed Ghost had to mirror command code to reproduce the wild-posture gate, steering order, and event shapes, risking drift from the CLI's load-bearing semantics.
Solution: Hoist those semantics into ghost-core as pure functions (
buildGatherMenu,orderPulledNodes,steeringBucket), export observability event types andstampGhostEventfrom./fingerprint, and document the embedded-consumer contract so the CLI becomes one transport for the semantics rather than their source of truth.Validation:
pnpm build: passpnpm test: 154 passed, 1 skipped (16 files)pnpm check: pass (biome, typecheck, file-size, terminology, CLI manifest in sync)Changeset: added (
.changeset/embedded-consumer-contract.md, minor)Ghost Review:
ghost check/ghost review: not run because this repo has no root.ghost/fingerprint package (ghost validatereports manifest.yml missing).File changes
.changeset/embedded-consumer-contract.md
Minor changeset describing the new library surface.
docs/embedded-consumers.md
New contract page naming which behaviors are semantics every consumer must honor (wild-posture gate, steering order, checks-as-review-only, index front door, skeleton extraction) vs. CLI presentation, with a minimal consumption sketch and a "must not" list.
packages/ghost/package.json
#ghost-core/#scanimporttypesconditions now point at shippeddist/declarations instead of unshippedsrc/, so embedders get types from the packed artifact.packages/ghost/src/ghost-core/catalog/menu.ts
Adds
buildGatherMenu(catalog, { includeWild })returning{ entries, wildAvailable, wildIncluded }— the gather menu semantics as a pure function.packages/ghost/src/ghost-core/catalog/steering.ts
New home for
orderPulledNodes/steeringBucket(index → concrete → steady/wild → guard, stable within bucket), hoisted out of the pull command.packages/ghost/src/ghost-core/catalog/index.ts, packages/ghost/src/ghost-core/index.ts
Re-export the new menu and steering functions and types from ghost-core.
packages/ghost/src/commands/gather-command.ts
CLI now consumes
buildGatherMenuinstead of computing wild counts and inclusion flags inline.packages/ghost/src/commands/pull-command.ts
CLI now imports
orderPulledNodesfrom ghost-core; local copies removed.packages/ghost/src/observability-events.ts
Doc comments clarifying that library consumers may construct these event shapes for their own telemetry but must never write into a fingerprint package directory.
packages/ghost/src/fingerprint.ts
Exports observability event types (
GatherObservabilityEvent,PullObservabilityEvent,PullMiss,GhostObservabilityEvent,NewGhostObservabilityEvent), the purestampGhostEventhelper, andLoadedCheck.packages/ghost/test/ghost-core/catalog-menu.test.ts
Tests for
buildGatherMenusemantics: wild gate, discoverability count, inclusion flag.packages/ghost/test/observability-events.test.ts
Tests for
stampGhostEventand exported event shapes.Screenshots/Demos: N/A