@mrciphersmith/keryx 0.2.69 → 0.2.71

package/docs/README.md

@@ -0,0 +1,54 @@
+# Documentation
+
+This directory separates documentation by purpose so current behavior, product
+intent, implementation plans, and release evidence do not get mixed together.
+
+## Current behavior
+
+- [Developer documentation](docs/README.md) — entry point for setup,
+  architecture, modules, CLI behavior, and workspace lifecycle.
+- [Complete setup and agent workflows](docs/complete-setup-and-agent-workflows.md)
+  — global installation, project configuration, command reference, scripts, and
+  copy-ready agent prompts.
+- [Agent installation playbook](docs/agent-installation-playbook.md) — autonomous
+  Gherkin scenarios for complete setup, validation, repair, and handoff.
+- [Documentation index](docs/index.md) — compact navigation for the generated
+  current-behavior reference.
+
+## Product intent
+
+- [Requirements roadmap](requirements/roadmap.md) — requirements packages and
+  their verified implementation state.
+- [Managed Review Feedback Loop](requirements/managed-review-feedback-loop/README.md)
+  — requirements and contracts for managed review packages.
+- [Keryx Memory Reliability](requirements/keryx-memory-reliability/README.md)
+  — corrective requirements and implementation tracking for side-effect-free
+  recall, accepted-only agent influence, durable lifecycle, and generated data.
+
+## Plans and reports
+
+- [Shared Agent Context Improvements Program](requirements/shared-agent-context-improvements-program/README.md)
+  — dependency-ordered implementation waves for twelve SAC improvement
+  packages, with copy-ready phase prompts, evidence gates, rollback, and a
+  live progress/statistics dashboard.
+- [Keryx Improvements 1 — SAC, memory, and orchestration analysis](analysis/keryx-improvements-1/2026-08-14/report/en/report.md)
+  — integrated audit of Shared Agent Context and its Context Operations, Flow,
+  Harness/session, MCP, Security, knowledge-owner, worktree, and policy seams;
+  includes twelve independently deliverable future requirement packages.
+- [Implementation plans](plans/) — bounded plans that may become cleanup
+  candidates after their acceptance criteria are implemented and verified.
+- [Release readiness — 2026-07-10](report/release-readiness-2026-07-10/release-readiness.md)
+  — verification results, release blockers, and the prioritized cleanup plan.
+- [Implementation spec](report/release-readiness-2026-07-10/implementation-spec.md)
+  — approved scope and acceptance criteria for this documentation pass.
+
+## Documentation policy
+
+- Repository documentation is English-only.
+- `docs/docs/` describes current behavior and must be verified against source or
+  live CLI help.
+- `docs/requirements/` describes intended behavior and must label implementation
+  status explicitly.
+- Generated `.metaproject` artifacts are refreshed through the project CLI; raw
+  and reproducible outputs remain ignored according to the managed `.gitignore`
+  policy.

package/docs/requirements/shared-agent-context/README.md

