From API Change to Verified Draft PR
A step-by-step technical breakdown of how MY OWL detects upstream breaking changes, traces affected call sites, verifies migrations, and stops at a Draft PR.
Install GitHub App & Authorize Repositories
Install the official MY OWL GitHub App and select which repositories to protect. The installation establishes an isolated workspace with cryptographic state binding.
GitHub Organization or User Account credentials with repository administration.
MY OWL generates a cryptographically signed HMAC-SHA256 state token bound to the active user session and workspace ID (15-minute TTL). The GitHub App webhook listener registers events for push and release triggers.
Authorized repository record in MY OWL database with scoped least-privilege installation credentials.
User denies permissions or state token HMAC validation expires / fails → Connection aborted.
// GitHub App Installation State Token Binding
{
"installationId": "gh_inst_4829104",
"workspaceId": "ws_alpha_prod",
"requestedScopes": ["contents:read", "pull_requests:write"],
"stateSignature": "hmac_sha256(payload, VERIFIER_SECRET)",
"status": "AUTHORIZED"
}Establish Immutable Analysis Snapshot
MY OWL reads your repository structure, discovers dependency manifests, and pins the exact 40-character Git commit SHA of your default branch as the baseline.
Target repository default branch (e.g., main or master).
Fetches repository file tree via Git transport. Resolves package manifests (package.json, lockfiles) and locks the exact HEAD commit SHA as the immutable analysis baseline.
Repository baseline snapshot with baseline commit SHA and discovered dependency catalog.
Repository is empty, contains no supported manifest, or network transport fails → Scan exits cleanly with 'unsupported' status.
// Baseline Snapshot Record
{
"repository": "acme/billing-service",
"defaultBranch": "main",
"baselineSha": "7a3f89d1b0924e3c881023a9d20c56b7104e6721",
"discoveredManifests": ["package.json"],
"treeSize": 142
}Match Upstream Breaking Change Rules
Our changelog ingestion pipeline continuously monitors vendor SDK releases, turning deprecation announcements into machine-readable AST change rules.
Discovered package dependencies vs. verified upstream vendor catalog (Stripe, Twilio).
Compares installed dependency version constraints against rule trigger ranges (e.g. stripe-node upgrade from v17.x to v18.0.0). Identifies candidate breaking changes.
List of candidate change IDs to inspect for reachability in the target codebase.
No breaking change rules match installed package versions → Scan completes with 0 findings.
// Candidate Breaking Change Rule
{
"ruleId": "stripe-v18-sub-coupon",
"provider": "stripe",
"targetPackage": "stripe",
"deprecatedParameter": "coupon",
"breakingInVersion": "18.0.0",
"severity": "breaking",
"status": "CANDIDATE_MATCH"
}Pinpoint Reachable Call Sites via AST Analysis
Instead of simplistic regex or package.json alerts, MY OWL parses TypeScript and JavaScript files into a typed Abstract Syntax Tree (AST) using ts-morph to find active call sites.
TypeScript/JavaScript source files in target repository.
Resolves import declarations, aliased identifiers, and custom client wrappers. Evaluates CallExpressions and PropertyAccessExpressions to determine whether arguments actively reference the breaking parameter.
Confirmed Finding records with exact file paths, line numbers, symbols, and code snippets. Safe/untouched invocations are filtered out.
Symbol exists in dependency but is never invoked or never passes deprecated parameters → Classified as 'Detected' but 'Unaffected'. Zero noise.
// Confirmed Reachable Finding Record
{
"findingId": "find_8f21c904",
"file": "src/billing.ts",
"line": 42,
"symbol": "stripe.subscriptions.create",
"matchedProperty": "coupon",
"reachability": "CONFIRMED_AFFECTED",
"excludedSafeCalls": 26
}Synthesize Context-Bound Migration Plan
The planning engine maps the confirmed finding to a deterministic transformation strategy, specifying the exact syntax tree modification.
Confirmed finding + matching migration rule + target source context.
Constructs a MigrationPlan defining the target AST node (PropertyAssignment), the replacement expression (discounts array), and bounding constraints.
Structured, deterministic MigrationPlan JSON artifact.
Call-site structure contains ambiguous dynamic expressions that cannot be safely transformed deterministically → Flagged for manual review.
// Structured Migration Plan
{
"planId": "plan_9f82d1c0",
"changeId": "stripe-v18-sub-coupon",
"targetFile": "src/billing.ts",
"nodeType": "PropertyAssignment",
"before": "coupon: promoCouponId",
"after": "discounts: [{ coupon: promoCouponId }]"
}Generate Deterministic Source Patch
Applies the migration plan against the exact source text, preserving original indentation, quotation style, and developer comments.
Baseline source snapshot + MigrationPlan.
Executes minimal AST rewrite. Computes unified diff and calculates a canonical SHA256 patch digest of the resulting code.
Unified patch diff and canonical patch digest bound to the baseline commit SHA.
Baseline source file has changed or digest does not match expected canonical representation → Patch generation halted.
// Unified Source Diff
@@ -40,6 +40,6 @@ export async function createSubscription(customerId: string) {
return await stripe.subscriptions.create({
customer: customerId,
- coupon: promoCouponId,
+ discounts: [{ coupon: promoCouponId }],
items: [{ price: priceId }],
});Run 4-Gate Pre-Flight Verification Harness
Before any Git branch or pull request is created, the candidate patch must pass four deterministic verification gates.
Patched codebase snapshot in isolated execution sandbox.
Gate 1: AST Syntax Validity parse. Gate 2: TypeScript compiler diagnostic check (tsc --noEmit). Gate 3: Call-site boundary constraint (verifies only allowed files & lines modified). Gate 4: Dry-run execution of repository test suite.
Cryptographically signed Verification Evidence artifact binding baseline SHA, change ID, and patch digest.
Any compiler error, diagnostic failure, patch scope violation, or test failure → Process terminates. No PR is created.
// Cryptographically Signed Verification Evidence
{
"proofLevel": "CONTRACT_VERIFIED",
"syntaxValid": true,
"typecheckPassed": true,
"scopeValid": true,
"testsPassed": true,
"evidenceDigest": "d8a9c41f7e02b489e21190bc74a3..."
}Push Isolated Branch & Open GitHub Draft PR
MY OWL enforces strict write isolation. It creates a dedicated branch with an explicit prefix (apiproof/*) and submits a GitHub Draft PR marked draft: true.
Verified patch artifact + Signed Verification Evidence.
Validates ControlledWriteRequest against write contract. Checks default branch HEAD SHA for divergence. Pushes single commit to apiproof/<change-id> and opens Draft PR via GitHub App API.
GitHub Draft Pull Request containing side-by-side diffs, migration rationale, and verification reports.
Default branch HEAD has moved since the scan was performed (REPOSITORY_HEAD_DIVERGED) → Write rejected. Fresh scan required.
// GitHub App Controlled Write Result
{
"action": "DRAFT_PR_OPENED",
"prNumber": 142,
"branch": "apiproof/stripe-v18-update",
"baseBranch": "main",
"draft": true,
"autoMerge": false
}Human Developer Review & Merge
Your engineering team retains total sovereignty. Engineers review the Draft PR, inspect automated test runs, and decide when to merge.
GitHub Draft PR #142 on your repository.
Your team conducts normal code review, runs your existing CI/CD checks, and merges the PR when ready.
Safely migrated production code with complete audit history and zero silent failures.
Engineer closes or requests changes on PR → PR closed. MY OWL records resolution status in audit log.
// Developer Sovereignty Boundary
{
"humanSignOffRequired": true,
"autoMergePermissions": "NONE",
"defaultBranchProtection": "PRESERVED",
"status": "AWAITING_TEAM_REVIEW"
}