@miadi/plan-insight

Capability-injected plan interpretation plus relational carriage for existing Miette perspective files.

@miadi/plan-insight receives a plan plus provenance, requires real perspective, chart, trace, and memory capabilities, runs them in order, and returns deterministic artifact wrappers together with a validated miadi.miette.perspective.ready event.

It also projects an existing session perspective into a bounded PerspectiveRecord and can register that projection with medicine-wheel. The package carries prose; it never generates prose.

Install

npm install @miadi/plan-insight

Boundary

This package owns:

• validating the minimum plan-insight request;
• deterministic run and artifact IDs;
• required-capability preflight;
• ordered perspective → chart → trace → memory orchestration;
• typed, stage-specific failures;
• hooks-core perspective discovery and ready-event composition.
• the additive PerspectiveRecord projection contract;
• lenient narrative parsing with a 64 KiB Markdown boundary;
• zero-to-many episode relation normalization;
• dry-run and injectable medicine-wheel registration;
• the plan-insight-register carriage-only CLI.

The injected capabilities own interpretation and orchestration side effects. The perspective generator owns miette_perspective.md. This package does not generate Mia/Miette prose, create structural-tension charts, contact tracing services, write memory, call an LLM, use SSH, or load credentials.

The existing Next.js route at app/api/session/plan-insight is a future consumer. It is not this package's transport or runtime boundary.

Perspective carriage

plan-insight-register \
  --session /a/src/_sessiondata/<session-id> \
  --episode 2026-07-15-episode-130-example \
  --dry-run

--session accepts an existing directory or a session id resolved under $MIADI_SESSIONDATA_ROOT (default /a/src/_sessiondata). Repeat --episode for every related episode; $MIADI_EPISODE_KEY supplies one default relation when no flag is present.

Without --dry-run, the command posts to POST {MW_API_URL}/api/plan-perspectives. Re-registration uses plan-perspective:<session_id> and medicine-wheel unions episode paths. A network or upstream failure exits 1 with the session files unchanged.

Lineage carries _claude_user_inputs.jsonl by path, count, and available timestamps. Prompt excerpts do not cross the network unless --with-excerpts is explicit; included excerpts are bounded.

The generator-to-carrier handoff remains a host integration concern:

plan-insight-register --session "$session_folder" ||
  echo "Perspective registration failed; generated file remains authoritative."

That invocation belongs after the generator has verified $session_folder/plans/miette_perspective.md. It is deliberately non-fatal to successful generation.

The three-spec workstream is anchored by jgwill/Miadi#483:

• rispecs/plan-perspective-registration.spec.md
• jgwill/medicine-wheel:rispecs/plan-insight-perspective-registration.spec.md
• miadisabelle/forgewright:rispecs/10-plan-perspective-visibility.spec.md

Required capabilities

import { runPlanInsight } from "@miadi/plan-insight"

const result = await runPlanInsight(input, {
  perspective: perspectiveProvider,
  chart: chartProvider,
  trace: traceProvider,
  memory: memoryProvider,
})

All four capabilities must be own data properties. Missing capabilities fail before any capability runs. Accessor registries, malformed outputs, provider failures, and hooks-core contract failures produce PlanInsightError with an explicit code and stage.

Each capability receives the caller's plan/provenance context and deterministic IDs. Provider references remain available as externalId; provider provenance remains attached to its artifact.

hooks-core reuse

The package consumes @miadi/[email protected] rather than redefining:

• deriveIdempotencyKey;
• discoverPlanPerspectives;
• perspectiveReadyEventFromRecord;
• validatePlanReviewEvent;
• planReviewIdempotencyKey;
• plan provenance, source, perspective record, and ready-event types.

Use discoverPlanInsightPerspectives(root, options) when a consumer needs existing session perspectives lifted into deterministic, validated ready events.

Memory contract

The memory capability returns EpisodicMemory from @miadi/[email protected]. In this CommonJS release that package is consumed as a type-only dependency; no CommonJS runtime import of its ESM entrypoint is emitted.

Plan Insight does not consume or duplicate EpisodeObservation, and it does not perform Chronicle promotion.

Provenance and determinism

The caller supplies timestamps and provenance. IDs derive from hooks-core's stable idempotency function over the plan, episode key, source, and provenance. The package does not call the clock or generate random IDs.

Capability artifacts receive deterministic package IDs while real provider/service IDs are preserved separately as externalId.

Each capability receives an isolated snapshot of the canonical request and prepared IDs. Provider mutation cannot rewrite the provenance or deterministic IDs used for later stages, events, or the final result.

Non-goals for 0.2.0

• HTTP routes or job storage
• provider implementations
• fake or deterministic substitute interpretations
• generation of perspective prose
• Passages integration
• medicine-wheel storage implementation
• ForgeWright rendering implementation
• LLM, MCP server, Langfuse, or credential wiring

Episode 128 next cycle

Episode 128 adds evidence for the package's outer lifecycle: two distinct agent sessions, a durable-worker need, independent producer/permission states, partial external outcomes, and the first live Salix-to-Chronicle contribution lane.

The focused implementation-and-publication recommendation is in rispecs/episode-128-next-cycle.spec.md. It preserves this package as a pure provider-neutral contract; filesystem drops, Herdr, Telegram, R2, Chronicle commits, and credentials remain adapter/runtime responsibilities.

Delivered in 0.3.0 (jgwill/Miadi#485, anchor jgwill/Miadi#484)

The spec targeted 0.2.0, but 0.2.0 shipped the PerspectiveRecord/carriage slice first; these contracts therefore land as 0.3.0, in src/run.ts:

• RunManifest (miadi.plan-insight.run/v1) + validateRunManifest — source and producer identity kept distinct, source-bytes and stored-artifact hashes carried separately, declared side effects, fail-closed schema/version errors.
• Four independent state axes — producer_phase, plan_permission (type shared with @miadi/hooks-core), review_delivery, implementation_authorization. runManifestAuthorizesImplementation is the only reading of authorization; Episode 128's real end state (completed + requested) authorizes nothing.
• Typed partial artifact outcomes — perspective verified while chart/trace stay unverified is the Episode 128 fixture, not an edge case.
• mapLegacyExitPlanRun — Episode 128's miette.exit-plan-run/v1 fails direct validation with a schema/version error and enters only through this mapper, which retains the original manifest hash as evidence and surfaces the launch_argv_redacted decision as a warning.
• ContributionReceipt + validator + mergeContributionReceipts — the live Salix→Chronicle lane, typed: contributor, relationship, drop state (draft/ready/superseded/witnessed), artifact hash/bytes, witness commit. The package validates receipts; it never writes or commits Chronicle files.

Credit: Jerry (G.Music) and Salix, whose Episode 128 cycle — chronicled in miadi-chronicle/2026-07-13-episode-128-gmtermux-cloudflare-r2-jerry-miette-plan-insight — supplied every fixture value in test/run.test.ts verbatim.

Development

npm test
npm run type-check
npm run build
npm pack --dry-run

TDD-EVIDENCE.md records the red/green sequence used for each 0.1.0 behavior.