@0xsequence/catapult 1.3.17 → 1.4.0

package/src/lib/__tests__/deployer.spec.ts

@@ -1679,7 +1679,7 @@ describe('Deployer', () => {
       const jobAResult = results.get('job-a')
       expect(jobAResult).toBeDefined()
       expect(jobAResult.outputs.get(mockNetwork1.chainId).status).toBe('skipped')
-      expect(jobAResult.outputs.get(mockNetwork1.chainId).data).toContain('skipped due to skip condition')
+      expect(jobAResult.outputs.get(mockNetwork1.chainId).data).toContain('skip_condition')
 
       // Verify that job B ran successfully
       const jobBResult = results.get('job-b')
@@ -2090,4 +2090,180 @@ describe('Deployer', () => {
       )
     })
   })
+
+  describe('skip_if functionality', () => {
+    it('should skip job when skip_if condition is true', async () => {
+      const jobWithSkipIf: Job = {
+        name: 'job-with-skip-if',
+        version: '1.0.0',
+        description: 'Job with skip_if condition',
+        skip_if: [{ type: 'contract-exists', arguments: { address: '0xabc' } }],
+        actions: [
+          { name: 'action1', template: 'template1', arguments: {} }
+        ]
+      }
+
+      mockLoader.jobs.clear()
+      mockLoader.jobs.set('job-with-skip-if', jobWithSkipIf)
+      mockGraph.getExecutionOrder.mockReturnValue(['job-with-skip-if'])
+
+      // Mock engine.evaluateSkipConditions to return true (condition met)
+      mockEngine.evaluateSkipConditions = jest.fn().mockResolvedValue(true)
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+      // Job should be skipped
+      const results = (deployer as any).results
+      const jobResult = results.get('job-with-skip-if')
+      expect(jobResult).toBeDefined()
+      expect(jobResult.outputs.get(mockNetwork1.chainId).status).toBe('skipped')
+      expect(jobResult.outputs.get(mockNetwork1.chainId).data).toContain('skip_if')
+
+      // executeJob should NOT be called for skipped job
+      expect(mockEngine.executeJob).not.toHaveBeenCalled()
+    })
+
+    it('should run job when skip_if condition is false', async () => {
+      const jobWithSkipIf: Job = {
+        name: 'job-with-skip-if-false',
+        version: '1.0.0',
+        description: 'Job with skip_if condition that is false',
+        skip_if: [{ type: 'contract-exists', arguments: { address: '0xabc' } }],
+        actions: [
+          { name: 'action1', template: 'template1', arguments: {} }
+        ]
+      }
+
+      mockLoader.jobs.clear()
+      mockLoader.jobs.set('job-with-skip-if-false', jobWithSkipIf)
+      mockGraph.getExecutionOrder.mockReturnValue(['job-with-skip-if-false'])
+
+      // Mock engine.evaluateSkipConditions to return false (condition not met)
+      mockEngine.evaluateSkipConditions = jest.fn().mockResolvedValue(false)
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+      // Job should run normally
+      const results = (deployer as any).results
+      const jobResult = results.get('job-with-skip-if-false')
+      expect(jobResult).toBeDefined()
+      expect(jobResult.outputs.get(mockNetwork1.chainId).status).toBe('success')
+
+      // executeJob should be called
+      expect(mockEngine.executeJob).toHaveBeenCalledWith(jobWithSkipIf, expect.anything())
+    })
+
+    it('should skip job when skip_if OR skip_condition is true', async () => {
+      const jobWithBoth: Job = {
+        name: 'job-with-both',
+        version: '1.0.0',
+        description: 'Job with both skip_if and skip_condition',
+        skip_condition: [{ type: 'contract-exists', arguments: { address: '0xabc' } }],
+        skip_if: [{ type: 'job-completed', arguments: { job: 'other-job' } }],
+        actions: [
+          { name: 'action1', template: 'template1', arguments: {} }
+        ]
+      }
+
+      mockLoader.jobs.clear()
+      mockLoader.jobs.set('job-with-both', jobWithBoth)
+      mockGraph.getExecutionOrder.mockReturnValue(['job-with-both'])
+
+      // Mock engine.evaluateSkipConditions to return false for skip_condition but true for skip_if
+      // The combined conditions should be evaluated together
+      mockEngine.evaluateSkipConditions = jest.fn().mockResolvedValue(true)
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+      // Job should be skipped (skip_if is true)
+      const results = (deployer as any).results
+      const jobResult = results.get('job-with-both')
+      expect(jobResult).toBeDefined()
+      expect(jobResult.outputs.get(mockNetwork1.chainId).status).toBe('skipped')
+
+      // executeJob should NOT be called
+      expect(mockEngine.executeJob).not.toHaveBeenCalled()
+    })
+
+    it('should NOT post-check skip_if after execution (only skip_condition is post-checked)', async () => {
+      // This is the key test: skip_if should NOT cause post-execution failures
+      const jobWithSkipIfOnly: Job = {
+        name: 'job-skip-if-only',
+        version: '1.0.0',
+        description: 'Job with skip_if that remains false after execution',
+        only_networks: [1], // Only run on mainnet to have predictable call count
+        skip_if: [{ type: 'contract-exists', arguments: { address: '0xabc' } }],
+        actions: [
+          { name: 'action1', template: 'template1', arguments: {} }
+        ]
+      }
+
+      mockLoader.jobs.clear()
+      mockLoader.jobs.set('job-skip-if-only', jobWithSkipIfOnly)
+      mockGraph.getExecutionOrder.mockReturnValue(['job-skip-if-only'])
+
+      // Pre-skip: skip_if is false, so job runs
+      mockEngine.evaluateSkipConditions = jest.fn().mockResolvedValue(false)
+
+      // Job runs successfully - no post-check for skip_if
+      mockEngine.executeJob = jest.fn().mockResolvedValue(undefined)
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+      // Job should succeed (no post-check failure for skip_if)
+      const results = (deployer as any).results
+      const jobResult = results.get('job-skip-if-only')
+      expect(jobResult).toBeDefined()
+      expect(jobResult.outputs.get(mockNetwork1.chainId).status).toBe('success')
+
+      // evaluateSkipConditions called once for pre-skip check (skip_if on mainnet only)
+      // skip_if is NOT post-checked, so no additional calls from engine
+      expect(mockEngine.evaluateSkipConditions).toHaveBeenCalledTimes(1)
+      // executeJob should be called once (job ran on mainnet only)
+      expect(mockEngine.executeJob).toHaveBeenCalledTimes(1)
+    })
+
+    it('should still post-check skip_condition (existing behavior unchanged)', async () => {
+      // Verify that skip_condition still gets post-checked
+      // For this test, we need to use the real ExecutionEngine behavior
+      // Since the mock doesn't easily support this, we'll verify the behavior indirectly
+      
+      // The key is that skip_condition triggers post-check in the engine,
+      // while skip_if does not. This is verified by the engine.spec.ts tests.
+      
+      const jobWithSkipCondition: Job = {
+        name: 'job-skip-condition',
+        version: '1.0.0',
+        description: 'Job with skip_condition',
+        skip_condition: [{ type: 'contract-exists', arguments: { address: '0xabc' } }],
+        actions: [
+          { name: 'action1', template: 'template1', arguments: {} }
+        ]
+      }
+
+      mockLoader.jobs.clear()
+      mockLoader.jobs.set('job-skip-condition', jobWithSkipCondition)
+      mockGraph.getExecutionOrder.mockReturnValue(['job-skip-condition'])
+
+      // Pre-skip: skip_condition is false, so job runs
+      mockEngine.evaluateSkipConditions = jest.fn().mockResolvedValue(false)
+
+      // Job runs successfully
+      mockEngine.executeJob = jest.fn().mockResolvedValue(undefined)
+
+      const deployer = new Deployer(deployerOptions)
+      await deployer.run()
+
+      // Job should succeed in this mock scenario
+      // The actual post-check behavior is tested in engine.spec.ts
+      const results = (deployer as any).results
+      const jobResult = results.get('job-skip-condition')
+      expect(jobResult).toBeDefined()
+      expect(jobResult.outputs.get(mockNetwork1.chainId).status).toBe('success')
+    })
+  })
 })

