@principal-ai/subsystems-react 0.55.2 → 0.56.0

package/src/subsystem/stepEmphasis.ts

@@ -0,0 +1,151 @@
+/**
+ * Step emphasis — PROTOTYPE contract for the "guiding focus" augmentation.
+ *
+ * A step emphasis is an authored pointer at a walkthrough step: "look here
+ * first", with optional markdown guidance explaining why. It is deliberately
+ * **not** part of the portable subsystem model and **not** a verification
+ * signal — it belongs in a separate, host-owned augmentation document:
+ *
+ *   `~/.principal/subsystem-model-augmentations/<model-identity>.json`
+ *
+ * The key question this prototype is here to answer is identity: a step has no
+ * id today and steps move. `stepClaimKey` fingerprints the step's *claim*
+ * (`from`/`to`/`mechanism`/site/symbol/span), so a mark survives a reorder but
+ * stops resolving when the claim itself is edited. Orphaned records are kept
+ * (and can be pruned deliberately) rather than silently dropped.
+ *
+ * The mark is a single star rather than a closed kind vocabulary. `guidance`
+ * is markdown so a mark can carry the same kind of prose as a model
+ * description — headings, emphasis, links, code — while staying a string.
+ *
+ * Nothing here is wired to disk yet. The story `Canvases/Subsystem/Step
+ * Emphasis` exercises the shape with an in-memory store and a live JSON view.
+ */
+
+import type { SubsystemTrail, SubsystemTrailStep } from './model';
+
+export interface StepEmphasisProvenance {
+  /** Who authored the mark. Agent marks are expected too. */
+  source: 'author' | 'agent';
+  /** ISO timestamp. */
+  at: string;
+  /** Optional human/agent identity. */
+  author?: string;
+}
+
+/** One mark in the separate augmentation document. */
+export interface StepEmphasisRecord {
+  /** The trail the step belongs to. */
+  trailId: string;
+  /**
+   * Fingerprint of the step's claim (see `stepClaimKey`). Stable across
+   * reorder; changes when the claim changes.
+   */
+  stepKey: string;
+  /** Optional markdown "why look here", rendered like a model description. */
+  guidance?: string;
+  provenance: StepEmphasisProvenance;
+}
+
+/**
+ * The whole separate document. `modelId` is the host-store id (or an identity
+ * key) — this document is host-local and never rides on the portable model.
+ */
+export interface StepEmphasisDocument {
+  version: 1;
+  modelId: string;
+  emphasis: StepEmphasisRecord[];
+}
+
+/**
+ * Lookup key for the UI. `trailId:stepKey` — one flat map is enough for a
+ * graph and keeps the panel from re-deriving a nested structure per render.
+ */
+export type StepEmphasisMap = ReadonlyMap<string, StepEmphasisRecord>;
+
+/** The claim fields a mark is attached to. Deliberately excludes `annotation`. */
+function claimFields(step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>): string[] {
+  return [
+    step.from,
+    step.to,
+    step.mechanism,
+    step.file,
+    step.symbol,
+    step.span?.startLine == null ? '' : String(step.span.startLine),
+    step.span?.endLine == null ? '' : String(step.span.endLine),
+    step.span?.contentHash ?? '',
+  ];
+}
+
+/**
+ * FNV-1a (32-bit) fingerprint. Good enough for a local key: the point is
+ * "same claim => same key", not cryptographic resistance. Swap for SHA-256 at
+ * the store boundary if marks ever travel between hosts.
+ */
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, '0');
+}
+
+/** Stable content key for a step's claim. */
+export function stepClaimKey(
+  step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>,
+): string {
+  return fnv1a(claimFields(step).join('\u001f'));
+}
+
+/** Map key for one step's mark. */
+export function emphasisKey(
+  trailId: string,
+  step: Pick<SubsystemTrailStep, 'from' | 'to' | 'mechanism' | 'file' | 'symbol' | 'span'>,
+): string {
+  return `${trailId}:${stepClaimKey(step)}`;
+}
+
+export function buildStepEmphasisMap(
+  records: readonly StepEmphasisRecord[],
+): StepEmphasisMap {
+  return new Map(records.map((r) => [`${r.trailId}:${r.stepKey}`, r]));
+}
+
+export function findStepEmphasis(
+  map: StepEmphasisMap | undefined,
+  trailId: string,
+  step: SubsystemTrailStep,
+): StepEmphasisRecord | undefined {
+  return map?.get(emphasisKey(trailId, step));
+}
+
+/**
+ * Records whose step claim no longer exists in the current trails. Kept in the
+ * document (so a bad edit does not destroy authored intent) but surfaced so
+ * the author can prune them.
+ */
+export function orphanedEmphasis(
+  records: readonly StepEmphasisRecord[],
+  trails: readonly SubsystemTrail[],
+): StepEmphasisRecord[] {
+  const live = new Set<string>();
+  for (const trail of trails) {
+    for (const step of trail.steps) live.add(emphasisKey(trail.id, step));
+  }
+  return records.filter((r) => !live.has(`${r.trailId}:${r.stepKey}`));
+}
+
+/** Records for one trail, in current step order (for reader surfaces). */
+export function emphasisForTrail(
+  map: StepEmphasisMap | undefined,
+  trail: SubsystemTrail,
+): Array<{ stepIndex: number; step: SubsystemTrailStep; record: StepEmphasisRecord }> {
+  if (!map) return [];
+  const rows: Array<{ stepIndex: number; step: SubsystemTrailStep; record: StepEmphasisRecord }> = [];
+  trail.steps.forEach((step, stepIndex) => {
+    const record = map.get(emphasisKey(trail.id, step));
+    if (record) rows.push({ stepIndex, step, record });
+  });
+  return rows;
+}