@@ -0,0 +1,104 @@
+# Keryx Shared Agent Context
+Version: 1.5.0
+
+## Назначение
+
+Этот пакет описывает **текущий** local-first слой совместного контекста Keryx
+(`src/sac/`, CLI `keryx workspace`, MCP `sac.*`, harness `workspace_*`).
+Он даёт человеку и агенту воспроизводимый вход в работу от workspace, компонента
+или flow: небольшой проверяемый обзор, адресное чтение деталей и безопасное
+предложение нового знания по завершении работы.
+
+## Статус
+
+`implemented` (механизмы 0–5), плюс фаза 6, разбитая на две части: **6a** —
+runtime-guard opt-in (`resolvePolicySelection`), реализована и проверена
+(AC1–AC6, вся SAC-сюита 88/88 зелёная); **6b** — операторский процесс готовности
+для реальных данных, частично (read-only `keryx workspace policy-readiness` и
+playbook; runtime re-ingestion сырых receipts/outcomes остаётся). Фазы 0–5 и 6a
+влиты в `main` и выпущены в `v0.2.32`; код lifecycle/CLI/MCP/harness с тех пор
+расширен на `main` (в т.ч. `v0.2.35`). Точный статус и evidence приведены в
+[Implementation plan](implementation-plan.md).
+
+**Документационная правда (1.5.0):** более ранние versioned-заголовки этого
+пакета помечали CLI/MCP/schema-enforcement как `future/planned` и прямо писали,
+что runtime «не реализует SAC contracts». Это устарело относительно `src/sac/`
+(~4.3k строк production + тесты: propose/review/accept, guarded owner-writers
+wiki/memory/skill, receipt-integrity, access-receipt ledger; плюс
+`src/commands/workspace.ts`, MCP `sac.*`, harness `workspace_*`). Норматив
+этого пакета теперь —
+как устроено **сейчас**. Спутниковые пакеты RP-01…RP-12 остаются future /
+spec-ready и **не** отменяют этот runtime. Валидатор, который сверяется с
+заголовками `future` в старых ревизиях или в RP-пакетах, получит ложный drift.
+
+Важно: Phase 5 (policy experiment) сейчас подтверждает корректность механизма на
+synthetic offline evidence и по умолчанию не включает production эффектов.
+
+## Модель FWK
+
+- **Facts** — evidence-linked, task-local и freshness-bound утверждения о
+  текущей работе. Fact не становится источником долгосрочного знания.
+- **Work** — read-only проекция существующего Flow: выполненное, следующее,
+  блокировки и verification evidence. SAC никогда не создаёт второй tracker.
+- **Know-how** — reviewed и reusable knowledge из memory, wiki и skills.
+  Необработанные транскрипты и скрытые рассуждения не являются Know-how.
+
+## Документы
+
+- [PRD](prd.md) — проблема, пользователи, требования, риски и результаты.
+- [Specification](specification.md) — границы, функциональная surface,
+  интеграции и acceptance criteria.
+- [Agent protocol](agent-protocol.md) — обязательное поведение агента при
+  read, wrap-up и proposal lifecycle.
+- [Artifact lifecycle](artifact-lifecycle.md) — источники истины, freshness,
+  retention, supersession и deletion policy.
+- [Metrics and validation](metrics-and-validation.md) — baseline, evals,
+  rollout/rollback и измеримые gates.
+- [Implementation plan](implementation-plan.md) — delivery status фаз 0–6b
+  и исторические exit criteria.
+- [Phase execution prompts](phase-execution-prompts.md) — утверждённые промты
+  для запуска и delivery-protocol каждой implementation phase.
+- [Phase 4 usability report](phase-4-usability-report.md) — contract-only
+  walkthrough evidence.
+- [Phase 5 policy experiment report](phase-5-policy-experiment-report.md) —
+  synthetic offline experiment evidence.
+- [Phase 6 readiness](phase-6-real-opt-in-readiness.md) — 6a/6b split and
+  remaining real-data work.
+- [Phase 6b operator playbook](phase-6b-operator-playbook.md) — operator
+  readiness process.
+- [Design rationale](design-rationale.md) — решения и ограничения модели FWK.
+- [Schemas](schemas/README.md) — JSON Schema, semantic-validation boundary и
+  полный positive/negative/replay fixture corpus.
+
+## Scope
+
+- Локальный workspace registry со ссылками на компоненты, repositories, flows,
+  evidence и approved knowledge; исходные артефакты не копируются.
+- Bounded FWK overview и progressive retrieval через **существующие** CLI
+  (`keryx workspace overview|read`), MCP (`sac.overview`/`sac.read`, только
+  local stdio) и harness-tools (`workspace_overview`/`workspace_read`);
+  hash-chained access-receipt ledger.
+- Evidence-linked session wrap-up, proposal queue, human review и guarded
+  promotion в существующие wiki/memory paths.
+- Freshness, least disclosure, trusted ActorContext, local roles, redaction и
+  audit trail; proposal может быть принят только после проверяемого,
+  append-only review transition.
+
+## Non-goals
+
+- Новый task manager, дубликат Flow или новый primary store для wiki/memory.
+- Хранение raw transcripts, secrets, PII, hidden reasoning или unrestricted
+  environment snapshots как knowledge.
+- Обязательная облачная база, multi-tenant service, SSO или внешний catalog.
+- UI/IDE/terminal shell как prerequisite первой поставки.
+- Обучаемая или self-modifying access policy до воспроизводимых offline evals.
+
+## Связанные модули
+
+- [Keryx Context Operations](../keryx-context-operations/2026-07-12/README.md)
+  — владелец context assembly, retrieval trace и feedback lifecycle.
+- [Keryx Project Agent Harness](../keryx-project-agent-harness/README.md) —
+  владелец сессий, approvals, worktrees и execution runtime.
+- `src/flow`, `src/memory`, `src/wiki`, `src/gdgraph`, `src/mcp`,
+  `src/security`, `src/ctx`, `src/harness` — существующие интеграционные
+  границы; изменения в них требуют отдельных implementation flows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.69",
+  "version": "0.2.71",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -41,6 +41,7 @@
     "test": "bun test",
     "check": "tsc --noEmit && bun test",
     "check:doc-links": "bun scripts/check-doc-links.ts",