package/src/lib/__tests__/provenance.spec.ts

@@ -0,0 +1,208 @@
+import * as fs from 'fs/promises'
+import * as os from 'os'
+import * as path from 'path'
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+import {
+  collectSourceProvenanceEntries,
+  generateBuildInfoFromSourceProvenance,
+  verifySourceProvenance
+} from '../provenance'
+
+const execFileAsync = promisify(execFile)
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const result = await execFileAsync('git', args, { cwd })
+  return String(result.stdout).trim()
+}
+
+async function writeFile(filePath: string, content: string): Promise<void> {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  await fs.writeFile(filePath, content)
+}
+
+function sourceYaml(repo: string, commit: string, build: string): string {
+  return `
+type: source
+build_info:
+  "./stage1.json":
+    repo: ${JSON.stringify(repo)}
+    commit: ${JSON.stringify(commit)}
+    build: ${JSON.stringify(build)}
+`
+}
+
+function jobYaml(name: string, dependsOn: string[] = []): string {
+  const depends = dependsOn.length > 0 ? `depends_on: ${JSON.stringify(dependsOn)}\n` : ''
+  return `
+name: ${JSON.stringify(name)}
+version: "1.0.0"
+${depends}actions:
+  - name: "noop"
+    type: "static"
+    arguments:
+      value: true
+`
+}
+
+describe('source provenance operations', () => {
+  let tempDir: string
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'catapult-provenance-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true })
+  })
+
+  it('collects source provenance entries even when build-info is missing', async () => {
+    const projectRoot = path.join(tempDir, 'project')
+    const sourcePath = path.join(projectRoot, 'jobs', 'demo', 'build-info', 'source.yaml')
+    await writeFile(sourcePath, sourceYaml('https://github.com/example/repo', 'abc123', 'forge build --build-info'))
+
+    const result = await collectSourceProvenanceEntries(projectRoot)
+
+    expect(result.warnings).toEqual([])
+    expect(result.entries).toHaveLength(1)
+    expect(result.entries[0]).toMatchObject({
+      sourceDocumentPath: sourcePath,
+      buildInfoRef: './stage1.json',
+      buildInfoPath: path.join(projectRoot, 'jobs', 'demo', 'build-info', 'stage1.json')
+    })
+  })
+
+  it('can scope provenance entries to a job and its dependencies', async () => {
+    const projectRoot = path.join(tempDir, 'project')
+    await writeFile(path.join(projectRoot, 'jobs', 'base.yaml'), jobYaml('base'))
+    await writeFile(path.join(projectRoot, 'jobs', 'child.yaml'), jobYaml('child', ['base']))
+    await writeFile(path.join(projectRoot, 'jobs', 'base', 'build-info', 'source.yaml'), sourceYaml('https://github.com/example/base', 'abc123', 'build-base'))
+    await writeFile(path.join(projectRoot, 'jobs', 'child', 'build-info', 'source.yaml'), sourceYaml('https://github.com/example/child', 'def456', 'build-child'))
+
+    const childOnly = await collectSourceProvenanceEntries(projectRoot, {
+      jobs: ['child'],
+      loadStdTemplates: false
+    })
+    const withDependencies = await collectSourceProvenanceEntries(projectRoot, {
+      jobs: ['child'],
+      includeDependencies: true,
+      loadStdTemplates: false
+    })
+
+    expect(childOnly.entries.map(entry => entry.provenance.repo)).toEqual(['https://github.com/example/child'])
+    expect(withDependencies.entries.map(entry => entry.provenance.repo).sort()).toEqual([
+      'https://github.com/example/base',
+      'https://github.com/example/child'
+    ])
+  })
+
+  it('generates missing build-info from a local Git provenance repo', async () => {
+    const { projectRoot, expectedBuildInfo } = await createProjectWithLocalProvenanceRepo()
+
+    const result = await generateBuildInfoFromSourceProvenance(projectRoot)
+    const generatedPath = path.join(projectRoot, 'jobs', 'demo', 'build-info', 'stage1.json')
+    const generatedJson = JSON.parse(await fs.readFile(generatedPath, 'utf-8'))
+
+    expect(result.results).toHaveLength(1)
+    expect(result.results[0].status).toBe('generated')
+    expect(generatedJson).toEqual(expectedBuildInfo)
+  })
+
+  it('verifies generated build-info and reports mismatches', async () => {
+    const { projectRoot } = await createProjectWithLocalProvenanceRepo()
+    const targetPath = path.join(projectRoot, 'jobs', 'demo', 'build-info', 'stage1.json')
+
+    await generateBuildInfoFromSourceProvenance(projectRoot)
+    const verified = await verifySourceProvenance(projectRoot)
+    expect(verified.results[0].status).toBe('verified')
+
+    const changed = JSON.parse(await fs.readFile(targetPath, 'utf-8'))
+    changed.solcVersion = '0.8.1'
+    await fs.writeFile(targetPath, JSON.stringify(changed, null, 2))
+
+    const mismatch = await verifySourceProvenance(projectRoot)
+    expect(mismatch.results[0].status).toBe('failed')
+    expect(mismatch.results[0].message).toContain('does not match')
+    expect(mismatch.results[0].message).toContain('$.solcVersion')
+  })
+
+  it('normalizes checkout-local build-info paths and top-level ids while verifying', async () => {
+    const { projectRoot } = await createProjectWithLocalProvenanceRepo({ checkoutSensitiveBuildInfo: true })
+    const targetPath = path.join(projectRoot, 'jobs', 'demo', 'build-info', 'stage1.json')
+
+    await generateBuildInfoFromSourceProvenance(projectRoot)
+    const generatedJson = JSON.parse(await fs.readFile(targetPath, 'utf-8'))
+    expect(generatedJson.id).toContain('catapult-provenance-')
+    expect(generatedJson.input.basePath).toContain('catapult-provenance-')
+
+    const verified = await verifySourceProvenance(projectRoot)
+    expect(verified.results[0].status).toBe('verified')
+  })
+
+  async function createProjectWithLocalProvenanceRepo(
+    options: { checkoutSensitiveBuildInfo?: boolean } = {}
+  ): Promise<{ projectRoot: string; expectedBuildInfo: Record<string, unknown> }> {
+    const sourceRepo = path.join(tempDir, 'source-repo')
+    const projectRoot = path.join(tempDir, 'project')
+    await fs.mkdir(sourceRepo, { recursive: true })
+
+    const expectedBuildInfo = {
+      _format: 'hh-sol-build-info-1',
+      id: 'stage1',
+      solcVersion: '0.8.0',
+      input: {
+        language: 'Solidity',
+        sources: {}
+      },
+      output: {
+        contracts: {}
+      }
+    }
+
+    const buildInfoScript = options.checkoutSensitiveBuildInfo
+      ? `
+const fs = require('fs')
+const path = require('path')
+const buildInfo = {
+  _format: 'hh-sol-build-info-1',
+  id: path.basename(path.dirname(__dirname)),
+  solcVersion: '0.8.0',
+  input: {
+    language: 'Solidity',
+    basePath: __dirname,
+    allowPaths: [__dirname, path.join(__dirname, 'lib')],
+    includePaths: [__dirname],
+    sources: {}
+  },
+  output: {
+    contracts: {}
+  }
+}
+fs.mkdirSync(path.join(__dirname, 'out', 'build-info'), { recursive: true })
+fs.writeFileSync(path.join(__dirname, 'out', 'build-info', 'stage1.json'), JSON.stringify(buildInfo, null, 2))
+`
+      : `
+const fs = require('fs')
+const path = require('path')
+fs.mkdirSync(path.join(__dirname, 'out', 'build-info'), { recursive: true })
+fs.writeFileSync(path.join(__dirname, 'out', 'build-info', 'stage1.json'), JSON.stringify(${JSON.stringify(expectedBuildInfo)}, null, 2))
+`
+
+    await writeFile(path.join(sourceRepo, 'build-info.js'), `
+${buildInfoScript.trim()}
+`)
+    await git(sourceRepo, ['init'])
+    await git(sourceRepo, ['config', 'user.email', 'catapult@example.com'])
+    await git(sourceRepo, ['config', 'user.name', 'Catapult Test'])
+    await git(sourceRepo, ['add', 'build-info.js'])
+    await git(sourceRepo, ['commit', '-m', 'add build script'])
+    const commit = await git(sourceRepo, ['rev-parse', 'HEAD'])
+
+    await writeFile(
+      path.join(projectRoot, 'jobs', 'demo', 'build-info', 'source.yaml'),
+      sourceYaml(sourceRepo, commit, 'node build-info.js')
+    )
+
+    return { projectRoot, expectedBuildInfo }
+  }
+})

