@veewo/gitnexus 1.5.0 → 1.5.1

package/dist/core/ingestion/unity-runtime-binding-rules.js

@@ -1,5 +1,6 @@
 import { generateId } from '../../lib/utils.js';
 const RULE_EDGE_CONFIDENCE = 0.75;
+const RULE_ANOMALY_PREVIEW_LIMIT = 5;
 export function applyUnityRuntimeBindingRules(graph, rules, config) {
     const ruleResults = [];
     let totalEdges = 0;
@@ -54,6 +55,24 @@ export function applyUnityRuntimeBindingRules(graph, rules, config) {
         else if (rel.type === 'UNITY_COMPONENT_INSTANCE')
             componentInstances.push(rel);
     }
+    const prefabSourceTargetsBySource = buildPrefabSourceTargetsBySource(assetGuidRefs);
+    const methodsByResourceId = buildMethodsByResourceId(componentInstances, methodsByClassId);
+    const executionState = {
+        methodsByResourceId,
+        resourceMethodLookupCache: new Map(),
+        sceneRuntimeResourceIdsCache: new Map(),
+        diagnostics: {
+            rulesEvaluated: rules.length,
+            bindingsEvaluated: 0,
+            bindingsByKind: {},
+            methodLookupCalls: 0,
+            methodLookupCacheHits: 0,
+            sceneRuntimeTraversalCalls: 0,
+            sceneRuntimeTraversalCacheHits: 0,
+            sceneRuntimeResourcesVisited: 0,
+            anomalySet: new Set(),
+        },
+    };
     // Pre-build scene file index: lowercase scene name → fileId[]
     const sceneFilesByName = new Map();
     for (const node of graph.iterNodes()) {
@@ -70,7 +89,10 @@ export function applyUnityRuntimeBindingRules(graph, rules, config) {
     for (const rule of rules) {
         let ruleEdges = 0;
         for (const binding of rule.resource_bindings ?? []) {
-            ruleEdges += processBinding(binding, rule.id, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, addSyntheticEdge);
+            executionState.diagnostics.bindingsEvaluated += 1;
+            executionState.diagnostics.bindingsByKind[binding.kind] =
+                (executionState.diagnostics.bindingsByKind[binding.kind] || 0) + 1;
+            ruleEdges += processBinding(binding, rule.id, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, prefabSourceTargetsBySource, executionState, addSyntheticEdge);
         }
         if (rule.lifecycle_overrides?.additional_entry_points?.length) {
             ruleEdges += processLifecycleOverrides(rule, methodsByClassId, containerNodes, addSyntheticEdge);
@@ -78,43 +100,58 @@ export function applyUnityRuntimeBindingRules(graph, rules, config) {
         totalEdges += ruleEdges;
         ruleResults.push({ ruleId: rule.id, edgesInjected: ruleEdges });
     }
-    return { edgesInjected: totalEdges, ruleResults };
+    return {
+        edgesInjected: totalEdges,
+        ruleResults,
+        diagnostics: finalizeRuleBindingDiagnostics(executionState.diagnostics, totalEdges),
+    };
 }
-function findMethodsOnResource(resourceFileId, componentInstances, methodsByClassId, entryPoints) {
-    const results = [];
+function findMethodsOnResource(resourceFileId, executionState, entryPoints) {
+    executionState.diagnostics.methodLookupCalls += 1;
+    const cacheKey = `${resourceFileId}::${entryPoints.join('|')}`;
+    const cached = executionState.resourceMethodLookupCache.get(cacheKey);
+    if (cached) {
+        executionState.diagnostics.methodLookupCacheHits += 1;
+        return cached;
+    }
+    const methods = executionState.methodsByResourceId.get(resourceFileId) ?? [];
+    if (methods.length === 0) {
+        executionState.resourceMethodLookupCache.set(cacheKey, []);
+        return [];
+    }
     const entrySet = new Set(entryPoints);
-    for (const ci of componentInstances) {
-        if (ci.targetId !== resourceFileId)
-            continue;
-        const classId = ci.sourceId;
-        for (const method of methodsByClassId.get(classId) ?? []) {
-            if (entrySet.has(method.properties.name))
-                results.push(method);
-        }
+    const results = [];
+    for (const method of methods) {
+        if (entrySet.has(method.properties.name))
+            results.push(method);
     }
+    executionState.resourceMethodLookupCache.set(cacheKey, results);
     return results;
 }
-function processBinding(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, addEdge) {
+function processBinding(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, prefabSourceTargetsBySource, executionState, addEdge) {
     if (binding.kind === 'asset_ref_loads_components') {
-        return processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, addEdge);
+        return processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, executionState, addEdge);
     }
     if (binding.kind === 'method_triggers_field_load') {
-        return processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, addEdge);
+        return processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, executionState, addEdge);
     }
     if (binding.kind === 'method_triggers_scene_load') {
-        return processMethodTriggersSceneLoad(binding, ruleId, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, addEdge);
+        return processMethodTriggersSceneLoad(binding, ruleId, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, prefabSourceTargetsBySource, executionState, addEdge);
     }
     if (binding.kind === 'method_triggers_method') {
         return processMethodTriggersMethod(binding, ruleId, methodsByClassId, containerNodes, addEdge);
     }
+    addAnomaly(executionState.diagnostics, `rule=${ruleId}: unsupported resource_binding kind "${binding.kind}"`);
     return 0;
 }
-function processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, addEdge) {
+function processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, executionState, addEdge) {
     let count = 0;
     const pattern = binding.ref_field_pattern ? new RegExp(binding.ref_field_pattern) : null;
     const entryPoints = binding.target_entry_points ?? [];
-    if (!pattern || entryPoints.length === 0)
+    if (!pattern || entryPoints.length === 0) {
+        addAnomaly(executionState.diagnostics, `rule=${ruleId}: asset_ref_loads_components missing ref_field_pattern or target_entry_points`);
         return 0;
+    }
     const runtimeRootId = generateId('Method', 'unity-runtime-root');
     for (const ref of assetGuidRefs) {
         let fieldName = '';
@@ -127,7 +164,7 @@ function processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, componen
         }
         if (!pattern.test(fieldName))
             continue;
-        const targetMethods = findMethodsOnResource(ref.targetId, componentInstances, methodsByClassId, entryPoints);
+        const targetMethods = findMethodsOnResource(ref.targetId, executionState, entryPoints);
         for (const method of targetMethods) {
             if (addEdge(runtimeRootId, method.id, `unity-rule-resource-load:${ruleId}`))
                 count++;
@@ -135,15 +172,17 @@ function processAssetRefLoadsComponents(binding, ruleId, assetGuidRefs, componen
     }
     return count;
 }
-function processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, addEdge) {
+function processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componentInstances, methodsByClassId, containerNodes, executionState, addEdge) {
     let count = 0;
     const classPattern = binding.host_class_pattern ? new RegExp(binding.host_class_pattern) : null;
     const loaderMethodNames = new Set(binding.loader_methods ?? []);
     const entryPoints = binding.target_entry_points ?? [];
     const defaultEntryPoints = ['OnEnable', 'Awake', 'Start'];
     const resolvedEntryPoints = entryPoints.length > 0 ? entryPoints : defaultEntryPoints;
-    if (!classPattern || loaderMethodNames.size === 0)
+    if (!classPattern || loaderMethodNames.size === 0) {
+        addAnomaly(executionState.diagnostics, `rule=${ruleId}: method_triggers_field_load missing host_class_pattern or loader_methods`);
         return 0;
+    }
     // Build asset ref index by source file
     const refsBySource = new Map();
     for (const ref of assetGuidRefs) {
@@ -167,7 +206,7 @@ function processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componen
         // Follow asset refs from those resource files
         for (const resourceFileId of resourceFileIds) {
             for (const ref of refsBySource.get(resourceFileId) ?? []) {
-                const targetMethods = findMethodsOnResource(ref.targetId, componentInstances, methodsByClassId, resolvedEntryPoints);
+                const targetMethods = findMethodsOnResource(ref.targetId, executionState, resolvedEntryPoints);
                 for (const loader of loaders) {
                     for (const target of targetMethods) {
                         if (addEdge(loader.id, target.id, `unity-rule-loader-bridge:${ruleId}`))
@@ -179,7 +218,7 @@ function processMethodTriggersFieldLoad(binding, ruleId, assetGuidRefs, componen
     }
     return count;
 }
-function processMethodTriggersSceneLoad(binding, ruleId, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, addEdge) {
+function processMethodTriggersSceneLoad(binding, ruleId, componentInstances, methodsByClassId, containerNodes, sceneFilesByName, prefabSourceTargetsBySource, executionState, addEdge) {
     const classPattern = binding.host_class_pattern ? new RegExp(binding.host_class_pattern) : null;
     const loaderMethodNames = new Set(binding.loader_methods ?? []);
     const sceneName = binding.scene_name;
@@ -187,11 +226,15 @@ function processMethodTriggersSceneLoad(binding, ruleId, componentInstances, met
     const entryPoints = (binding.target_entry_points ?? []).length > 0
         ? binding.target_entry_points
         : defaultEntryPoints;
-    if (!classPattern || loaderMethodNames.size === 0 || !sceneName)
+    if (!classPattern || loaderMethodNames.size === 0 || !sceneName) {
+        addAnomaly(executionState.diagnostics, `rule=${ruleId}: method_triggers_scene_load missing host_class_pattern, loader_methods, or scene_name`);
         return 0;
+    }
     const sceneFileIds = sceneFilesByName.get(sceneName.toLowerCase()) ?? [];
-    if (sceneFileIds.length === 0)
+    if (sceneFileIds.length === 0) {
+        addAnomaly(executionState.diagnostics, `rule=${ruleId}: scene "${sceneName}" not found in File(.unity) index`);
         return 0;
+    }
     let count = 0;
     for (const cls of containerNodes) {
         if (!classPattern.test(cls.properties.name))
@@ -201,17 +244,81 @@ function processMethodTriggersSceneLoad(binding, ruleId, componentInstances, met
         if (loaders.length === 0)
             continue;
         for (const sceneFileId of sceneFileIds) {
-            const targetMethods = findMethodsOnResource(sceneFileId, componentInstances, methodsByClassId, entryPoints);
-            for (const loader of loaders) {
-                for (const target of targetMethods) {
-                    if (addEdge(loader.id, target.id, `unity-rule-scene-load:${ruleId}`))
-                        count++;
+            const runtimeResourceIds = getSceneRuntimeResourceIds(sceneFileId, prefabSourceTargetsBySource, executionState);
+            for (const runtimeResourceId of runtimeResourceIds) {
+                const targetMethods = findMethodsOnResource(runtimeResourceId, executionState, entryPoints);
+                for (const loader of loaders) {
+                    for (const target of targetMethods) {
+                        if (addEdge(loader.id, target.id, `unity-rule-scene-load:${ruleId}`))
+                            count++;
+                    }
                 }
             }
         }
     }
     return count;
 }
+function buildMethodsByResourceId(componentInstances, methodsByClassId) {
+    const methodsByResourceId = new Map();
+    for (const componentRef of componentInstances) {
+        const methods = methodsByClassId.get(componentRef.sourceId) ?? [];
+        if (methods.length === 0)
+            continue;
+        const list = methodsByResourceId.get(componentRef.targetId) ?? [];
+        list.push(...methods);
+        methodsByResourceId.set(componentRef.targetId, list);
+    }
+    return methodsByResourceId;
+}
+function buildPrefabSourceTargetsBySource(assetGuidRefs) {
+    const targetsBySource = new Map();
+    for (const ref of assetGuidRefs) {
+        let fieldName = '';
+        try {
+            const parsed = JSON.parse(String(ref.reason || '{}'));
+            fieldName = String(parsed?.fieldName || '');
+        }
+        catch {
+            continue;
+        }
+        if (fieldName !== 'm_SourcePrefab')
+            continue;
+        const targets = targetsBySource.get(ref.sourceId) ?? new Set();
+        targets.add(ref.targetId);
+        targetsBySource.set(ref.sourceId, targets);
+    }
+    const out = new Map();
+    for (const [sourceId, targets] of targetsBySource.entries()) {
+        out.set(sourceId, [...targets]);
+    }
+    return out;
+}
+function collectSceneRuntimeResourceIds(sceneFileId, prefabSourceTargetsBySource) {
+    const visited = new Set([sceneFileId]);
+    const queue = [sceneFileId];
+    while (queue.length > 0) {
+        const currentId = queue.shift();
+        for (const targetId of prefabSourceTargetsBySource.get(currentId) ?? []) {
+            if (visited.has(targetId))
+                continue;
+            visited.add(targetId);
+            queue.push(targetId);
+        }
+    }
+    return [...visited];
+}
+function getSceneRuntimeResourceIds(sceneFileId, prefabSourceTargetsBySource, executionState) {
+    executionState.diagnostics.sceneRuntimeTraversalCalls += 1;
+    const cached = executionState.sceneRuntimeResourceIdsCache.get(sceneFileId);
+    if (cached) {
+        executionState.diagnostics.sceneRuntimeTraversalCacheHits += 1;
+        return cached;
+    }
+    const ids = collectSceneRuntimeResourceIds(sceneFileId, prefabSourceTargetsBySource);
+    executionState.sceneRuntimeResourceIdsCache.set(sceneFileId, ids);
+    executionState.diagnostics.sceneRuntimeResourcesVisited += ids.length;
+    return ids;
+}
 function processMethodTriggersMethod(binding, ruleId, methodsByClassId, containerNodes, addEdge) {
     const { source_class_pattern, source_method, target_class_pattern, target_method } = binding;
     if (!source_class_pattern || !source_method || !target_class_pattern || !target_method)
@@ -258,3 +365,44 @@ function processLifecycleOverrides(rule, methodsByClassId, containerNodes, addEd
     }
     return count;
 }
+function addAnomaly(diagnostics, message) {
+    diagnostics.anomalySet.add(message);
+}
+function finalizeRuleBindingDiagnostics(diagnostics, edgesInjected) {
+    const anomalies = [...diagnostics.anomalySet];
+    const shouldAgentReport = anomalies.length > 0;
+    const bindingsByKind = Object.fromEntries(Object.entries(diagnostics.bindingsByKind).sort(([a], [b]) => a.localeCompare(b)));
+    const kindSummary = Object.entries(bindingsByKind)
+        .map(([kind, count]) => `${kind}=${count}`)
+        .join(', ') || 'none';
+    const summary = [
+        `rule_binding.summary: rules=${diagnostics.rulesEvaluated}, bindings=${diagnostics.bindingsEvaluated}, edges=${edgesInjected}`,
+        `rule_binding.bindings_by_kind: ${kindSummary}`,
+        `rule_binding.lookup: method_calls=${diagnostics.methodLookupCalls}, cache_hits=${diagnostics.methodLookupCacheHits}`,
+        `rule_binding.scene_closure: traversals=${diagnostics.sceneRuntimeTraversalCalls}, cache_hits=${diagnostics.sceneRuntimeTraversalCacheHits}, visited_resources=${diagnostics.sceneRuntimeResourcesVisited}`,
+        `rule_binding.agent_report: should_report=${shouldAgentReport} reason="${shouldAgentReport ? 'rule-binding anomalies detected' : 'no anomalies detected'}"`,
+    ];
+    if (anomalies.length > 0) {
+        summary.push(`rule_binding.anomalies: count=${anomalies.length}`);
+        for (const anomaly of anomalies.slice(0, RULE_ANOMALY_PREVIEW_LIMIT)) {
+            summary.push(`rule_binding.anomaly: ${anomaly}`);
+        }
+        if (anomalies.length > RULE_ANOMALY_PREVIEW_LIMIT) {
+            summary.push(`rule_binding.anomaly: ... ${anomalies.length - RULE_ANOMALY_PREVIEW_LIMIT} more`);
+        }
+    }
+    return {
+        rulesEvaluated: diagnostics.rulesEvaluated,
+        bindingsEvaluated: diagnostics.bindingsEvaluated,
+        bindingsByKind,
+        methodLookupCalls: diagnostics.methodLookupCalls,
+        methodLookupCacheHits: diagnostics.methodLookupCacheHits,
+        sceneRuntimeTraversalCalls: diagnostics.sceneRuntimeTraversalCalls,
+        sceneRuntimeTraversalCacheHits: diagnostics.sceneRuntimeTraversalCacheHits,
+        sceneRuntimeResourcesVisited: diagnostics.sceneRuntimeResourcesVisited,
+        anomalies,
+        shouldAgentReport,
+        agentReportReason: shouldAgentReport ? 'rule-binding anomalies detected' : 'no anomalies detected',
+        summary,
+    };
+}

package/dist/core/lbug/csv-generator.test.js

@@ -1,8 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
 import { FileContentCache, toCodeElementCsvRow } from './csv-generator.js';
-test('FileContentCache evicts oldest entries when byte budget is exceeded', async () => {
-    const cache = new FileContentCache('/tmp/repo', 10);
+test('FileContentCache evicts oldest entries when max entry count is exceeded', async () => {
+    const cache = new FileContentCache('/tmp/repo', 1);
     cache.setForTest('a.cs', '123456');
     cache.setForTest('b.cs', '123456');
     assert.equal(cache.hasForTest('a.cs'), false);

package/dist/core/unity/doc-contract.test.d.ts

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

package/dist/core/unity/doc-contract.test.js

@@ -0,0 +1,30 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const gitnexusRoot = path.resolve(here, '../../..');
+const repoRoot = path.resolve(gitnexusRoot, '..');
+test('scan-context carrier contract matches code and docs', async () => {
+    const bindingDoc = await fs.readFile(path.join(repoRoot, 'UNITY_RESOURCE_BINDING.md'), 'utf-8');
+    const ssot = await fs.readFile(path.join(repoRoot, 'docs/unity-runtime-process-source-of-truth.md'), 'utf-8');
+    const design = await fs.readFile(path.join(repoRoot, 'docs/plans/2026-04-10-prefab-source-streaming-consumption-memory-optimization-design.md'), 'utf-8');
+    const scanContextCode = await fs.readFile(path.join(gitnexusRoot, 'src/core/unity/scan-context.ts'), 'utf-8');
+    const processorCode = await fs.readFile(path.join(gitnexusRoot, 'src/core/ingestion/unity-resource-processor.ts'), 'utf-8');
+    const pipelineCode = await fs.readFile(path.join(gitnexusRoot, 'src/core/ingestion/pipeline.ts'), 'utf-8');
+    assert.match(bindingDoc, /scan-context.*承载器|resource signal carrier|scan-context.*carrier/i);
+    assert.match(bindingDoc, /streaming delivery|incremental consumption/i);
+    assert.match(ssot, /As-Built[\s\S]*Design Direction/i);
+    assert.match(ssot, /scan-context[\s\S]*does not write graph/i);
+    assert.match(ssot, /统一消费点契约/i);
+    assert.match(design, /scan-context[\s\S]*(统一消费|unified consumer)/i);
+    assert.match(scanContextCode, /streamPrefabSourceRefs/);
+    assert.match(processorCode, /streamPrefabSourceRefs\(/);
+    assert.match(processorCode, /emitPrefabSourceGuidRefsFromScanContext/);
+    assert.doesNotMatch(processorCode, /emitPrefabSourceGuidRefs\(/);
+    assert.doesNotMatch(scanContextCode, /addRelationship\(/);
+    assert.ok(pipelineCode.indexOf('processUnityResources(') >= 0
+        && pipelineCode.indexOf('applyUnityLifecycleSyntheticCalls(') >= 0
+        && pipelineCode.indexOf('processUnityResources(') < pipelineCode.indexOf('applyUnityLifecycleSyntheticCalls('));
+});

package/dist/core/unity/prefab-source-scan.d.ts

@@ -0,0 +1,25 @@
+export interface PrefabSourceScanRow {
+    sourceResourcePath: string;
+    targetGuid: string;
+    targetResourcePath?: string;
+    fileId?: string;
+    fieldName: 'm_SourcePrefab';
+    sourceLayer: 'scene' | 'prefab';
+}
+export interface StreamPrefabSourceRefsInput {
+    repoRoot: string;
+    resourceFiles: string[];
+    assetGuidToPath: Map<string, string>;
+    queue?: {
+        enabled?: boolean;
+        maxDepth?: number;
+    };
+    hooks?: {
+        onFileOpen?: (resourcePath: string) => void;
+        onYield?: (row: PrefabSourceScanRow) => void;
+        onQueueDepth?: (depth: number) => void;
+        onFileError?: (resourcePath: string, error: unknown) => void;
+    };
+}
+export declare function collectPrefabSourceRefs(args: StreamPrefabSourceRefsInput): Promise<PrefabSourceScanRow[]>;
+export declare function streamPrefabSourceRefs(args: StreamPrefabSourceRefsInput): AsyncGenerator<PrefabSourceScanRow>;

package/dist/core/unity/prefab-source-scan.js

@@ -0,0 +1,152 @@
+import { createReadStream } from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+const PREFAB_INSTANCE_PATTERN = /^\s*PrefabInstance:\s*$/;
+const YAML_OBJECT_BOUNDARY_PATTERN = /^\s*---\s*!u!\d+\s+&/;
+const SOURCE_PREFAB_LINE_PATTERN = /m_SourcePrefab\s*:\s*\{[^}]*fileID\s*:\s*([^,\s}]+)[^}]*guid\s*:\s*([0-9a-fA-F]{32})[^}]*\}/;
+const ZERO_GUID = '00000000000000000000000000000000';
+export async function collectPrefabSourceRefs(args) {
+    const rows = [];
+    for await (const row of streamPrefabSourceRefs(args)) {
+        rows.push(row);
+    }
+    return rows;
+}
+export async function* streamPrefabSourceRefs(args) {
+    const resources = [...new Set((args.resourceFiles || []).map((value) => normalizePath(value)))]
+        .filter((value) => value.endsWith('.unity') || value.endsWith('.prefab'));
+    if (!args.queue?.enabled) {
+        for await (const row of streamPrefabSourceRefsSequential(resources, args)) {
+            yield row;
+        }
+        return;
+    }
+    const maxDepth = Math.max(1, Number(args.queue.maxDepth || 64));
+    const queue = [];
+    const waitingReaders = [];
+    const waitingWriters = [];
+    let producerDone = false;
+    let producerError;
+    const notifyDepth = () => args.hooks?.onQueueDepth?.(queue.length);
+    const push = async (row) => {
+        while (queue.length >= maxDepth) {
+            await new Promise((resolve) => waitingWriters.push(resolve));
+        }
+        if (waitingReaders.length > 0) {
+            const resolveReader = waitingReaders.shift();
+            resolveReader(row);
+            return;
+        }
+        queue.push(row);
+        notifyDepth();
+    };
+    const shift = async () => {
+        if (queue.length > 0) {
+            const value = queue.shift();
+            notifyDepth();
+            const resolveWriter = waitingWriters.shift();
+            if (resolveWriter)
+                resolveWriter();
+            return value;
+        }
+        if (producerDone) {
+            return null;
+        }
+        return await new Promise((resolve) => waitingReaders.push(resolve));
+    };
+    const finishReaders = () => {
+        while (waitingReaders.length > 0) {
+            const resolveReader = waitingReaders.shift();
+            resolveReader(null);
+        }
+    };
+    const finishWriters = () => {
+        while (waitingWriters.length > 0) {
+            const resolveWriter = waitingWriters.shift();
+            resolveWriter();
+        }
+    };
+    const producer = (async () => {
+        try {
+            for await (const row of streamPrefabSourceRefsSequential(resources, args)) {
+                await push(row);
+            }
+        }
+        catch (error) {
+            producerError = error;
+        }
+        finally {
+            producerDone = true;
+            finishReaders();
+            finishWriters();
+        }
+    })();
+    while (true) {
+        const row = await shift();
+        if (!row)
+            break;
+        yield row;
+    }
+    await producer;
+    if (producerError) {
+        throw producerError;
+    }
+}
+async function* streamPrefabSourceRefsSequential(resources, args) {
+    const hooks = args.hooks;
+    for (const resourcePath of resources) {
+        hooks?.onFileOpen?.(resourcePath);
+        const absolutePath = path.join(args.repoRoot, resourcePath);
+        const stream = createReadStream(absolutePath, { encoding: 'utf-8' });
+        const reader = createInterface({
+            input: stream,
+            crlfDelay: Infinity,
+        });
+        try {
+            let inPrefabInstance = false;
+            for await (const line of reader) {
+                if (YAML_OBJECT_BOUNDARY_PATTERN.test(line)) {
+                    inPrefabInstance = false;
+                }
+                if (PREFAB_INSTANCE_PATTERN.test(line)) {
+                    inPrefabInstance = true;
+                    continue;
+                }
+                if (!inPrefabInstance)
+                    continue;
+                const match = line.match(SOURCE_PREFAB_LINE_PATTERN);
+                if (!match)
+                    continue;
+                const fileId = String(match[1] || '').trim();
+                const guid = String(match[2] || '').trim().toLowerCase();
+                if (!guid || guid === ZERO_GUID)
+                    continue;
+                const targetResourcePath = normalizePath(args.assetGuidToPath.get(guid) || args.assetGuidToPath.get(guid.toLowerCase()) || '');
+                if (!targetResourcePath || !targetResourcePath.endsWith('.prefab'))
+                    continue;
+                const row = {
+                    sourceResourcePath: resourcePath,
+                    targetGuid: guid,
+                    targetResourcePath,
+                    fileId: fileId || undefined,
+                    fieldName: 'm_SourcePrefab',
+                    sourceLayer: resourcePath.endsWith('.unity') ? 'scene' : 'prefab',
+                };
+                hooks?.onYield?.(row);
+                yield row;
+                inPrefabInstance = false;
+            }
+        }
+        catch (error) {
+            hooks?.onFileError?.(resourcePath, error);
+            continue;
+        }
+        finally {
+            reader.close();
+            stream.destroy();
+        }
+    }
+}
+function normalizePath(value) {
+    return String(value || '').replace(/\\/g, '/').trim();
+}

package/dist/core/unity/prefab-source-scan.test.d.ts

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

package/dist/core/unity/prefab-source-scan.test.js

@@ -0,0 +1,70 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { streamPrefabSourceRefs } from './prefab-source-scan.js';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const fixtureRoot = path.resolve(here, '../../../src/core/unity/__fixtures__/mini-unity');
+const assetGuidToPath = new Map([['99999999999999999999999999999999', 'Assets/Prefabs/BattleMode.prefab']]);
+const scopedFiles = ['Assets/Scene/MainUIManager.unity', 'Assets/Prefabs/BattleMode.prefab'];
+test('same source can yield prefab-source rows while script-guid flow remains independent', async () => {
+    const rows = [];
+    for await (const row of streamPrefabSourceRefs({
+        repoRoot: fixtureRoot,
+        resourceFiles: ['Assets/Scene/MainUIManager.unity'],
+        assetGuidToPath,
+    })) {
+        rows.push(row);
+    }
+    assert.ok(rows.length > 0);
+    assert.equal(rows.every((r) => r.fieldName === 'm_SourcePrefab'), true);
+});
+test('streamPrefabSourceRefs does not open second file before first row is yielded', async () => {
+    const probe = [];
+    const iterator = streamPrefabSourceRefs({
+        repoRoot: fixtureRoot,
+        resourceFiles: scopedFiles,
+        assetGuidToPath,
+        hooks: {
+            onFileOpen: (filePath) => probe.push(`open:${filePath}`),
+            onYield: () => probe.push('yield'),
+        },
+    })[Symbol.asyncIterator]();
+    const first = await iterator.next();
+    assert.equal(first.done, false);
+    assert.equal(first.value.fieldName, 'm_SourcePrefab');
+    assert.equal(probe.includes('open:Assets/Prefabs/BattleMode.prefab'), false);
+    await iterator.return?.(undefined);
+});
+test('producer rows are immutable snapshots (consumer mutation does not backflow)', async () => {
+    for await (const row of streamPrefabSourceRefs({
+        repoRoot: fixtureRoot,
+        resourceFiles: scopedFiles,
+        assetGuidToPath,
+    })) {
+        const copy = { ...row };
+        copy.targetResourcePath = '__PLACEHOLDER__';
+    }
+    const again = [];
+    for await (const row of streamPrefabSourceRefs({
+        repoRoot: fixtureRoot,
+        resourceFiles: scopedFiles,
+        assetGuidToPath,
+    })) {
+        again.push(row);
+    }
+    assert.equal(again.some((r) => r.targetResourcePath === '__PLACEHOLDER__'), false);
+});
+test('bounded queue backpressure never exceeds configured depth when decoupled mode is enabled', async () => {
+    const depthSamples = [];
+    for await (const _row of streamPrefabSourceRefs({
+        repoRoot: fixtureRoot,
+        resourceFiles: scopedFiles,
+        assetGuidToPath,
+        queue: { enabled: true, maxDepth: 64 },
+        hooks: { onQueueDepth: (depth) => depthSamples.push(depth) },
+    })) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+    assert.equal(depthSamples.every((depth) => depth <= 64), true);
+});

package/dist/core/unity/scan-context.d.ts

@@ -1,3 +1,4 @@
+import type { StreamPrefabSourceRefsInput } from './prefab-source-scan.js';
 import type { UnityResourceGuidHit } from './resource-hit-scanner.js';
 import type { UnityObjectBlock } from './yaml-object-graph.js';
 import type { UnityParitySeed } from '../ingestion/unity-parity-seed.js';
@@ -10,6 +11,14 @@ export interface UnitySymbolDeclaration {
     symbol: string;
     scriptPath: string;
 }
+export interface UnityPrefabSourceRef {
+    sourceResourcePath: string;
+    targetGuid: string;
+    targetResourcePath?: string;
+    fileId?: string;
+    fieldName: 'm_SourcePrefab';
+    sourceLayer: 'scene' | 'prefab';
+}
 export interface UnityScanContext {
     symbolToScriptPaths: Map<string, string[]>;
     symbolToCanonicalScriptPath: Map<string, string>;
@@ -21,6 +30,9 @@ export interface UnityScanContext {
     assetGuidToPath?: Map<string, string>;
     uxmlGuidToPath?: Map<string, string>;
     ussGuidToPath?: Map<string, string>;
+    prefabSourceRefs: UnityPrefabSourceRef[];
+    streamPrefabSourceRefs: (options?: Pick<StreamPrefabSourceRefsInput, 'queue' | 'hooks'>) => AsyncIterable<UnityPrefabSourceRef>;
+    resourceFiles: string[];
     resourceDocCache: Map<string, UnityObjectBlock[]>;
 }
 export declare function buildUnityScanContext(input: BuildScanContextInput): Promise<UnityScanContext>;