@sweny-ai/core 0.1.53 → 0.1.55

package/dist/schema.js

@@ -7,6 +7,8 @@
  * parsing untrusted input (JSON/YAML import, Studio editor).
  */
 import { z } from "zod";
+import { sourceZ } from "./sources.js";
+export { sourceZ };
 // ─── Zod Schemas ─────────────────────────────────────────────────
 export const jsonSchemaZ = z.record(z.unknown());
 export const configFieldZ = z.object({
@@ -63,7 +65,7 @@ export const skillZ = z
 });
 export const nodeZ = z.object({
     name: z.string().min(1),
-    instruction: z.string().min(1),
+    instruction: sourceZ,
     skills: z.array(z.string()).default([]),
     output: jsonSchemaZ.optional(),
 });
@@ -232,6 +234,32 @@ export function validateWorkflow(workflow, knownSkills) {
  * Static JSON Schema for the Workflow type.
  * Use this for external validation (YAML files, Studio import, CI checks).
  */
+const sourceJsonSchema = {
+    oneOf: [
+        { type: "string", minLength: 1 },
+        {
+            type: "object",
+            properties: { inline: { type: "string" } },
+            required: ["inline"],
+            additionalProperties: false,
+        },
+        {
+            type: "object",
+            properties: { file: { type: "string", minLength: 1 } },
+            required: ["file"],
+            additionalProperties: false,
+        },
+        {
+            type: "object",
+            properties: {
+                url: { type: "string", format: "uri" },
+                type: { type: "string" },
+            },
+            required: ["url"],
+            additionalProperties: false,
+        },
+    ],
+};
 export const workflowJsonSchema = {
     $schema: "https://json-schema.org/draft/2020-12/schema",
     $id: "https://sweny.ai/schemas/workflow.json",
@@ -240,6 +268,7 @@ export const workflowJsonSchema = {
     type: "object",
     required: ["id", "name", "nodes", "edges", "entry"],
     additionalProperties: false,
+    $defs: { Source: sourceJsonSchema },
     properties: {
         id: { type: "string", minLength: 1 },
         name: { type: "string", minLength: 1 },
@@ -253,7 +282,7 @@ export const workflowJsonSchema = {
                 additionalProperties: false,
                 properties: {
                     name: { type: "string", minLength: 1 },
-                    instruction: { type: "string", minLength: 1, description: "What Claude should do at this node" },
+                    instruction: { $ref: "#/$defs/Source", description: "What Claude should do at this node" },
                     skills: {
                         type: "array",
                         items: { type: "string" },

package/dist/sources.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Source type — unified shape for every content-bearing field in a workflow
+ * (instructions, rules, context, templates). Supports inline text, relative or
+ * absolute file paths, and HTTP(S) URLs via a single ergonomic form.
+ *
+ * See docs/superpowers/specs/2026-04-12-unified-source-type-design.md.
+ */
+import { z } from "zod";
+import type { Logger } from "./types.js";
+export type Source = string | {
+    inline: string;
+} | {
+    file: string;
+} | {
+    url: string;
+    type?: string;
+};
+export type SourceKind = "inline" | "file" | "url";
+/**
+ * Zod schema for a Source. Accepts either a non-empty string (classified by
+ * prefix) or one of three tagged object forms: {inline}, {file}, {url,type?}.
+ * Runtime validation of `type` against the resolver registry happens later —
+ * the schema stays permissive so new resolvers slot in without schema bumps.
+ */
+export declare const sourceZ: z.ZodUnion<[z.ZodString, z.ZodObject<{
+    inline: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    inline: string;
+}, {
+    inline: string;
+}>, z.ZodObject<{
+    file: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    file: string;
+}, {
+    file: string;
+}>, z.ZodObject<{
+    url: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    url: string;
+    type?: string | undefined;
+}, {
+    url: string;
+    type?: string | undefined;
+}>]>;
+/**
+ * Classify a plain-string Source by prefix. Throws on empty strings.
+ */
+export type ResolvedSource = {
+    content: string;
+    kind: SourceKind;
+    origin: Source;
+    resolver: "inline" | "file" | "fetch";
+    hash: string;
+    fetchedAt?: string;
+    sourcePath?: string;
+};
+export type SourceResolutionMap = Record<string, ResolvedSource>;
+export declare function hashContent(content: string): string;
+export declare function classifySource(raw: string): SourceKind;
+export type SourceResolutionContext = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    authConfig: Record<string, string>;
+    offline: boolean;
+    logger: Logger;
+};
+export declare function resolveSource(source: Source, fieldPath: string, ctx: SourceResolutionContext): Promise<ResolvedSource>;
+export declare function resolveSources(sources: Record<string, Source>, ctx: SourceResolutionContext): Promise<SourceResolutionMap>;

package/dist/sources.js

@@ -0,0 +1,194 @@
+/**
+ * Source type — unified shape for every content-bearing field in a workflow
+ * (instructions, rules, context, templates). Supports inline text, relative or
+ * absolute file paths, and HTTP(S) URLs via a single ergonomic form.
+ *
+ * See docs/superpowers/specs/2026-04-12-unified-source-type-design.md.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { z } from "zod";
+const inlineTagZ = z.object({ inline: z.string().min(1) }).strict();
+const fileTagZ = z.object({ file: z.string().min(1) }).strict();
+const urlTagZ = z
+    .object({
+    url: z.string().url(),
+    type: z.string().optional(),
+})
+    .strict();
+/**
+ * Zod schema for a Source. Accepts either a non-empty string (classified by
+ * prefix) or one of three tagged object forms: {inline}, {file}, {url,type?}.
+ * Runtime validation of `type` against the resolver registry happens later —
+ * the schema stays permissive so new resolvers slot in without schema bumps.
+ */
+export const sourceZ = z.union([z.string().min(1), inlineTagZ, fileTagZ, urlTagZ]);
+export function hashContent(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex").slice(0, 16);
+}
+export function classifySource(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        throw new Error("source error: empty string is not a valid Source");
+    }
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+        return "url";
+    }
+    if (trimmed.startsWith("./") || trimmed.startsWith("../") || trimmed.startsWith("/")) {
+        return "file";
+    }
+    return "inline";
+}
+export async function resolveSource(source, fieldPath, ctx) {
+    const [kind, value] = normalizeSource(source);
+    if (kind === "inline") {
+        return {
+            content: value,
+            kind: "inline",
+            origin: source,
+            resolver: "inline",
+            hash: hashContent(value),
+        };
+    }
+    if (kind === "file") {
+        const absolute = path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value);
+        let content;
+        try {
+            content = await fs.readFile(absolute, "utf-8");
+        }
+        catch (err) {
+            const e = err;
+            if (e.code === "ENOENT") {
+                throw new Error(`SOURCE_FILE_NOT_FOUND: file not found: ${absolute} (referenced by ${fieldPath})`);
+            }
+            throw new Error(`SOURCE_FILE_READ_FAILED: could not read ${absolute} (referenced by ${fieldPath}): ${e.message}`);
+        }
+        // Strip UTF-8 BOM (Windows editors emit this)
+        if (content.charCodeAt(0) === 0xfeff)
+            content = content.slice(1);
+        return {
+            content,
+            kind: "file",
+            origin: source,
+            resolver: "file",
+            hash: hashContent(content),
+            sourcePath: absolute,
+        };
+    }
+    if (kind === "url") {
+        if (ctx.offline) {
+            throw new Error(`SOURCE_OFFLINE_REQUIRES_FETCH: cannot fetch ${value} in --offline mode (referenced by ${fieldPath}).`);
+        }
+        // Validate type field on tagged URL forms — v1 only accepts "fetch" (the default).
+        if (typeof source === "object" && "url" in source && source.type && source.type !== "fetch") {
+            throw new Error(`SOURCE_INVALID_TYPE: unknown resolver type "${source.type}" on ${value} (referenced by ${fieldPath}). v1 supports only "fetch".`);
+        }
+        const url = value;
+        const headers = buildFetchHeaders(url, ctx);
+        const res = await fetchWithRetry(url, headers, fieldPath);
+        if (res.status === 401 || res.status === 403) {
+            throw new Error(`SOURCE_URL_AUTH_REQUIRED: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}). Configure fetch.auth in .sweny.yml or set SWENY_FETCH_TOKEN.`);
+        }
+        if (!res.ok) {
+            throw new Error(`SOURCE_URL_HTTP_ERROR: ${url} returned HTTP ${res.status} (referenced by ${fieldPath}).`);
+        }
+        const content = await res.text();
+        return {
+            content,
+            kind: "url",
+            origin: source,
+            resolver: "fetch",
+            hash: hashContent(content),
+            fetchedAt: new Date().toISOString(),
+        };
+    }
+    throw new Error(`source error: unreachable (kind: ${kind}, field: ${fieldPath})`);
+}
+export async function resolveSources(sources, ctx) {
+    const cache = new Map();
+    const out = {};
+    const entries = Object.entries(sources);
+    await Promise.all(entries.map(async ([fieldPath, source]) => {
+        const key = canonicalKey(source, ctx);
+        let promise = key ? cache.get(key) : undefined;
+        if (!promise) {
+            promise = resolveSource(source, fieldPath, ctx);
+            if (key)
+                cache.set(key, promise);
+        }
+        out[fieldPath] = await promise;
+    }));
+    return out;
+}
+function canonicalKey(source, ctx) {
+    const [kind, value] = normalizeSource(source);
+    if (kind === "file") {
+        return "file:" + (path.isAbsolute(value) ? value : path.resolve(ctx.cwd, value));
+    }
+    if (kind === "url")
+        return "url:" + value;
+    return null;
+}
+const RETRY_DELAYS = [250, 1000]; // ms — exponential backoff for 5xx
+async function fetchWithRetry(url, headers, fieldPath) {
+    let lastError;
+    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+        try {
+            const res = await fetch(url, { headers, signal: AbortSignal.timeout(10_000) });
+            // Don't retry on 4xx (client errors) or 2xx (success)
+            if (res.status < 500)
+                return res;
+            // 5xx — retry if attempts remain
+            if (attempt < RETRY_DELAYS.length) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
+                continue;
+            }
+            return res; // final 5xx — let caller handle it
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            if (attempt < RETRY_DELAYS.length) {
+                await new Promise((r) => setTimeout(r, RETRY_DELAYS[attempt]));
+                continue;
+            }
+        }
+    }
+    throw new Error(`SOURCE_URL_UNREACHABLE: ${url} (referenced by ${fieldPath}): ${lastError?.message ?? "unknown error"}. Pass --offline to skip URL sources.`);
+}
+function buildFetchHeaders(url, ctx) {
+    const headers = {
+        Accept: "text/plain, text/markdown, */*",
+    };
+    const token = resolveFetchToken(url, ctx);
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    return headers;
+}
+function resolveFetchToken(url, ctx) {
+    let host;
+    try {
+        host = new URL(url).host;
+    }
+    catch {
+        return undefined;
+    }
+    const envVar = ctx.authConfig[host];
+    if (envVar && ctx.env[envVar])
+        return ctx.env[envVar];
+    const fallback = ctx.env.SWENY_FETCH_TOKEN;
+    return fallback || undefined;
+}
+function normalizeSource(source) {
+    if (typeof source === "string") {
+        const kind = classifySource(source);
+        return [kind, source.trim()];
+    }
+    if ("inline" in source)
+        return ["inline", source.inline];
+    if ("file" in source)
+        return ["file", source.file.trim()];
+    if ("url" in source)
+        return ["url", source.url.trim()];
+    throw new Error("source error: unrecognised Source shape");
+}

package/dist/sources.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sources.test.js

@@ -0,0 +1,264 @@
+import { mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import * as path from "node:path";
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { classifySource, sourceZ, hashContent, resolveSource, resolveSources } from "./sources.js";
+const fileTmp = path.join(tmpdir(), "sweny-sources-file-test");
+const baseCtx = () => ({
+    cwd: "/tmp",
+    env: {},
+    authConfig: {},
+    offline: false,
+    logger: { info: () => { }, warn: () => { }, error: () => { }, debug: () => { } },
+});
+describe("classifySource", () => {
+    it("classifies http(s) URLs as url", () => {
+        expect(classifySource("http://example.com/x.md")).toBe("url");
+        expect(classifySource("https://example.com/x.md")).toBe("url");
+    });
+    it("classifies ./ ../ and / paths as file", () => {
+        expect(classifySource("./local.md")).toBe("file");
+        expect(classifySource("../sibling.md")).toBe("file");
+        expect(classifySource("/abs/path.md")).toBe("file");
+    });
+    it("classifies anything else as inline", () => {
+        expect(classifySource("Just be helpful.")).toBe("inline");
+        expect(classifySource("foo bar baz")).toBe("inline");
+    });
+    it("rejects empty strings", () => {
+        expect(() => classifySource("")).toThrow(/empty/i);
+        expect(() => classifySource("   ")).toThrow(/empty/i);
+    });
+});
+describe("sourceZ", () => {
+    it("accepts non-empty string", () => {
+        expect(sourceZ.parse("hello")).toBe("hello");
+        expect(sourceZ.parse("./x.md")).toBe("./x.md");
+        expect(sourceZ.parse("https://x/y")).toBe("https://x/y");
+    });
+    it("rejects empty string", () => {
+        expect(() => sourceZ.parse("")).toThrow();
+    });
+    it("accepts tagged inline form", () => {
+        expect(sourceZ.parse({ inline: "text" })).toEqual({ inline: "text" });
+    });
+    it("accepts tagged file form", () => {
+        expect(sourceZ.parse({ file: "./x.md" })).toEqual({ file: "./x.md" });
+    });
+    it("accepts tagged url form with and without type", () => {
+        expect(sourceZ.parse({ url: "https://x" })).toEqual({ url: "https://x" });
+        expect(sourceZ.parse({ url: "https://x", type: "fetch" })).toEqual({
+            url: "https://x",
+            type: "fetch",
+        });
+    });
+    it("rejects objects with multiple tag keys", () => {
+        expect(() => sourceZ.parse({ inline: "x", file: "./y" })).toThrow();
+        expect(() => sourceZ.parse({ file: "./x", url: "https://y" })).toThrow();
+    });
+    it("rejects objects with no tag keys", () => {
+        expect(() => sourceZ.parse({})).toThrow();
+        expect(() => sourceZ.parse({ foo: "bar" })).toThrow();
+    });
+    it("rejects extra keys on tagged forms", () => {
+        expect(() => sourceZ.parse({ inline: "x", extra: true })).toThrow();
+    });
+});
+describe("hashContent", () => {
+    it("produces stable 16-char hex for same content", () => {
+        const a = hashContent("hello world");
+        const b = hashContent("hello world");
+        expect(a).toBe(b);
+        expect(a).toMatch(/^[0-9a-f]{16}$/);
+    });
+    it("produces different hashes for different content", () => {
+        expect(hashContent("a")).not.toBe(hashContent("b"));
+    });
+});
+describe("resolveSource (inline)", () => {
+    it("returns the plain string for inline-classified strings", async () => {
+        const resolved = await resolveSource("Just do it.", "test.field", baseCtx());
+        expect(resolved.content).toBe("Just do it.");
+        expect(resolved.kind).toBe("inline");
+        expect(resolved.resolver).toBe("inline");
+        expect(resolved.origin).toBe("Just do it.");
+        expect(resolved.hash).toMatch(/^[0-9a-f]{16}$/);
+        expect(resolved.fetchedAt).toBeUndefined();
+        expect(resolved.sourcePath).toBeUndefined();
+    });
+    it("returns the inline text from tagged {inline} form", async () => {
+        const resolved = await resolveSource({ inline: "Tagged body" }, "test.field", baseCtx());
+        expect(resolved.content).toBe("Tagged body");
+        expect(resolved.kind).toBe("inline");
+        expect(resolved.resolver).toBe("inline");
+    });
+});
+describe("resolveSource (file)", () => {
+    beforeEach(() => {
+        rmSync(fileTmp, { recursive: true, force: true });
+        mkdirSync(fileTmp, { recursive: true });
+    });
+    it("reads a file by relative path (cwd-based)", async () => {
+        writeFileSync(path.join(fileTmp, "rules.md"), "# Rules\n\nBe kind.");
+        const resolved = await resolveSource("./rules.md", "rules[0]", {
+            ...baseCtx(),
+            cwd: fileTmp,
+        });
+        expect(resolved.content).toBe("# Rules\n\nBe kind.");
+        expect(resolved.kind).toBe("file");
+        expect(resolved.resolver).toBe("file");
+        expect(resolved.sourcePath).toBe(path.resolve(fileTmp, "rules.md"));
+    });
+    it("reads a file via tagged {file} form", async () => {
+        writeFileSync(path.join(fileTmp, "a.txt"), "alpha");
+        const resolved = await resolveSource({ file: "./a.txt" }, "x", {
+            ...baseCtx(),
+            cwd: fileTmp,
+        });
+        expect(resolved.content).toBe("alpha");
+        expect(resolved.origin).toEqual({ file: "./a.txt" });
+    });
+    it("reads an absolute path", async () => {
+        const abs = path.join(fileTmp, "abs.md");
+        writeFileSync(abs, "absolute body");
+        const resolved = await resolveSource(abs, "x", baseCtx());
+        expect(resolved.content).toBe("absolute body");
+    });
+    it("throws SOURCE_FILE_NOT_FOUND with field path on missing file", async () => {
+        await expect(resolveSource("./missing.md", "nodes.investigate.instruction", {
+            ...baseCtx(),
+            cwd: fileTmp,
+        })).rejects.toThrow(/SOURCE_FILE_NOT_FOUND.*nodes\.investigate\.instruction/);
+    });
+});
+describe("resolveSource (fetch)", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("fetches URL content via plain string", async () => {
+        const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async () => {
+            return new Response("# Shared rules\n\nBe careful.", {
+                status: 200,
+                headers: { "content-type": "text/markdown" },
+            });
+        });
+        const resolved = await resolveSource("https://example.com/rules.md", "rules[0]", baseCtx());
+        expect(resolved.content).toBe("# Shared rules\n\nBe careful.");
+        expect(resolved.kind).toBe("url");
+        expect(resolved.resolver).toBe("fetch");
+        expect(resolved.fetchedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+        expect(fetchMock).toHaveBeenCalledOnce();
+    });
+    it("fetches via tagged {url} form", async () => {
+        vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("body", { status: 200 }));
+        const resolved = await resolveSource({ url: "https://x.test/y", type: "fetch" }, "x", baseCtx());
+        expect(resolved.content).toBe("body");
+    });
+    it("throws SOURCE_URL_HTTP_ERROR on 4xx", async () => {
+        vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("nope", { status: 404 }));
+        await expect(resolveSource("https://x.test/missing", "nodes.n.instruction", baseCtx())).rejects.toThrow(/SOURCE_URL_HTTP_ERROR.*404.*nodes\.n\.instruction/);
+    });
+    it("throws SOURCE_URL_AUTH_REQUIRED on 401", async () => {
+        vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("denied", { status: 401 }));
+        await expect(resolveSource("https://x.test/auth", "x", baseCtx())).rejects.toThrow(/SOURCE_URL_AUTH_REQUIRED/);
+    });
+});
+describe("fetch auth headers", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("sets Authorization from per-host fetch.auth config", async () => {
+        const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("ok", { status: 200 }));
+        await resolveSource("https://raw.githubusercontent.com/x/y/main/z.md", "f", {
+            ...baseCtx(),
+            env: { GITHUB_TOKEN: "ghp_abc" },
+            authConfig: { "raw.githubusercontent.com": "GITHUB_TOKEN" },
+        });
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init.headers).toMatchObject({
+            Authorization: "Bearer ghp_abc",
+        });
+    });
+    it("falls back to SWENY_FETCH_TOKEN when no per-host match", async () => {
+        const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("ok", { status: 200 }));
+        await resolveSource("https://other.example/x", "f", {
+            ...baseCtx(),
+            env: { SWENY_FETCH_TOKEN: "global_token" },
+            authConfig: { "raw.githubusercontent.com": "GITHUB_TOKEN" },
+        });
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init.headers).toMatchObject({
+            Authorization: "Bearer global_token",
+        });
+    });
+    it("omits Authorization when env var is unset", async () => {
+        const fetchMock = vi.spyOn(globalThis, "fetch").mockImplementation(async () => new Response("ok", { status: 200 }));
+        await resolveSource("https://raw.githubusercontent.com/x", "f", {
+            ...baseCtx(),
+            env: {},
+            authConfig: { "raw.githubusercontent.com": "GITHUB_TOKEN" },
+        });
+        const [, init] = fetchMock.mock.calls[0];
+        const headers = init.headers;
+        expect(headers.Authorization).toBeUndefined();
+    });
+});
+describe("offline mode", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        rmSync(fileTmp, { recursive: true, force: true });
+        mkdirSync(fileTmp, { recursive: true });
+    });
+    it("file resolution still works when offline", async () => {
+        writeFileSync(path.join(fileTmp, "local.md"), "hi");
+        const resolved = await resolveSource("./local.md", "f", {
+            ...baseCtx(),
+            cwd: fileTmp,
+            offline: true,
+        });
+        expect(resolved.content).toBe("hi");
+    });
+    it("url resolution fails with SOURCE_OFFLINE_REQUIRES_FETCH when offline", async () => {
+        await expect(resolveSource("https://example.com/x", "rules[0]", {
+            ...baseCtx(),
+            offline: true,
+        })).rejects.toThrow(/SOURCE_OFFLINE_REQUIRES_FETCH.*https:\/\/example\.com\/x.*rules\[0\]/);
+    });
+});
+describe("resolveSources (orchestrator)", () => {
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        rmSync(fileTmp, { recursive: true, force: true });
+        mkdirSync(fileTmp, { recursive: true });
+    });
+    it("resolves a map of Sources and returns a parallel ResolvedSource map", async () => {
+        writeFileSync(path.join(fileTmp, "a.md"), "alpha");
+        const fetchMock = vi
+            .spyOn(globalThis, "fetch")
+            .mockImplementation(async () => new Response("beta", { status: 200 }));
+        const out = await resolveSources({
+            "nodes.n.instruction": "Inline thing.",
+            "rules[0]": "./a.md",
+            "context[0]": "https://x.test/doc",
+        }, { ...baseCtx(), cwd: fileTmp });
+        expect(out["nodes.n.instruction"].content).toBe("Inline thing.");
+        expect(out["rules[0]"].content).toBe("alpha");
+        expect(out["context[0]"].content).toBe("beta");
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it("caches by canonical key: same URL referenced twice fetches once", async () => {
+        const fetchMock = vi
+            .spyOn(globalThis, "fetch")
+            .mockImplementation(async () => new Response("shared", { status: 200 }));
+        const out = await resolveSources({
+            "rules[0]": "https://x.test/shared.md",
+            "context[0]": "https://x.test/shared.md",
+        }, baseCtx());
+        expect(out["rules[0]"].content).toBe("shared");
+        expect(out["context[0]"].content).toBe("shared");
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+    it("reports the first failure's field path", async () => {
+        await expect(resolveSources({ "nodes.bad.instruction": "./does-not-exist.md" }, { ...baseCtx(), cwd: fileTmp })).rejects.toThrow(/SOURCE_FILE_NOT_FOUND.*nodes\.bad\.instruction/);
+    });
+});

package/dist/sources.validation.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Comprehensive validation tests for the unified Source type.
+ *
+ * These tests verify correctness, completeness, and best practices
+ * beyond the unit tests in sources.test.ts. They cover:
+ *   - Review fix features: retry on 5xx, BOM stripping, SOURCE_INVALID_TYPE, tagged trimming
+ *   - Edge cases: whitespace, unicode, large content, concurrent resolution
+ *   - Schema validation: sourceZ boundary cases
+ *   - Error message quality: field paths, remediation hints
+ *   - Security: no auth token leakage, URL validation
+ */
+export {};