+    "baseline:review-precision": "bun scripts/review-precision-baseline.ts",
     "test:guards": "bun test src/lib/config-dir.ast.test.ts src/lib/config-dir.readers.test.ts src/lib/production-graph.test.ts src/harness/policy/profiles.test.ts src/lib/serve-server.test.ts"
   },
   "files": [
@@ -72,4 +73,4 @@
     "protobufjs",
     "sharp"
   ]
-}
+}

package/src/gdgraph/build-lang.test.ts

@@ -188,6 +188,13 @@ test("buildGraph resolves Python absolute, relative, and __init__.py imports", a
 // !!! NEVER regenerate these goldens to make a diff disappear. If this test
 // !!! fails, the TS/JS code path changed and AC4 is violated — fix the code,
 // !!! not the golden.
+//
+// EXCEPTION, recorded rather than silently applied: flow 140 (P1 — dynamic
+// imports counted as load-order cycles) intentionally adds an `importKind`
+// field to every edge record, TS/JS included — the whole point of that flow
+// is that the field was missing. That is a deliberate schema change, not a
+// TS/JS behavior drift from Java/Python work, so the AC4 invariant above
+// still holds; only the pinned literal needed the new field appended.
 // ---------------------------------------------------------------------------
 
 const GOLDEN_NODES_JSONL =
@@ -197,9 +204,9 @@ const GOLDEN_NODES_JSONL =
   `{"id":"src/feature/value.ts","kind":"file","path":"src/feature/value.ts","language":"typescript"}\n`;
 
 const GOLDEN_EDGES_JSONL =
-  `{"id":"edge:1","from":"src/feature/helper.js","to":"src/feature/value.ts","kind":"imports","specifier":"./value"}\n` +
-  `{"id":"edge:2","from":"src/feature/index.ts","to":"src/feature/style.css","kind":"asset","specifier":"./style.css"}\n` +
-  `{"id":"edge:3","from":"src/feature/index.ts","to":"src/feature/value.ts","kind":"imports","specifier":"./value"}\n`;
+  `{"id":"edge:1","from":"src/feature/helper.js","to":"src/feature/value.ts","kind":"imports","specifier":"./value","importKind":"import-statement"}\n` +
+  `{"id":"edge:2","from":"src/feature/index.ts","to":"src/feature/style.css","kind":"asset","specifier":"./style.css","importKind":"import-statement"}\n` +
+  `{"id":"edge:3","from":"src/feature/index.ts","to":"src/feature/value.ts","kind":"imports","specifier":"./value","importKind":"import-statement"}\n`;
 
 test("buildGraph output is byte-identical for a TS/JS-only project (AC4 guard)", async () => {
   const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-lang-regression");

package/src/gdgraph/build.ts

@@ -1,7 +1,8 @@
 import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import type { GraphData, GraphEdge, GraphNode } from "./types";
+import type { GraphData, GraphEdge, GraphNode, ImportKind, TranspilerImportKind } from "./types";
+import { UNKNOWN_IMPORT_KIND } from "./types";
 
 const SOURCE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".java", ".py"];
 const SOURCE_RESOLUTION_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".d.ts", ".java", ".py"];
@@ -111,9 +112,9 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
     // dropped), so the resolution metric is honest. TS/JS keeps the exact
     // original guard (relative + tsconfig alias only) ⇒ byte-identical output.
     const isLanguageAware = language === "java" || language === "python";
-    const specifiers = extractImportSpecifiers(content, language);
+    const records = extractImportRecords(content, language);
 
-    for (const specifier of specifiers) {
+    for (const { specifier, kind: importKind } of records) {
       const resolved = resolveImport(projectRoot, file, specifier, fileSet, resolver);
       const asset = resolved ? null : resolveAssetImport(projectRoot, file, specifier, resolver);
       const shouldTrackUnresolved =
@@ -136,6 +137,7 @@ export async function buildGraph(projectRoot: string): Promise<BuildResult> {
         to: resolved ?? asset ?? specifier,
         kind: resolved ? "imports" : asset ? "asset" : "unresolved",
         specifier,
+        importKind,
       });
     }
   }
