Bump App Security trace schema version to 3

Co-authored-by: AI (Pi/Claude Opus 5.5) <noreply@pi.dev>

Author: jplhomer

packages/app/src/cli/services/app-security-api.test.ts

@@ -93,7 +93,7 @@ describe('App Security CLI integration', () => {
       expect(review.source_scan_id).toBe(result.execution.scan.scan.input_hash)
       expect(review.checks.length).toBeGreaterThan(0)
       expect(review.checks.every((check: {prompt: string}) => check.prompt.length > 0)).toBe(true)
-      expect(trace.schema_version).toBe(2)
+      expect(trace.schema_version).toBe(3)
       expect(trace.engine.name).toBe('shopify-app-security')
       expect(result.engine).toEqual(trace.engine)
       expect(result.reviewPath).toBe(artifactPath(directory, 'review.json'))
@@ -635,7 +635,7 @@ describe('App Security CLI integration', () => {
 
       const payload = JSON.parse(output.mock.calls[0]![0]) as {operation: string; trace: {schema_version: number}}
       expect(payload.operation).toBe('scan')
-      expect(payload.trace.schema_version).toBe(2)
+      expect(payload.trace.schema_version).toBe(3)
       await expect(readFile(artifactPath(directory, 'review.json'))).resolves.toContain('"checks"')
       await expect(readFile(artifactPath(directory, 'trace.json'))).resolves.toContain('"schema_version"')
       expect(setExitCode).not.toHaveBeenCalled()

packages/app/src/cli/services/app-security-artifacts.ts

@@ -1,4 +1,4 @@
-import {parseTrace, type TraceV2} from './app-security-engine/index.js'
+import {parseTrace, type TraceV3} from './app-security-engine/index.js'
 import {fileExists, fileSize, readFile} from '@shopify/cli-kit/node/fs'
 import {AbortError} from '@shopify/cli-kit/node/error'
 import {joinPath, relativePath, resolvePath} from '@shopify/cli-kit/node/path'
@@ -20,7 +20,7 @@ export interface ResolvedAppSecurityArtifactPaths extends Required<AppSecurityAr
 }
 
 export type ReadTraceResult =
-  | {status: 'ok'; trace: TraceV2}
+  | {status: 'ok'; trace: TraceV3}
   | {status: 'missing'}
   | {status: 'invalid'; errors: string[]}
 

packages/app/src/cli/services/app-security-engine/index.ts

@@ -30,4 +30,4 @@ export type {AppSecuritySubmission, AppSecuritySubmissionReport, BuildSubmission
 export type {ReviewPack} from './checks/index.js'
 export {groupIssues} from './output/group-issues.js'
 export type {IssueGroup} from './output/group-issues.js'
-export type {Capabilities, Issue, ScanResult, Severity, TraceV2} from './types.js'
+export type {Capabilities, Issue, ScanResult, Severity, TraceV3} from './types.js'

packages/app/src/cli/services/app-security-engine/run.ts

@@ -15,7 +15,7 @@ import {computeResultHash} from './scorer/index.js'
 import {compileTrace, validateTrace} from './trace/index.js'
 import {FINDINGS_SCHEMA_VERSION} from './types.js'
 import {getEngineVersion} from './version.js'
-import type {CheckExecution, ScanResult, Suppression, TraceV2} from './types.js'
+import type {CheckExecution, ScanResult, Suppression, TraceV3} from './types.js'
 
 export {AppRootDiscoveryError, findAppRoot}
 
@@ -43,7 +43,7 @@ export interface AppSecurityScan {
   operation: 'scan'
   appRoot: string
   scan: ScanResult
-  trace: TraceV2
+  trace: TraceV3
   reviewPack: ReviewPack
   engine: AppSecurityEngineMetadata
 }
@@ -52,12 +52,12 @@ export interface AppSecurityCompile {
   operation: 'compile'
   appRoot: string
   scan: ScanResult
-  trace: TraceV2
+  trace: TraceV3
   findings: AppSecurityFindings
   engine: AppSecurityEngineMetadata
 }
 
-export type ParseTraceResult = {ok: true; trace: TraceV2} | {ok: false; errors: string[]}
+export type ParseTraceResult = {ok: true; trace: TraceV3} | {ok: false; errors: string[]}
 
 /** Expected user error while reading an agent findings document. */
 export class FindingsDocumentError extends Error {
@@ -76,7 +76,7 @@ export function getAgentInstructions(): string {
 
 export function parseTrace(value: unknown): ParseTraceResult {
   const validation = validateTrace(value)
-  return validation.valid ? {ok: true, trace: value as TraceV2} : {ok: false, errors: validation.errors}
+  return validation.valid ? {ok: true, trace: value as TraceV3} : {ok: false, errors: validation.errors}
 }
 
 export function parseFindings(value: unknown): FindingsDocument {

packages/app/src/cli/services/app-security-engine/submission/index.ts

@@ -11,7 +11,7 @@ import type {
   Severity,
   SuppressionProvenance,
   TraceFinding,
-  TraceV2,
+  TraceV3,
 } from '../types.js'
 
 export const SUBMISSION_SCHEMA_VERSION = 1 as const
@@ -68,7 +68,7 @@ export interface AppSecuritySubmission {
 }
 
 export interface AppSecuritySubmissionReport {
-  trace_schema_version: TraceV2['schema_version']
+  trace_schema_version: TraceV3['schema_version']
   engine: {name: string; version: string; ruleset: string}
   cli_version: string
   generated_at: string
@@ -93,7 +93,7 @@ export interface AppSecuritySubmissionReport {
     files_scanned: number
     complete: boolean
     files_skipped: {too_large: number; unreadable: number}
-    gaps: {code: TraceV2['coverage']['gaps'][number]['code']; check_id?: string}[]
+    gaps: {code: TraceV3['coverage']['gaps'][number]['code']; check_id?: string}[]
   }
   attestation: {trace_digest: string}
 }
@@ -159,7 +159,7 @@ function submissionCheck(check: CheckExecution): SubmissionCheck {
   }
 }
 
-function skippedFileCounts(trace: TraceV2): {too_large: number; unreadable: number} {
+function skippedFileCounts(trace: TraceV3): {too_large: number; unreadable: number} {
   return trace.coverage.files_skipped.reduce(
     (counts, file) =>
       file.reason === 'too_large'
@@ -169,7 +169,7 @@ function skippedFileCounts(trace: TraceV2): {too_large: number; unreadable: numb
   )
 }
 
-export function buildSubmission(trace: TraceV2, options: BuildSubmissionOptions): AppSecuritySubmission {
+export function buildSubmission(trace: TraceV3, options: BuildSubmissionOptions): AppSecuritySubmission {
   return {
     schemaVersion: SUBMISSION_SCHEMA_VERSION,
     report: {

packages/app/src/cli/services/app-security-engine/tests/fixtures/submission-trace.ts

@@ -1,5 +1,5 @@
 import {findingFingerprint, sha256} from '../../trace/index.js'
-import type {TraceFinding, TraceV2} from '../../types.js'
+import type {TraceFinding, TraceV3} from '../../types.js'
 
 const inputHash = `sha256:${'a'.repeat(64)}`
 const privateFileHash = `sha256:${'b'.repeat(64)}`
@@ -23,7 +23,7 @@ const suppression = {
 }
 
 const traceWithLeakageSentinels = {
-  schema_version: 2,
+  schema_version: 3,
   engine: {
     name: 'shopify-app-security',
     version: '0.1.0',
@@ -221,7 +221,7 @@ function computedFindingFingerprint(finding: TraceFinding): string {
 
 // Compute every integrity field from the final semantic inputs. Unknown-field
 // sentinels are already present before the unsigned trace digest is calculated.
-const unsignedTrace = traceWithLeakageSentinels as unknown as Omit<TraceV2, 'attestation'>
+const unsignedTrace = traceWithLeakageSentinels as unknown as Omit<TraceV3, 'attestation'>
 const agentCheck = unsignedTrace.checks_executed[1]!
 const unresolvedCheck = unsignedTrace.checks_executed[4]!
 agentCheck.prompt_hash = sha256(agentCheck.prompt!)
@@ -242,4 +242,4 @@ export const submissionTraceHashes = {
 export const submissionTraceFixture = {
   ...unsignedTrace,
   attestation: {digest: submissionTraceHashes.traceDigest, signed: false},
-} as TraceV2
+} as TraceV3

packages/app/src/cli/services/app-security-engine/tests/fixtures/submission.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "report": {
-    "trace_schema_version": 2,
+    "trace_schema_version": 3,
     "engine": {
       "name": "shopify-app-security",
       "version": "0.1.0",
@@ -141,7 +141,7 @@
       "gaps": [{"code": "skipped_file"}, {"code": "unresolved_check", "check_id": "UNREPORTED_AGENT_CHECK"}]
     },
     "attestation": {
-      "trace_digest": "sha256:a5abc9a5b332ff7fb9a7afae1dd13a9af8a4fcb990d4551f63d96e3c5318507e"
+      "trace_digest": "sha256:47beaec0942e8f81a01ab97293d256be086c6426cd30c220aa3f800d6a7d19cb"
     }
   }
 }

packages/app/src/cli/services/app-security-engine/tests/scan-contract.test.ts

@@ -8,7 +8,7 @@ import {afterEach, describe, expect, test} from 'vitest'
 import {mkdir, mkdtemp, rm, writeFile} from 'node:fs/promises'
 import {tmpdir} from 'node:os'
 import {join} from 'node:path'
-import type {TraceV2} from '../types.js'
+import type {TraceV3} from '../types.js'
 
 const directories: string[] = []
 afterEach(async () => {
@@ -31,7 +31,7 @@ async function app(files: Record<string, string>): Promise<string> {
 const appConfig = (scopes = '') => `name = "Scan contract"\n[access_scopes]\nscopes = "${scopes}"\n`
 const reactPackage = JSON.stringify({dependencies: {'@shopify/shopify-app-react-router': '^1.0.0'}})
 
-function resign(trace: TraceV2): void {
+function resign(trace: TraceV3): void {
   const {attestation: _attestation, ...unsigned} = trace
   trace.attestation = {digest: sha256(unsigned), signed: false}
 }

packages/app/src/cli/services/app-security-engine/tests/trace.test.ts

@@ -86,7 +86,7 @@ describe('trace v2', () => {
     const trace = compileTrace(result(), {
       generatedAt: '2026-08-28T00:00:00.000Z',
     })
-    expect(trace.schema_version).toBe(2)
+    expect(trace.schema_version).toBe(3)
     expect(trace.engine.name).toBe('shopify-app-security')
     expect(trace.project).toMatchObject({
       commit: 'a'.repeat(40),
@@ -248,6 +248,7 @@ describe('trace v2', () => {
       generatedAt: '2026-08-28T00:00:00.000Z',
     })
     expect(validateTrace({...trace, schema_version: 1}).errors).toContain('unsupported schema_version: 1')
+    expect(validateTrace({...trace, schema_version: 2}).errors).toContain('unsupported schema_version: 2')
     const changed = structuredClone(trace)
     const [changedFinding] = changed.findings
     if (!changedFinding) throw new Error('Expected the trace to contain a finding')

packages/app/src/cli/services/app-security-engine/trace/index.ts

@@ -13,7 +13,7 @@ import type {
   Severity,
   Suppression,
   TraceFinding,
-  TraceV2,
+  TraceV3,
 } from '../types.js'
 
 const SHA256 = /^sha256:[0-9a-f]{64}$/
@@ -134,7 +134,7 @@ function issueToFinding(issueInput: Issue): TraceFinding {
   return {fingerprint: findingFingerprint(core), ...core, suppressed: false}
 }
 
-export function hasRecordedAgentReview(trace: TraceV2): boolean {
+export function hasRecordedAgentReview(trace: TraceV3): boolean {
   return (
     trace.findings.some((finding) => finding.source === 'agent' || finding.source === 'external') ||
     trace.checks_executed.some((execution) => {
@@ -156,7 +156,7 @@ export interface CompileTraceOptions {
 }
 
 /** Compile trace schema v2. Version 1 remains a separate frozen type. */
-export function compileTrace(result: ScanResult, options: CompileTraceOptions = {}): TraceV2 {
+export function compileTrace(result: ScanResult, options: CompileTraceOptions = {}): TraceV3 {
   const findings = result.issues
     .map(issueToFinding)
     .sort((left, right) =>
@@ -253,7 +253,7 @@ export function compileTrace(result: ScanResult, options: CompileTraceOptions =
       })),
     },
   }
-  const trace: TraceV2 = {...unsigned, attestation: {digest: sha256(unsigned), signed: false}}
+  const trace: TraceV3 = {...unsigned, attestation: {digest: sha256(unsigned), signed: false}}
   const validation = validateTraceValue(trace)
   if (!validation.valid) {
     // Self-compiled traces are acyclic. A complexity miss on a large app must
@@ -818,7 +818,7 @@ export function validateTrace(value: unknown): TraceValidationResult {
   }
 }
 
-export function assertCompatibleTrace(value: unknown): asserts value is TraceV2 {
+export function assertCompatibleTrace(value: unknown): asserts value is TraceV3 {
   const validation = validateTrace(value)
   if (!validation.valid) throw new Error(`Invalid App Security trace: ${validation.errors.join('; ')}`)
 }