@intentius/chant 0.45.0 → 0.49.0

package/src/lint/rules/cor024-receipt-secret-pointer.test.ts

@@ -0,0 +1,121 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
+import type { LintContext } from "../rule";
+
+function createContext(code: string, filePath = "test.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(filePath, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath, lexicon: undefined };
+}
+
+describe("COR024: receipt inputs reference secrets by pointer (#1833)", () => {
+  test("rule metadata", () => {
+    expect(cor024ReceiptSecretPointerRule.id).toBe("COR024");
+    expect(cor024ReceiptSecretPointerRule.severity).toBe("error");
+    expect(cor024ReceiptSecretPointerRule.category).toBe("correctness");
+  });
+
+  test("flags a receipt input reading a Secret entity's data attribute", () => {
+    const ctx = createContext(`
+      export const dbSecret = new SecretManagerSecret({ name: "db-password" });
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { password: dbSecret.data.password },
+      });
+    `);
+    const diags = cor024ReceiptSecretPointerRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].ruleId).toBe("COR024");
+    expect(diags[0].severity).toBe("error");
+    expect(diags[0].message).toContain("dbSecret.data.password");
+    expect(diags[0].message).toContain("name+version pointer");
+    expect(diags[0].message).toContain("secretVersion");
+  });
+
+  test("flags a .value read on a Secret entity", () => {
+    const ctx = createContext(`
+      const apiToken = new ExternalSecret({ name: "api-token" });
+      export const bootstrapped = EffectReceipt("bootstrapped", {
+        effect: "bootstrap",
+        flavor: "hash",
+        inputs: { token: apiToken.value },
+      });
+    `);
+    const diags = cor024ReceiptSecretPointerRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("apiToken.value");
+  });
+
+  test("const indirection fires: material extracted into a variable first", () => {
+    const ctx = createContext(`
+      const dbSecret = new SecretManagerSecret({ name: "db-password" });
+      const material = dbSecret.data;
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { password: material.password },
+      });
+    `);
+    const diags = cor024ReceiptSecretPointerRule.check(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("material");
+  });
+
+  test("bare material variable as an input fires", () => {
+    const ctx = createContext(`
+      const dbSecret = new SecretManagerSecret({ name: "db-password" });
+      const material = dbSecret.stringData;
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { blob: material },
+      });
+    `);
+    expect(cor024ReceiptSecretPointerRule.check(ctx)).toHaveLength(1);
+  });
+
+  test("passes: the name+version pointer form", () => {
+    const ctx = createContext(`
+      export const dbSecret = new SecretManagerSecret({ name: "db-password" });
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { secretName: dbSecret.name, secretVersion: 3 },
+      });
+    `);
+    expect(cor024ReceiptSecretPointerRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("passes: non-secret entity attributes and static inputs", () => {
+    const ctx = createContext(`
+      export const db = new Database({ name: "main" });
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { endpoint: db.endpoint, schema: "v3", value: db.port },
+      });
+    `);
+    expect(cor024ReceiptSecretPointerRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("passes: secret material read OUTSIDE a receipt's inputs is not this rule's concern", () => {
+    const ctx = createContext(`
+      const dbSecret = new SecretManagerSecret({ name: "db-password" });
+      export const app = new Service({ env: { DB_PASSWORD: dbSecret.data.password } });
+    `);
+    expect(cor024ReceiptSecretPointerRule.check(ctx)).toHaveLength(0);
+  });
+
+  test("declareSecret provenance declarations are secret-rooted", () => {
+    const ctx = createContext(`
+      const dbSecret = declareSecret("db-password", { provenance: "referenced" });
+      export const seeded = EffectReceipt("seeded", {
+        effect: "db-seed",
+        flavor: "hash",
+        inputs: { v: dbSecret.value },
+      });
+    `);
+    expect(cor024ReceiptSecretPointerRule.check(ctx)).toHaveLength(1);
+  });
+});

package/src/lint/rules/cor024-receipt-secret-pointer.ts

@@ -0,0 +1,218 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { receiptFactoryCall } from "./cor022-receipt-leaf";
+
+/**
+ * COR024: Receipt Inputs Reference Secrets by Pointer (#1833, epic #1703;
+ * composes with the secret-provenance work, #1365/#1828)
+ *
+ * A receipt's `inputs` feed its expectation hash (../../effect-receipt.ts) —
+ * whatever lands there is canonicalized, digested, and compared against a
+ * stored value for the rest of the receipt's life. chant's constitutional
+ * line on secrets is that no code path may hold, log, hash, or compare a
+ * secret value (../../secret-provenance.ts), so a receipt input that reads a
+ * Secret-kind entity's material (`.data`, `.value`, `.stringData`, ...)
+ * violates it twice over: the material enters the hash, and the serialized
+ * placeholder ties the receipt to the secret's value rather than its
+ * identity.
+ *
+ * The pointer form is fine — and is the point: reference the secret by name
+ * and version (`{ secretName: dbSecret.name, secretVersion: 3 }`), so a
+ * rotation is an explicit version bump that re-proposes the effect, and the
+ * hash only ever sees the pointer.
+ *
+ * Recognition is the same file-local reference walk COR022 uses (const
+ * indirection included): a variable is Secret-kind when its initializer is a
+ * constructor or factory whose name says so (`new SecretManagerSecret(...)`,
+ * `new ExternalSecret(...)`, `declareSecret(...)`); an input fires when a
+ * property chain rooted at one of those crosses a material field.
+ */
+
+/** Fields that carry secret material. Mirrors secret-provenance.ts's
+ * FORBIDDEN_MATERIAL_FIELDS, plus the provider-attribute spellings
+ * (`secretString`/`secretValue`) a materialized secret exposes. */
+const MATERIAL_FIELDS = new Set([
+  "value",
+  "data",
+  "stringdata",
+  "material",
+  "plaintext",
+  "ciphertext",
+  "secretstring",
+  "secretvalue",
+]);
+
+function isMaterialField(name: string): boolean {
+  return MATERIAL_FIELDS.has(name.toLowerCase());
+}
+
+/** Simple name of a `new X(...)` / `X(...)` / `ns.X(...)` initializer. */
+function initializerName(init: ts.Expression): string | undefined {
+  if (!ts.isNewExpression(init) && !ts.isCallExpression(init)) return undefined;
+  const callee = init.expression;
+  if (ts.isIdentifier(callee)) return callee.text;
+  if (ts.isPropertyAccessExpression(callee)) return callee.name.text;
+  return undefined;
+}
+
+/** Does this constructor/factory name declare a Secret-kind entity? */
+function isSecretKindName(name: string): boolean {
+  return /secret/i.test(name) || name === "declareSecret";
+}
+
+/** One access chain: `sec.data.password` → root "sec", segments ["data","password"]. */
+function decomposeChain(
+  node: ts.Expression,
+): { root: string; segments: string[] } | undefined {
+  const segments: string[] = [];
+  let current: ts.Expression = node;
+  while (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) {
+    if (ts.isPropertyAccessExpression(current)) {
+      segments.unshift(current.name.text);
+    } else {
+      const arg = current.argumentExpression;
+      segments.unshift(ts.isStringLiteralLike(arg) ? arg.text : "<computed>");
+    }
+    current = current.expression;
+  }
+  if (!ts.isIdentifier(current)) return undefined;
+  return { root: current.text, segments };
+}
+
+interface SecretVars {
+  /** Variables holding a Secret-kind entity (or an alias of one). */
+  secretRooted: Set<string>;
+  /** Variables that already crossed a material field (`const m = sec.data`). */
+  material: Set<string>;
+}
+
+/** File-local Secret-kind variables, aliases and material extractions, to a fixpoint. */
+function collectSecretVariables(sourceFile: ts.SourceFile): SecretVars {
+  const secretRooted = new Set<string>();
+  const material = new Set<string>();
+  const derived: Array<{ name: string; root: string; crossesMaterial: boolean; isBareAlias: boolean }> = [];
+
+  function visit(node: ts.Node): void {
+    if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+      const init = node.initializer;
+      const ctorName = initializerName(init);
+      if (ctorName !== undefined && isSecretKindName(ctorName)) {
+        secretRooted.add(node.name.text);
+      } else if (ts.isIdentifier(init)) {
+        derived.push({ name: node.name.text, root: init.text, crossesMaterial: false, isBareAlias: true });
+      } else if (ts.isPropertyAccessExpression(init) || ts.isElementAccessExpression(init)) {
+        const chain = decomposeChain(init);
+        if (chain) {
+          derived.push({
+            name: node.name.text,
+            root: chain.root,
+            crossesMaterial: chain.segments.some(isMaterialField),
+            isBareAlias: false,
+          });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  }
+  visit(sourceFile);
+
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const d of derived) {
+      const rootIsSecret = secretRooted.has(d.root);
+      const rootIsMaterial = material.has(d.root);
+      if (!rootIsSecret && !rootIsMaterial) continue;
+      const target = rootIsMaterial || d.crossesMaterial ? material : secretRooted;
+      if (d.isBareAlias && !d.crossesMaterial && rootIsSecret) {
+        if (!secretRooted.has(d.name)) {
+          secretRooted.add(d.name);
+          grew = true;
+        }
+      } else if (!target.has(d.name)) {
+        target.add(d.name);
+        grew = true;
+      }
+    }
+  }
+  return { secretRooted, material };
+}
+
+export const cor024ReceiptSecretPointerRule: LintRule = {
+  id: "COR024",
+  severity: "error",
+  category: "correctness",
+  description:
+    "A receipt's inputs may reference a secret only by name+version pointer, never by value — secret material must not enter the expectation hash",
+  check(context: LintContext): LintDiagnostic[] {
+    const diagnostics: LintDiagnostic[] = [];
+    const secrets = collectSecretVariables(context.sourceFile);
+    if (secrets.secretRooted.size === 0 && secrets.material.size === 0) return diagnostics;
+
+    const report = (node: ts.Node, rendered: string, root: string): void => {
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        node.getStart(context.sourceFile),
+      );
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR024",
+        severity: "error",
+        message:
+          `Receipt input reads secret material (${rendered}) from "${root}" — a receipt's inputs may ` +
+          `reference a secret only by name+version pointer, never by value: the inputs are hashed into ` +
+          `the receipt's expectation, and no chant code path may hash or compare secret material. ` +
+          `Use the pointer form instead, e.g. { secretName: ${root}.name, secretVersion: 3 } — ` +
+          `a rotation then re-proposes the effect through an explicit version bump.`,
+      });
+    };
+
+    const checkInputs = (inputs: ts.Expression): void => {
+      const visit = (node: ts.Node): void => {
+        if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) {
+          const chain = decomposeChain(node);
+          if (chain) {
+            const rootMaterial = secrets.material.has(chain.root);
+            const crossesMaterial = chain.segments.some(isMaterialField);
+            if (rootMaterial || (secrets.secretRooted.has(chain.root) && crossesMaterial)) {
+              report(node, `\`${chain.root}.${chain.segments.join(".")}\``, chain.root);
+              return; // one diagnostic per chain, not one per link
+            }
+          }
+        } else if (ts.isIdentifier(node) && secrets.material.has(node.text)) {
+          const parent = node.parent;
+          const isChainBase =
+            (ts.isPropertyAccessExpression(parent) || ts.isElementAccessExpression(parent)) &&
+            parent.expression === node;
+          const isKey = ts.isPropertyAssignment(parent) && parent.name === node;
+          if (!isChainBase && !isKey) report(node, `\`${node.text}\``, node.text);
+        }
+        ts.forEachChild(node, visit);
+      };
+      visit(inputs);
+    };
+
+    const walk = (node: ts.Node): void => {
+      if (ts.isVariableDeclaration(node)) {
+        const call = receiptFactoryCall(node);
+        const options = call?.arguments[1];
+        if (options && ts.isObjectLiteralExpression(options)) {
+          for (const prop of options.properties) {
+            if (
+              ts.isPropertyAssignment(prop) &&
+              (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) &&
+              prop.name.text === "inputs"
+            ) {
+              checkInputs(prop.initializer);
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, walk);
+    };
+    walk(context.sourceFile);
+
+    return diagnostics;
+  },
+};

package/src/lint/rules/evl001-non-literal-expression.test.ts

@@ -104,6 +104,33 @@ describe("EVL001: non-literal-expression", () => {
     expect(diags[0].ruleId).toBe("EVL001");
   });
 
+  // chant #1544 — the single-action Composite() wrapper idiom
+  // (`Checkout({...}).step`) every lexicon's own docs/examples embed inline
+  // inside a `Job`'s `steps:` array must not trip EVL001.
+  test("allows a composite call's .step access embedded in an array", () => {
+    const ctx = createContext(`new Job({ "runs-on": "ubuntu-latest", steps: [Checkout({}).step] });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("allows a composite call's .step access as a direct property value", () => {
+    const ctx = createContext(`new Job({ step: Checkout({ ref: "main" }).step });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(0);
+  });
+
+  test("still flags a call accessing a non-.step property", () => {
+    const ctx = createContext(`new Job({ steps: [Checkout({}).output] });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
+  test("still flags a bare call (no trailing .step access)", () => {
+    const ctx = createContext(`new Bucket({ name: getName() });`);
+    const diags = evl001NonLiteralExpressionRule.check(ctx);
+    expect(diags).toHaveLength(1);
+  });
+
   test("flags multiple violations", () => {
     const ctx = createContext(`new Bucket({ a: foo(), b: bar() });`);
     const diags = evl001NonLiteralExpressionRule.check(ctx);

package/src/lint/rules/evl001-non-literal-expression.ts

@@ -31,7 +31,14 @@ function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnos
       const firstArg = node.arguments[0];
       if (ts.isObjectLiteralExpression(firstArg)) {
         for (const prop of firstArg.properties) {
-          const violation = checkObjectMember(prop, context.intrinsics);
+          // chant #1544 — `allowCompositeStepAccess: true` opts EVL001 (and
+          // only EVL001; `fold()` never sets this) into treating
+          // `Checkout({...}).step` — the single-action Composite()-wrapper
+          // idiom every lexicon's own docs/examples embed inline inside a
+          // Job's `steps:` array — as shape-valid. See findSubsetViolation's
+          // doc comment (../../fold/subset.ts) for why this is a documented,
+          // EVL-only, more-permissive divergence rather than a shared one.
+          const violation = checkObjectMember(prop, context.intrinsics, true);
           if (violation) {
             const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
               violation.node.getStart(context.sourceFile),

package/src/lint/rules/index.ts

@@ -25,6 +25,9 @@ export { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant";
 export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform";
 export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
+export { cor022ReceiptLeafRule, collectReceiptVariables, receiptFactoryCall } from "./cor022-receipt-leaf";
+export { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
 export { isInsideCompositeFactory } from "./composite-scope";
 
 import { flatDeclarationsRule } from "./flat-declarations";
@@ -48,9 +51,12 @@ import { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant";
 import { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform";
 import { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 import { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
+import { cor022ReceiptLeafRule } from "./cor022-receipt-leaf";
+import { cor024ReceiptSecretPointerRule } from "./cor024-receipt-secret-pointer";
 
 /**
- * Load all 21 core lint rules (COR + EVL).
+ * Load all 24 core lint rules (COR + EVL).
  */
 export function loadCoreRules(): LintRule[] {
   return [
@@ -75,5 +81,8 @@ export function loadCoreRules(): LintRule[] {
     evl010CompositeNoTransformRule,
     cor017CompositeNameMatchRule,
     cor018CompositePreferLexiconTypeRule,
+    cor021EnvLiteralNameRule,
+    cor022ReceiptLeafRule,
+    cor024ReceiptSecretPointerRule,
   ];
 }

package/src/okf-read.test.ts

@@ -0,0 +1,149 @@
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { loadOkfBundle, bindConcepts } from "./okf-read";
+import { buildOkfBundle } from "./okf";
+import { DECLARABLE_MARKER, type Declarable } from "./declarable";
+
+function decl<T extends object>(base: T): Declarable & T {
+  return { [DECLARABLE_MARKER]: true, ...base } as Declarable & T;
+}
+
+const TEST_DIR = join(import.meta.dirname, "__test_okf_read__");
+
+beforeEach(() => {
+  mkdirSync(TEST_DIR, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+function write(relPath: string, content: string): void {
+  const full = join(TEST_DIR, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content);
+}
+
+describe("loadOkfBundle", () => {
+  test("a missing directory yields an empty bundle, not an error", async () => {
+    const bundle = await loadOkfBundle(join(TEST_DIR, "does-not-exist"));
+    expect(bundle.concepts).toEqual([]);
+  });
+
+  test("skips index.md and log.md, at any depth", async () => {
+    write("index.md", "---\nokf_version: '0.2'\n---\n");
+    write("log.md", "---\ntype: log\n---\nsome log\n");
+    write("nested/log.md", "---\ntype: log\n---\nnested log\n");
+    write("decisions/keep.md", "---\ntype: decision\ntitle: Keep me\n---\nbody\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts.map((c) => c.path)).toEqual(["decisions/keep.md"]);
+  });
+
+  test("passes through unknown type values and extra frontmatter keys", async () => {
+    write("weird.md", "---\ntype: some-unknown-type\ncustom_field: hello\n---\nbody text\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts).toHaveLength(1);
+    const [concept] = bundle.concepts;
+    expect(concept.type).toBe("some-unknown-type");
+    expect(concept.frontmatter.custom_field).toBe("hello");
+    expect(concept.body).toContain("body text");
+  });
+
+  test("skips a file with unparseable frontmatter, warns, and does not affect other files", async () => {
+    write("broken.md", "not frontmatter at all\n");
+    write("fine.md", "---\ntype: decision\ntitle: Fine\n---\nbody\n");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+
+    expect(bundle.concepts.map((c) => c.path)).toEqual(["fine.md"]);
+    expect(warn).toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  test("never rejects the bundle for a malformed file — an empty frontmatter block loads with an empty type", async () => {
+    write("empty-front.md", "---\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts).toHaveLength(1);
+    expect(bundle.concepts[0].type).toBe("");
+    expect(bundle.concepts[0].binds).toEqual([]);
+  });
+
+  test("binds accepts a single name", async () => {
+    write("single.md", "---\ntype: decision\nbinds: myBucket\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual(["myBucket"]);
+  });
+
+  test("binds accepts a list", async () => {
+    write("multi.md", "---\ntype: decision\nbinds:\n  - myBucket\n  - vpc\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual(["myBucket", "vpc"]);
+  });
+
+  test("a concept without binds loads as unbound and is legitimate", async () => {
+    write("orphan.md", "---\ntype: runbook\ntitle: Incident response\n---\nbody\n");
+    const bundle = await loadOkfBundle(TEST_DIR);
+    expect(bundle.concepts[0].binds).toEqual([]);
+  });
+});
+
+describe("bindConcepts", () => {
+  test("returns bound concepts per entity name plus unresolved bindings", async () => {
+    write("bound.md", "---\ntype: decision\ntitle: Bound\nbinds: myBucket\n---\nbody\n");
+    write("multi.md", "---\ntype: decision\ntitle: Spans two\nbinds:\n  - myBucket\n  - vpc\n---\nbody\n");
+    write("stale.md", "---\ntype: decision\ntitle: Stale\nbinds: ghost\n---\nbody\n");
+    write("orphan.md", "---\ntype: runbook\ntitle: Orphan\n---\nbody\n");
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    const entities = new Map<string, Declarable>([
+      ["myBucket", decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" })],
+      ["vpc", decl({ lexicon: "gcp", entityType: "Vpc" })],
+    ]);
+
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+
+    expect(bound.get("myBucket")?.map((c) => c.title)).toEqual(["Bound", "Spans two"]);
+    expect(bound.get("vpc")?.map((c) => c.title)).toEqual(["Spans two"]);
+    expect(bound.has("ghost")).toBe(false);
+    expect(unresolved).toHaveLength(1);
+    expect(unresolved[0].name).toBe("ghost");
+    expect(unresolved[0].concept.title).toBe("Stale");
+  });
+
+  test("an entity with no bound concepts is absent from the map, never present with []", async () => {
+    const bundle = await loadOkfBundle(join(TEST_DIR, "empty"));
+    const entities = new Map<string, Declarable>([["vpc", decl({ lexicon: "gcp", entityType: "Vpc" })]]);
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+    expect(bound.size).toBe(0);
+    expect(unresolved).toEqual([]);
+  });
+});
+
+describe("round trip with buildOkfBundle (#1058) — the emitter never writes binds", () => {
+  test("reading back an emitted bundle yields zero bindings", async () => {
+    const bucket = decl({ lexicon: "aws", entityType: "AWS::S3::Bucket" });
+    const vpc = decl({ lexicon: "gcp", entityType: "Vpc" });
+    const entities = new Map<string, Declarable>([
+      ["myBucket", bucket],
+      ["vpc", vpc],
+    ]);
+    const dependencies = new Map([["myBucket", new Set(["vpc"])]]);
+
+    for (const file of buildOkfBundle({ entities, dependencies })) {
+      write(file.path, file.content);
+    }
+
+    const bundle = await loadOkfBundle(TEST_DIR);
+    // index.md is reserved and skipped; the two entity concepts load.
+    expect(bundle.concepts.map((c) => c.path).sort()).toEqual(["aws/myBucket.md", "gcp/vpc.md"]);
+    expect(bundle.concepts.every((c) => c.binds.length === 0)).toBe(true);
+
+    const { bound, unresolved } = bindConcepts(bundle, entities);
+    expect(bound.size).toBe(0);
+    expect(unresolved).toEqual([]);
+  });
+});