@@ -200,14 +202,27 @@ async function collectSourceFiles(projectRoot: string): Promise<SourceCollection
   return { files: result.sort(), skippedDirectories: skippedDirectories.sort() };
 }
 
-function extractImportSpecifiers(content: string, language: string): string[] {
+type ImportRecord = { specifier: string; kind: ImportKind };
+
+// P1 remediation (flow 140): union the transpiler and fallback extractors as
+// before, but keep the transpiler's per-specifier kind alive instead of
+// collapsing everything to a bare specifier string. `build()`'s edge-writing
+// loop reads `record.kind` straight onto the edge, so cycle detection can
+// later tell a load-order `import-statement` from a call-time `dynamic-import`
+// instead of the previous single "imports" bucket.
+function extractImportRecords(content: string, language: string): ImportRecord[] {
   // Java/Python are not TS/JS syntax — the tsx transpiler cannot scan them
   // (it throws today, which is why they already reach the fallback). Route them
   // explicitly to the regex fallback that carries the java/python patterns,
   // rather than depending on the transpiler always throwing. TS/JS keep the
   // exact original transpiler-then-fallback path ⇒ byte-identical output.
+  // The fallback is a plain regex with no notion of import kind, so every
+  // Java/Python edge is marked UNKNOWN_IMPORT_KIND — never guessed (AC4).
   if (language === "java" || language === "python") {
-    return extractImportSpecifiersFallback(content);
+    return extractImportSpecifiersFallback(content).map((specifier) => ({
+      specifier,
+      kind: UNKNOWN_IMPORT_KIND,
+    }));
   }
   // `Bun.Transpiler#scanImports` ERASES type-only imports: `import type {X} from
   // "./m"` and `export type {X} from "./m"` are compiled away, so the transpiler
@@ -219,16 +234,46 @@ function extractImportSpecifiers(content: string, language: string): string[] {
   // odd formatting), the fallback contributes the type-only ones.
   const scanned = scanImportsOrEmpty(content);
   const fallback = extractImportSpecifiersFallback(content);
-  return [...new Set([...scanned, ...fallback])].sort();
+
+  const kindBySpecifier = new Map<string, ImportKind>();
+  for (const { specifier, kind } of scanned) {
+    const existing = kindBySpecifier.get(specifier);
+    // The same specifier can appear more than once in a file (a static import
+    // plus a separate `await import()` of the same path). A real static edge
+    // makes it a load-order dependency regardless of what else also imports
+    // it dynamically elsewhere in the file, so a non-dynamic kind always wins
+    // over a dynamic one already recorded for the same specifier.
+    if (!existing || (existing === "dynamic-import" && kind !== "dynamic-import")) {
+      kindBySpecifier.set(specifier, kind);
+    }
+  }
+  // Fallback-only specifiers (not seen by the transpiler at all — e.g.
+  // type-only imports) get the explicit unknown/static marker, never a
+  // guessed kind (AC4). A specifier the transpiler DID see keeps its real
+  // kind; the fallback never overrides it.
+  for (const specifier of fallback) {
+    if (!kindBySpecifier.has(specifier)) {
+      kindBySpecifier.set(specifier, UNKNOWN_IMPORT_KIND);
+    }
+  }
+
+  return [...kindBySpecifier.entries()]
+    .map(([specifier, kind]) => ({ specifier, kind }))
+    .sort((a, b) => a.specifier.localeCompare(b.specifier));
 }
 
-function scanImportsOrEmpty(content: string): string[] {
+type ScannedImport = { specifier: string; kind: TranspilerImportKind };
+
+function scanImportsOrEmpty(content: string): ScannedImport[] {
   try {
     const scanner = new Bun.Transpiler({ loader: "tsx" });
     return scanner
       .scanImports(content)
-      .map((entry) => entry.path)
-      .filter((specifier): specifier is string => typeof specifier === "string" && specifier.length > 0);
+      .filter(
+        (entry): entry is { path: string; kind: TranspilerImportKind } =>
+          typeof entry.path === "string" && entry.path.length > 0,
+      )
+      .map((entry) => ({ specifier: entry.path, kind: entry.kind }));
   } catch {
     // Unparseable source ⇒ the regex fallback alone still yields the imports.
     return [];

package/src/gdgraph/import-kind.test.ts

@@ -0,0 +1,205 @@
+// P1 remediation (flow 140) — `keryx gdgraph query cycles` was folding
+// `await import()` edges into the load-order cycle count. `Bun.Transpiler
+// #scanImports` already reports whether a specifier is a static
+// import-statement, a dynamic-import, a require-call, etc.; `build.ts` threw
+// that classification away one line after receiving it. These tests are
+// written FIRST (TDD RED) against the frozen acceptance criteria in
+// `.metaproject/flows/140-2026-08-07-gdgraph-dynamic-import-edges/acceptance-criteria.md`.
+//
+// Conventions mirror build.test.ts / build-lang.test.ts: uniqueTestRoot(),
+// reset(root), buildGraph(root), loadGraph(root).
+
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { expect, test } from "bun:test";
+import { buildGraph } from "./build";
+import { getCycles, loadGraph } from "./query";
+import { uniqueTestRoot } from "../lib/test-tmp";
+
+async function reset(root: string): Promise<void> {
+  await rm(root, { recursive: true, force: true });
+  await mkdir(root, { recursive: true });
+}
+
+// ---------------------------------------------------------------------------
+// AC1 — every edge the transpiler produced carries the kind scanImports
+// actually returned, and it survives to the written edge record.
+// ---------------------------------------------------------------------------
+
+test("AC1 — the transpiler's import kind survives onto the written edge record", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-ac1");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "index.ts"),
+    [
+      "import { staticValue } from './static';",
+      "const loadDynamic = async () => { const { dynamicValue } = await import('./dynamic'); return dynamicValue; };",
+      "const required = require('./required');",
+      "export const result = { staticValue, loadDynamic, required };",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(path.join(root, "src", "static.ts"), "export const staticValue = 1;\n");
+  await writeFile(path.join(root, "src", "dynamic.ts"), "export const dynamicValue = 2;\n");
+  await writeFile(path.join(root, "src", "required.ts"), "export const requiredValue = 3;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edgesFromIndex = graph.edges.filter(
+    (edge) => edge.from === "src/index.ts" && edge.kind === "imports",
+  );
+  const importKindByTarget = new Map(edgesFromIndex.map((edge) => [edge.to, edge.importKind]));
+
+  expect(importKindByTarget.get("src/static.ts")).toBe("import-statement");
+  expect(importKindByTarget.get("src/dynamic.ts")).toBe("dynamic-import");
+  expect(importKindByTarget.get("src/required.ts")).toBe("require-call");
+});
+
+test("a specifier imported both statically and dynamically in the same file keeps the static classification", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-mixed-specifier");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "index.ts"),
+    [
+      "import './shared';",
+      "const loadAgain = async () => { await import('./shared'); };",
+      "export const result = loadAgain;",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(path.join(root, "src", "shared.ts"), "export const shared = true;\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/index.ts" && item.to === "src/shared.ts");
+
+  expect(edge?.importKind).toBe("import-statement");
+});
+
+// ---------------------------------------------------------------------------
+// AC2 — a fixture reproducing the target's shape: one static edge, one
+// dynamic-import edge back, no longer reported as a load-order cycle.
+// ---------------------------------------------------------------------------
+
+test("AC2 — a cycle closed only through a dynamic-import edge is no longer reported as load-order", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-mixed");
+  await reset(root);
+  await mkdir(path.join(root, "bot", "commands"), { recursive: true });
+  // Mirrors the target's shape: commands/menu.ts statically imports
+  // callbacks.ts; callbacks.ts reaches back into menu.ts only via `await
+  // import()`.
+  await writeFile(
+    path.join(root, "bot", "commands", "menu.ts"),
+    "import { registerCallback } from '../callbacks';\nexport const menu = () => registerCallback();\n",
+  );
+  await writeFile(
+    path.join(root, "bot", "callbacks.ts"),
+    [
+      "export const registerCallback = () => 1;",
+      "export const handleMenuCallback = async () => {",
+      "  const { menu } = await import('./commands/menu');",
+      "  return menu();",
+      "};",
+      "",
+    ].join("\n"),
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(
+    cycles.some((cycle) => cycle.includes("bot/callbacks.ts") && cycle.includes("bot/commands/menu.ts")),
+  ).toBe(false);
+});
+
+// ---------------------------------------------------------------------------
+// AC3 — classification both ways, same two-file cycle shape.
+// ---------------------------------------------------------------------------
+
+test("AC3 — a two-file cycle formed by static imports IS reported", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-static");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(path.join(root, "src", "a.ts"), "import { b } from './b';\nexport const a = () => b();\n");
+  await writeFile(path.join(root, "src", "b.ts"), "import { a } from './a';\nexport const b = () => a();\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(true);
+});
+
+test("AC3 — the same two-file cycle formed by await import() is NOT reported as load-order", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-cycle-dynamic");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "a.ts"),
+    "export const a = async () => { const { b } = await import('./b'); return b(); };\n",
+  );
+  await writeFile(
+    path.join(root, "src", "b.ts"),
+    "export const b = async () => { const { a } = await import('./a'); return a(); };\n",
+  );
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const cycles = getCycles(graph);
+
+  expect(cycles.some((cycle) => cycle.includes("src/a.ts") && cycle.includes("src/b.ts"))).toBe(false);
+});
+
+// ---------------------------------------------------------------------------
+// AC4 — an edge found only by the regex fallback (never seen by scanImports)
+// is marked with an explicit unknown/static marker, never inferred dynamic.
+// A type-only import is the real-world case: `Bun.Transpiler#scanImports`
+// erases `import type {...}` entirely, so it reaches the graph only through
+// `extractImportSpecifiersFallback`.
+// ---------------------------------------------------------------------------
+
+test("AC4 — a fallback-only edge (type-only import) is marked unknown-static, never inferred dynamic", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-ac4");
+  await reset(root);
+  await mkdir(path.join(root, "src"), { recursive: true });
+  await writeFile(
+    path.join(root, "src", "consumer.ts"),
+    "import type { Shape } from './types';\nexport const consumer: Shape = { ok: true } as Shape;\n",
+  );
+  await writeFile(path.join(root, "src", "types.ts"), "export interface Shape { ok: boolean }\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find((item) => item.from === "src/consumer.ts" && item.to === "src/types.ts");
+
+  expect(edge).toBeDefined();
+  expect(edge?.importKind).toBe("unknown-static");
+  expect(edge?.importKind).not.toBe("dynamic-import");
+});
+
+test("AC4 — Java imports (fallback-only language) are marked unknown-static, never dynamic", async () => {
+  const root = uniqueTestRoot(tmpdir(), "keryx-gdgraph-import-kind-java");
+  await reset(root);
+  const javaRoot = path.join(root, "src", "main", "java", "com", "example");
+  await mkdir(javaRoot, { recursive: true });
+  await writeFile(
+    path.join(javaRoot, "Consumer.java"),
+    "package com.example;\nimport com.example.Model;\npublic class Consumer {}\n",
+  );
+  await writeFile(path.join(javaRoot, "Model.java"), "package com.example;\npublic class Model {}\n");
+
+  await buildGraph(root);
+  const graph = await loadGraph(root);
+  const edge = graph.edges.find(
+    (item) =>
+      item.from === "src/main/java/com/example/Consumer.java" &&
+      item.to === "src/main/java/com/example/Model.java",
+  );
+
+  expect(edge).toBeDefined();
+  expect(edge?.importKind).toBe("unknown-static");
+});

package/src/gdgraph/query.ts

@@ -61,7 +61,12 @@ export function getCycles(graph: GraphData): string[][] {
     adjacency.set(node.path, []);
   }
   for (const edge of graph.edges) {
-    if (edge.kind !== "imports") {
+    // A `dynamic-import` (`await import()`) resolves at call time, not
+    // module-load time, so a cycle closed only through one is not the
+    // load-order cycle this query answers (P1, flow 140). Excluding it here
+    // — rather than reclassifying `edge.kind` — leaves orphans/affected
+    // untouched (AC5): both still treat the edge as a normal import.
+    if (edge.kind !== "imports" || edge.importKind === "dynamic-import") {
       continue;
     }
     adjacency.get(edge.from)?.push(edge.to);

package/src/gdgraph/types.ts

@@ -5,12 +5,46 @@ export type GraphNode = {
   language: "typescript" | "javascript" | "java" | "python" | "asset";
 };
 
+// Import classification straight from `Bun.Transpiler#scanImports` (P1
+// remediation, flow 140). A static `import`/`export ... from` statement is a
+// load-order dependency; `dynamic-import` (`await import()`) resolves at call
+// time and is not. The full union mirrors every literal `scanImports` can
+// return (bun-types `ImportKind`), so a transpiler-found edge always carries
+// the value the transpiler actually reported — never a guess.
+export type TranspilerImportKind =
+  | "import-statement"
+  | "require-call"
+  | "require-resolve"
+  | "dynamic-import"
+  | "import-rule"
+  | "url-token"
+  | "internal"
+  | "entry-point-run"
+  | "entry-point-build";
+
+// A specifier found ONLY by the regex fallback (`extractImportSpecifiersFallback`
+// in build.ts) carries no real kind from the transpiler — the fallback is a
+// plain regex with no notion of "static" vs "dynamic". Never infer one;
+// `UNKNOWN_IMPORT_KIND` marks it explicitly and cycle detection treats it as
+// load-order (the pre-fix behavior), so fallback-only edges are never
+// silently excluded from a real cycle.
+export const UNKNOWN_IMPORT_KIND = "unknown-static" as const;
+
+export type ImportKind = TranspilerImportKind | typeof UNKNOWN_IMPORT_KIND;
+
 export type GraphEdge = {
   id: string;
   from: string;
   to: string;
   kind: "imports" | "asset" | "unresolved";
   specifier: string;
+  // Provenance/kind of the specifier that produced this edge (P1, flow 140).
+  // `buildGraph()` always sets this. Optional (not required) so edge literals
+  // constructed before this field existed — test fixtures elsewhere in the
+  // repo, or graphs persisted by an older `keryx gdgraph build` — stay valid;
+  // `getCycles` treats a missing value as load-order, matching pre-fix
+  // behavior rather than crashing or silently mis-classifying.
+  importKind?: ImportKind;
 };
 
 export type GraphData = {