package/src/subsystem/trailBrief.test.ts

@@ -38,6 +38,11 @@ describe('buildStepBrief', () => {
     expect(brief).toContain('- symbol: `Login.submit`');
     expect(brief).toContain('- site: `src/ui/login.tsx:42`');
     expect(brief).toContain('- purl: `pkg:github/acme/app`');
+    expect(brief).not.toContain('- site role:');
+  });
+
+  test('marks a non-call site as via evidence', () => {
+    expect(buildStepBrief(trail, 1)).toContain('- site role: `via`');
   });
 
   test('omits the note when the step has no annotation', () => {
@@ -50,6 +55,30 @@ describe('buildStepBrief', () => {
     expect(brief).toContain('- note: session row is written here');
   });
 
+  test('includes resolved site and target constructs when present', () => {
+    const resolved: SubsystemTrail = {
+      ...trail,
+      steps: [
+        {
+          ...trail.steps[0]!,
+          site: {
+            symbol: 'Login.submit',
+            span: { startLine: 30, endLine: 60, contentHash: 'h' },
+          },
+          target: {
+            purl: 'pkg:github/acme/app#src/api/session.ts',
+            file: 'src/api/session.ts',
+            symbol: 'Session.create',
+            span: { startLine: 7, endLine: 7, contentHash: 'h' },
+          },
+        },
+      ],
+    };
+    const brief = buildStepBrief(resolved, 0);
+    expect(brief).toContain('- site construct: `Login.submit` (src/ui/login.tsx:30-60)');
+    expect(brief).toContain('- target: `Session.create` (src/api/session.ts:7)');
+  });
+
   test('returns an empty string for an out-of-range index', () => {
     expect(buildStepBrief(trail, 9)).toBe('');
     expect(buildStepBrief(trail, -1)).toBe('');

package/src/subsystem/trailBrief.ts

@@ -31,12 +31,32 @@ export function buildStepBrief(
   lines.push(`- to: \`${step.to}\``);
   lines.push(`- mechanism: \`${step.mechanism}\``);
   lines.push(`- symbol: \`${step.symbol}\``);
+  // `calls` means the site is the caller frame. Every other mechanism is a
+  // logical hop whose evidence can live in another construct; say so, so an
+  // agent does not treat the site symbol as the source component.
+  if (step.mechanism !== 'calls') {
+    lines.push(`- site role: \`via\``);
+  }
   const site = step.span
     ? step.span.startLine === step.span.endLine
       ? `${step.file}:${step.span.startLine}`
       : `${step.file}:${step.span.startLine}-${step.span.endLine}`
     : step.file;
   lines.push(`- site: \`${site}\``);
+  if (step.site) {
+    const frame = step.site.span.startLine === step.site.span.endLine
+      ? `${step.file}:${step.site.span.startLine}`
+      : `${step.file}:${step.site.span.startLine}-${step.site.span.endLine}`;
+    lines.push(`- site construct: \`${step.site.symbol}\` (${frame})`);
+  }
+  if (step.target) {
+    const targetSpan = step.target.span
+      ? step.target.span.startLine === step.target.span.endLine
+        ? `:${step.target.span.startLine}`
+        : `:${step.target.span.startLine}-${step.target.span.endLine}`
+      : '';
+    lines.push(`- target: \`${step.target.symbol}\` (${step.target.file}${targetSpan})`);
+  }
   lines.push(`- purl: \`${step.purl}\``);
   if (step.annotation != null && step.annotation.length > 0) {
     lines.push(`- note: ${step.annotation}`);

package/src/subsystem/trailStack.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test';
+import type { SubsystemTrail } from './model';
+import { buildTrailStack } from './trailStack';
+
+const trail: SubsystemTrail = {
+  id: 'stack',
+  title: 'Stack',
+  steps: [
+    {
+      from: 'panel',
+      to: 'rpc',
+      mechanism: 'calls',
+      file: 'src/panel.ts',
+      purl: 'pkg:github/acme/app#src/panel.ts',
+      symbol: 'MaintenancePanel',
+      target: {
+        purl: 'pkg:github/acme/app#src/rpc.ts',
+        file: 'src/rpc.ts',
+        symbol: 'getRpc',
+      },
+    },
+    {
+      from: 'rpc',
+      to: 'detail',
+      mechanism: 'calls',
+      file: 'src/rpc.ts',
+      purl: 'pkg:github/acme/app#src/rpc.ts',
+      symbol: 'getRpc',
+      target: {
+        purl: 'pkg:github/acme/app#src/detail.ts',
+        file: 'src/detail.ts',
+        symbol: 'modelDetail',
+      },
+    },
+    {
+      from: 'detail',
+      to: 'touches',
+      mechanism: 'calls',
+      file: 'src/detail.ts',
+      purl: 'pkg:github/acme/app#src/detail.ts',
+      symbol: 'modelDetail',
+      target: {
+        purl: 'pkg:github/acme/app#src/touches.ts',
+        file: 'src/touches.ts',
+        symbol: 'commitTouches',
+      },
+    },
+    {
+      from: 'detail',
+      to: 'remote',
+      mechanism: 'calls',
+      file: 'src/detail.ts',
+      purl: 'pkg:github/acme/app#src/detail.ts',
+      symbol: 'modelDetail',
+      target: {
+        purl: 'pkg:github/acme/app#src/remote.ts',
+        file: 'src/remote.ts',
+        symbol: 'remoteRefSha',
+      },
+    },
+    {
+      from: 'panel',
+      to: 'merge',
+      mechanism: 'uses',
+      file: 'src/list.tsx',
+      purl: 'pkg:github/acme/app#src/list.tsx',
+      symbol: 'ModelList',
+    },
+    {
+      from: 'merge',
+      to: 'dots',
+      mechanism: 'feeds',
+      file: 'src/dots.tsx',
+      purl: 'pkg:github/acme/app#src/dots.tsx',
+      symbol: 'CommitDots',
+    },
+  ],
+};
+
+describe('buildTrailStack', () => {
+  test('builds the caller chain for a nested call', () => {
+    const stack = buildTrailStack(trail, 2);
+    expect(stack.isCall).toBe(true);
+    expect(stack.frames.map((f) => f.label)).toEqual([
+      'MaintenancePanel',
+      'getRpc',
+      'modelDetail',
+    ]);
+    expect(stack.frames.map((f) => f.current)).toEqual([false, false, true]);
+    expect(stack.callee).toBe('commitTouches');
+  });
+
+  test('a sibling call links to the shared parent, not the previous sibling', () => {
+    const stack = buildTrailStack(trail, 3);
+    expect(stack.frames.map((f) => f.stepIndex)).toEqual([0, 1, 3]);
+    expect(stack.frames.map((f) => f.label)).toEqual([
+      'MaintenancePanel',
+      'getRpc',
+      'modelDetail',
+    ]);
+    expect(stack.callee).toBe('remoteRefSha');
+  });
+
+  test('uses is an annotation on the frame it belongs to, not a frame', () => {
+    const stack = buildTrailStack(trail, 4);
+    expect(stack.isCall).toBe(false);
+    expect(stack.frames.map((f) => f.label)).toEqual(['MaintenancePanel']);
+    expect(stack.annotations).toEqual([
+      { stepIndex: 4, mechanism: 'uses', label: 'uses merge', selected: true },
+    ]);
+  });
+
+  test('a root call still shows its caller frame and callee', () => {
+    const stack = buildTrailStack(trail, 0);
+    expect(stack.frames.map((f) => f.label)).toEqual(['MaintenancePanel']);
+    expect(stack.callee).toBe('getRpc');
+  });
+
+  test('a non-call step with no call context falls back to its source frame', () => {
+    const stack = buildTrailStack(trail, 5);
+    expect(stack.isCall).toBe(false);
+    expect(stack.frames.map((f) => f.label)).toEqual(['CommitDots']);
+    expect(stack.annotations[0]?.label).toBe('feeds dots');
+  });
+
+  test('out-of-range returns an empty view', () => {
+    expect(buildTrailStack(trail, 99)).toEqual({
+      frames: [],
+      annotations: [],
+      isCall: false,
+    });
+  });
+});

package/src/subsystem/trailStack.ts

@@ -0,0 +1,229 @@
+/**
+ * Derive a call stack for one trail step.
+ *
+ * A trail is a timeline, not a stack frame dump: steps can return to an
+ * ancestor, take sibling calls, or describe a non-call seam (`uses`, `feeds`,
+ * …). This module links each `calls` step to the prior call that entered its
+ * caller construct, then renders that ancestry as a stack. Non-call steps are
+ * annotations on the nearest frame — they are not frames.
+ *
+ * The links use the resolved `site`/`target` when present, falling back to the
+ * component aliases. That keeps the view useful before every step has its
+ * construct refs captured.
+ */
+
+import type {
+  SubsystemTrail,
+  SubsystemTrailMechanism,
+  SubsystemTrailStep,
+} from './model';
+import {
+  trailComponentLabel,
+  type TrailComponentLabels,
+} from './trailStepDisplay';
+
+export interface TrailStackFrame {
+  /** The step whose call creates this frame. */
+  stepIndex: number;
+  /** Frame label — the caller construct, or the component alias. */
+  label: string;
+  /** Component alias of the caller (for focus/selection wiring). */
+  componentAlias: string;
+  /** The selected step's own frame (innermost). */
+  current: boolean;
+}
+
+export interface TrailStackAnnotation {
+  /** Non-call step attached to the current frame. */
+  stepIndex: number;
+  mechanism: SubsystemTrailMechanism;
+  label: string;
+  /** The selected step itself (vs context around it). */
+  selected: boolean;
+}
+
+export interface TrailStackView {
+  /** Outermost → innermost. Empty only for an out-of-range index. */
+  frames: TrailStackFrame[];
+  /** Non-call seams attached to the current frame. */
+  annotations: TrailStackAnnotation[];
+  /** True when the selected step is a call frame. */
+  isCall: boolean;
+  /** The selected call's target, shown as the next frame-to-be. */
+  callee?: string;
+}
+
+function callerSymbol(step: SubsystemTrailStep): string {
+  return step.site?.symbol?.trim() || step.symbol?.trim() || step.from;
+}
+
+function calleeSymbol(step: SubsystemTrailStep): string {
+  return step.target?.symbol?.trim() || step.to;
+}
+
+function callerLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return callerSymbol(step) || trailComponentLabel(step.from, byAlias);
+}
+
+function calleeLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+}
+
+function isCallStep(step: SubsystemTrailStep | undefined): boolean {
+  return step?.mechanism === 'calls';
+}
+
+/** Does call `a` lead into the caller of call `b`? */
+function leadsInto(a: SubsystemTrailStep, b: SubsystemTrailStep): boolean {
+  return a.to === b.from || calleeSymbol(a) === callerSymbol(b);
+}
+
+/** The nearest earlier call that entered this step's caller frame. */
+function parentCallIndex(
+  trail: SubsystemTrail,
+  stepIndex: number,
+): number | null {
+  const child = trail.steps[stepIndex];
+  if (!child) return null;
+  for (let i = stepIndex - 1; i >= 0; i--) {
+    const candidate = trail.steps[i];
+    if (!isCallStep(candidate)) continue;
+    if (leadsInto(candidate!, child)) return i;
+  }
+  return null;
+}
+
+/** The call chain ending at `stepIndex`, outermost first. */
+function callChain(trail: SubsystemTrail, stepIndex: number): number[] {
+  const chain: number[] = [];
+  const seen = new Set<number>();
+  let cursor: number | null = stepIndex;
+  while (cursor != null && !seen.has(cursor)) {
+    seen.add(cursor);
+    chain.unshift(cursor);
+    cursor = parentCallIndex(trail, cursor);
+  }
+  return chain;
+}
+
+function framesForChain(
+  trail: SubsystemTrail,
+  chain: number[],
+  selectedStepIndex: number | null,
+  byAlias?: TrailComponentLabels,
+): TrailStackFrame[] {
+  return chain.map((idx) => {
+    const step = trail.steps[idx]!;
+    return {
+      stepIndex: idx,
+      label: callerLabel(step, byAlias),
+      componentAlias: step.from,
+      current: idx === selectedStepIndex,
+    };
+  });
+}
+
+/**
+ * The nearest earlier call that shares this non-call step's source component.
+ * `uses`/`feeds`/… are dependencies of that frame, not new frames.
+ */
+function anchorCallIndex(
+  trail: SubsystemTrail,
+  stepIndex: number,
+): number | null {
+  const step = trail.steps[stepIndex];
+  if (!step) return null;
+  const source = callerSymbol(step);
+  for (let i = stepIndex - 1; i >= 0; i--) {
+    const candidate = trail.steps[i];
+    if (!isCallStep(candidate)) continue;
+    if (
+      candidate!.from === step.from ||
+      candidate!.to === step.from ||
+      callerSymbol(candidate!) === source ||
+      calleeSymbol(candidate!) === source
+    ) {
+      return i;
+    }
+  }
+  return null;
+}
+
+function annotationLabel(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): string {
+  return `${step.mechanism} ${calleeLabel(step, byAlias)}`;
+}
+
+/**
+ * Build the stack at one trail step.
+ *
+ * - `calls` → the chain of calls into the caller frame, plus the callee as the
+ *   next frame (not yet on the stack).
+ * - `uses` / data + event seams → the nearest call frame they attach to, with
+ *   the seam as an annotation.
+ */
+export function buildTrailStack(
+  trail: SubsystemTrail,
+  stepIndex: number,
+  byAlias?: TrailComponentLabels,
+): TrailStackView {
+  const step = trail.steps[stepIndex];
+  if (!step) {
+    return { frames: [], annotations: [], isCall: false };
+  }
+
+  if (isCallStep(step)) {
+    const chain = callChain(trail, stepIndex);
+    return {
+      frames: framesForChain(trail, chain, stepIndex, byAlias),
+      annotations: [],
+      isCall: true,
+      callee: calleeLabel(step, byAlias),
+    };
+  }
+
+  const anchor = anchorCallIndex(trail, stepIndex);
+  if (anchor != null) {
+    const chain = callChain(trail, anchor);
+    return {
+      frames: framesForChain(trail, chain, anchor, byAlias),
+      annotations: [
+        {
+          stepIndex,
+          mechanism: step.mechanism,
+          label: annotationLabel(step, byAlias),
+          selected: true,
+        },
+      ],
+      isCall: false,
+    };
+  }
+
+  return {
+    frames: [
+      {
+        stepIndex,
+        label: callerLabel(step, byAlias),
+        componentAlias: step.from,
+        current: true,
+      },
+    ],
+    annotations: [
+      {
+        stepIndex,
+        mechanism: step.mechanism,
+        label: annotationLabel(step, byAlias),
+        selected: true,
+      },
+    ],
+    isCall: false,
+  };
+}

package/src/subsystem/trailStepDisplay.ts

@@ -0,0 +1,68 @@
+/**
+ * How a trail step reads in the Trails panel.
+ *
+ * A step is one seam, but the panel shows the logical hop and the site in a
+ * single wrapping line:
+ *
+ * - `calls` — the caller frame (the site construct).
+ * - `uses` — `from uses to`, where `to` is the precise target when resolved.
+ * - Everything else — `from mechanism to`.
+ *
+ * The evidence site lives in the code view and the stack breadcrumb; the
+ * sidebar row stays one line so it can wrap instead of truncating.
+ */
+
+import type { SubsystemTrailStep, SubsystemTrailMechanism } from './model';
+
+/** The slice of a component the labels need — keeps fixtures light. */
+export interface TrailComponentLabelSource {
+  alias: string;
+  name?: string;
+  symbol?: string;
+}
+
+/** Alias → component, for turning model-local aliases into display names. */
+export type TrailComponentLabels = ReadonlyMap<string, TrailComponentLabelSource>;
+
+/** One row's primary text. */
+export interface TrailStepDisplay {
+  mechanism: SubsystemTrailMechanism;
+  /** The line that names the step: caller frame for `calls`, hop otherwise. */
+  primary: string;
+}
+
+/** Display label for a component alias; falls back to the alias. */
+export function trailComponentLabel(
+  alias: string,
+  byAlias?: TrailComponentLabels,
+): string {
+  const component = byAlias?.get(alias);
+  const label = component?.name?.trim() || component?.symbol?.trim();
+  return label || alias;
+}
+
+/**
+ * Build the single display line for one step.
+ *
+ * The resolved target (`step.target.symbol`) is the precise callee, while `to`
+ * is only a component alias and can be a whole class/store. Prefer the target.
+ */
+export function trailStepDisplay(
+  step: SubsystemTrailStep,
+  byAlias?: TrailComponentLabels,
+): TrailStepDisplay {
+  const from = trailComponentLabel(step.from, byAlias);
+  const to = step.target?.symbol?.trim() || trailComponentLabel(step.to, byAlias);
+  const siteSymbol = step.site?.symbol?.trim() || step.symbol?.trim() || from;
+
+  if (step.mechanism === 'calls') {
+    return { mechanism: step.mechanism, primary: siteSymbol };
+  }
+  if (step.mechanism === 'uses') {
+    return { mechanism: step.mechanism, primary: `${from} uses ${to}` };
+  }
+  return {
+    mechanism: step.mechanism,
+    primary: `${from} ${step.mechanism} ${to}`,
+  };
+}