package/src/lib/contracts/__tests__/repository.spec.ts

@@ -1,7 +1,64 @@
 import * as fs from 'fs/promises'
 import * as path from 'path'
 import { ContractRepository } from '../repository'
-import { Contract } from '../../types/contracts'
+
+function buildInfoContent(): string {
+  return JSON.stringify({
+    _format: 'hh-sol-build-info-1',
+    id: 'test-build-id',
+    solcVersion: '0.8.0',
+    solcLongVersion: '0.8.0+commit.c7dfd78e',
+    input: {
+      language: 'Solidity',
+      sources: {
+        'src/Stage1Module.sol': {
+          content: 'contract Stage1Module {}'
+        },
+        'src/Stage2Module.sol': {
+          content: 'contract Stage2Module {}'
+        }
+      },
+      settings: {
+        outputSelection: {
+          '*': {
+            '*': ['abi', 'evm.bytecode', 'evm.deployedBytecode']
+          }
+        }
+      }
+    },
+    output: {
+      contracts: {
+        'src/Stage1Module.sol': {
+          Stage1Module: {
+            abi: [],
+            evm: {
+              bytecode: {
+                object: '0x608060405234801561001057600080fd5b50111111'
+              },
+              deployedBytecode: {
+                object: '0x608060405234801561001057600080fd5b50111112'
+              }
+            }
+          }
+        },
+        'src/Stage2Module.sol': {
+          Stage2Module: {
+            abi: [],
+            evm: {
+              bytecode: {
+                object: '0x608060405234801561001057600080fd5b50222222'
+              },
+              deployedBytecode: {
+                object: '0x608060405234801561001057600080fd5b50222223'
+              }
+            }
+          }
+        }
+      },
+      sources: {}
+    }
+  })
+}
 
 describe('ContractRepository', () => {
   let repository: ContractRepository
@@ -111,6 +168,217 @@ describe('ContractRepository', () => {
       expect(contract._sources.has(buildInfoPath)).toBe(true)
     })
 
+    it('should attach source provenance from build-info sidecars', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const sourcePath = path.join(buildInfoDir, 'source.yaml')
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(sourcePath, `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    ref: "v3.0.0-rc.5"
+    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
+    build: "forge build --build-info"
+    contracts:
+      "src/Stage1Module.sol:Stage1Module":
+        ref: "stage1-special"
+`)
+
+      await repository.loadFrom(tempDir)
+
+      const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+      const stage2 = repository.lookup(`${buildInfoPath}:Stage2Module`)
+
+      expect(stage1).not.toBeNull()
+      expect(stage2).not.toBeNull()
+
+      expect(stage1!.sourceProvenance).toMatchObject({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'stage1-special',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d',
+        build: 'forge build --build-info',
+        sourceDocumentPath: sourcePath,
+        buildInfoPath
+      })
+      expect(stage2!.sourceProvenance).toMatchObject({
+        repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+        ref: 'v3.0.0-rc.5',
+        commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+      })
+
+      expect(stage1!._sourceProvenance?.get(buildInfoPath)?.ref).toBe('stage1-special')
+    })
+
+    it('should skip source sidecars that point to missing build-info files', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./missing.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+`)
+
+      try {
+        await expect(repository.loadFrom(tempDir)).resolves.toBeUndefined()
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('does not exist'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip malformed source sidecars without blocking build-info loading', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    ref: "v3.0.0-rc.5"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+      } finally {
+        warnSpy.mockRestore()
+      }
+
+      const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+      expect(stage1).not.toBeNull()
+      expect(stage1!.sourceProvenance).toBeUndefined()
+    })
+
+    it('should keep valid source sidecar entries when sibling entries are invalid', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+    commit: "0d9061f229da73edae890e6fdd1fbf753028df6d"
+  "./bad.json":
+    typo_field: true
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!.sourceProvenance).toMatchObject({
+          repo: 'https://github.com/0xsequence/wallet-contracts-v3',
+          commit: '0d9061f229da73edae890e6fdd1fbf753028df6d'
+        })
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('typo_field is not supported'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip source sidecar entries that do not point to build-info JSON', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.txt":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!.sourceProvenance).toBeUndefined()
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('does not point to a build-info JSON file'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should skip duplicate source provenance entries for the same build-info file', async () => {
+      const buildInfoDir = path.join(tempDir, 'build-info', 'rc-5')
+      await fs.mkdir(buildInfoDir, { recursive: true })
+      const buildInfoPath = path.join(buildInfoDir, 'stage1.json')
+      const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+
+      await fs.writeFile(buildInfoPath, buildInfoContent())
+      await fs.writeFile(path.join(buildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-a"
+`)
+      await fs.writeFile(path.join(buildInfoDir, 'source.yml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-b"
+`)
+
+      try {
+        await repository.loadFrom(tempDir)
+
+        const stage1 = repository.lookup(`${buildInfoPath}:Stage1Module`)
+        expect(stage1).not.toBeNull()
+        expect(stage1!._sourceProvenance?.size).toBe(1)
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('duplicate provenance'))
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
+
+    it('should select preferred source provenance deterministically for duplicate bytecode', async () => {
+      const olderBuildInfoDir = path.join(tempDir, 'build-info', 'b-release')
+      const newerBuildInfoDir = path.join(tempDir, 'build-info', 'a-release')
+      await fs.mkdir(olderBuildInfoDir, { recursive: true })
+      await fs.mkdir(newerBuildInfoDir, { recursive: true })
+
+      const olderBuildInfoPath = path.join(olderBuildInfoDir, 'stage1.json')
+      const newerBuildInfoPath = path.join(newerBuildInfoDir, 'stage1.json')
+      await fs.writeFile(olderBuildInfoPath, buildInfoContent())
+      await fs.writeFile(newerBuildInfoPath, buildInfoContent())
+
+      await fs.writeFile(path.join(olderBuildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-old"
+`)
+      await fs.writeFile(path.join(newerBuildInfoDir, 'source.yaml'), `
+type: source
+build_info:
+  "./stage1.json":
+    repo: "https://github.com/0xsequence/wallet-contracts-v3-new"
+`)
+
+      await repository.loadFrom(tempDir)
+
+      const stage1 = repository.lookup(`${newerBuildInfoPath}:Stage1Module`)
+      expect(stage1).not.toBeNull()
+      expect(stage1!._sourceProvenance?.size).toBe(2)
+      expect(stage1!.sourceProvenance?.repo).toBe('https://github.com/0xsequence/wallet-contracts-v3-new')
+    })
+
     it('should hydrate contracts from multiple source files', async () => {
       // Create a basic artifact file (minimal info, will be hydrated by build-info)
       const artifactContent = JSON.stringify({
@@ -341,4 +609,4 @@ describe('ContractRepository', () => {
       expect(contracts).toHaveLength(0)
     })
   })
-})
+})