Learning pathsPricingChecking sign-in…
← ML curriculum

AISD-001 · WORKED SYSTEM DESIGN

AI coding assistant with repository context and safe tool execution

Design a repository-aware AI coding assistant that explains code, retrieves commit-accurate context, proposes reviewable patches, validates them in isolated execution and performs repository writes only after explicit, server-enforced approval. Synthetic workload assumptions are stated separately from measured production facts.

Authored for interview education; independent technical review pending. Workload numbers are synthetic assumptions. This chapter does not deploy a Git provider connector, OAuth app, database migration, code index, LLM service or sandbox..

Practice this design before reading →

Prerequisites and scoped previews

Events, identity and data contracts

Define keys, event/ingestion/availability times, schema evolution, dedupe and permitted use.

Candidate retrieval and ANN indexes

Separate eligible-corpus recall from latency/memory and filtering effects.

Calibration, uncertainty and decision thresholds

Distinguish score quality from calibrated probabilities, uncertainty and action capacity.

What, when, why and how

Repository state is commit-scoped

what
Every code citation and patch is tied to a repository and immutable commit/blob identity.
when
Whenever an index, branch, patch or workspace can change during a task.
why
Branch names move; stale context can overwrite newer developer work.
how
Record base SHA and blob SHAs, validate before hydration and use compare-and-swap before writes.

Code retrieval is hybrid and structural

what
Symbol graphs, lexical search, dependency/test lookup and semantic retrieval complement one another.
when
For code navigation, bug localization and cross-file change planning.
why
Embeddings alone miss exact identifiers, call relationships and language semantics.
how
Fuse candidate sources, expand references, preserve line provenance and verify against Git.

Retrieved code is untrusted input

what
Repository text can contain malicious instructions, secrets or unsafe scripts.
when
At ingestion, retrieval, prompt assembly and tool execution.
why
Prompt injection must not turn data into authority or leak credentials.
how
Keep policy outside the model, delimit repository data, scan secrets and gate every capability.

Patch generation is a proposal

what
The model creates an immutable diff bound to expected file versions.
when
Before any workspace or remote repository mutation.
why
Direct model writes make review, conflict detection and rollback difficult.
how
Validate patch paths and blob SHAs, apply in an ephemeral workspace and show exact diff.

Sandbox execution limits blast radius

what
Build and test commands run in short-lived isolated compute with explicit resource and network policy.
when
Running repository-controlled scripts or dependency installation.
why
A repository may execute arbitrary code during build/test.
how
Use ephemeral containers/microVMs, no ambient secrets, egress controls, quotas and cleanup leases.

Approval is a server-enforced boundary

what
User confirmation is bound to a specific patch, repository, branch and base SHA.
when
Before pushing commits, creating PRs or performing other side effects.
why
A model's statement that a user approved is not authorization.
how
Persist approval against patch hash and reauthorize immediately before compare-and-swap write.

Evaluate verified changes, not generated text

what
Quality includes semantic correctness, test evidence, safe execution and accepted outcomes.
when
Comparing models, prompts, retrieval, parsers or rollout cohorts.
why
A plausible diff or benchmark score can still introduce regressions or security issues.
how
Use hidden tests, human review, security slices, provenance checks and post-merge outcomes.

Frame the coding assistant

Design an assistant that explains, navigates and proposes changes in a developer's repository. It must understand repository state without treating retrieved code or model output as trusted instructions.

Synthetic interview assumptions: 20,000 active developers, 2,000 peak concurrent sessions, 30 repository operations/s, 8-second p95 first useful response for interactive chat, 90-second p95 for bounded edit/test tasks. These are design inputs, not measured production data.

Define trust boundaries and invariants

The repository, branch, user identity, workspace, tool permissions and execution environment are separate trust domains. A prompt or retrieved README cannot grant permission. Repository content is untrusted data and may contain prompt injection, secrets or malicious build scripts.

Core invariants: every operation is bound to an authenticated principal, tenant, repository and immutable base commit; reads and writes are separately authorized; execution is isolated; proposed patches are not applied until policy and user approval pass; every side effect is auditable and idempotent.

Connect repositories with least privilege

Use provider OAuth or an installation app with narrowly scoped permissions. Resolve repository membership and branch protections server-side. Issue short-lived installation/user tokens to a connector broker; never send long-lived credentials to the model or sandbox.

A read-only task receives contents and metadata access only. A patch task receives a server-side capability for a specific repository, branch and base SHA. Write/PR permissions are separate capabilities and expire with the task.

Build and refresh a repository index

Index repository structure, symbol definitions/references, dependency manifests, tests, docs and commit metadata. Store immutable snapshots keyed by repository ID, commit SHA, parser version and embedding model version. Preserve file path, line range, blob SHA and language metadata.

Use a full baseline scan for a new repository, then consume webhook events and compare tree/blob SHAs. Reconcile missed webhooks periodically. Do not assume branch name identifies immutable content.

VISUAL WALKTHROUGH

See the system in motion

Follow a commit webhook through incremental parsing, symbol extraction and immutable index publication.

Process overviewAvailable even when interactive playback cannot load.
  1. Receive commit event and verify repository installation.

  2. Resolve immutable commit and tree SHAs.

  3. Parse changed blobs and update symbol graph.

  4. Reconcile missed events and stale snapshots.

  5. Run index smoke checks.

  6. Publish the snapshot generation atomically.

Loading interactive walkthrough…

Retrieve code with structure and provenance

Route requests into symbol search, lexical search, dependency/test lookup and dense semantic retrieval. Combine candidates with reciprocal-rank fusion, expand symbol references and cap file/line context. Verify every returned range against the selected commit SHA before hydration.

A stale index is a retrieval hint, not authority. If a blob SHA no longer matches the requested base commit, re-resolve from Git or restart retrieval against the new snapshot.

VISUAL WALKTHROUGH

See the system in motion

Combine exact symbol, lexical, dependency and semantic search, then verify every source span against the pinned commit.

Process overviewAvailable even when interactive playback cannot load.
  1. Pin repository and base commit.

  2. Run symbol and lexical retrieval.

  3. Run dense retrieval in parallel.

  4. Fuse, deduplicate and expand references.

  5. Verify blob SHAs and line ranges.

  6. Return provenance-bearing candidates.

Loading interactive walkthrough…

Assemble bounded repository context

Build a context manifest containing repository, base commit, file blob SHAs, line ranges, retrieval scores, tool outputs and prompt version. Deduplicate overlapping ranges, preserve imports and surrounding control flow, and allocate tokens across task instructions, code, tests and history.

Treat code comments, issues, docs and tool output as untrusted. Delimit them as data; never concatenate them into privileged system instructions. Redact secrets before model context and record omissions.

VISUAL WALKTHROUGH

See the system in motion

Build a token-bounded context manifest with exact file provenance and untrusted repository text clearly separated.

Process overviewAvailable even when interactive playback cannot load.
  1. Collect verified code spans.

  2. Deduplicate overlapping ranges.

  3. Preserve imports and control flow.

  4. Redact detected secrets.

  5. Allocate token budget.

  6. Record prompt and context manifest versions.

Loading interactive walkthrough…

Turn intent into a reviewable patch plan

Ask clarifying questions when the target behavior, acceptance criteria or scope is ambiguous. Produce a plan with files to inspect, invariants, expected edits, tests and risk classification before generating a diff.

The planner may propose paths and operations, but a deterministic policy service validates path allowlists, repository scope, file size, binary/generated files, protected branches and task limits.

Generate structured patches, not arbitrary writes

Prefer a unified diff or structured edit operation bound to base commit and expected blob SHA. Validate syntax, path traversal, duplicate paths, binary payloads, patch size and hunk applicability before storing the candidate patch.

A patch is immutable and versioned. If a file changed after retrieval, reject the stale hunk and rebase/retrieve rather than silently overwriting the user's newer work.

VISUAL WALKTHROUGH

See the system in motion

Turn a model-proposed edit into an immutable, validated diff bound to expected blob SHAs.

Process overviewAvailable even when interactive playback cannot load.
  1. Create a scoped edit plan.

  2. Generate unified diff.

  3. Reject path traversal and disallowed files.

  4. Verify expected blob SHAs.

  5. Apply to ephemeral workspace.

  6. Persist immutable patch hash.

Loading interactive walkthrough…

Run tools in an isolated workspace

Create an ephemeral workspace from an immutable repository snapshot. Execute commands in a container or microVM with CPU, memory, disk, wall-clock and process limits; deny ambient credentials and restrict egress by default.

Network access is an explicit capability. Dependency installation uses approved mirrors/cache; arbitrary postinstall scripts are disabled or isolated. Never mount the developer's host filesystem or provider token into the sandbox.

Validate changes with deterministic checks

Run formatting, type checks, targeted tests and relevant integration suites based on a policy-selected test plan. Capture command, exit code, duration, resource use, logs and artifact hashes. Parse failures into evidence for a bounded repair attempt.

A passing test suite is evidence, not proof. Keep static analysis, security scans and human review distinct. Cap repair iterations and stop when context becomes stale or the task budget is exhausted.

Separate proposal, approval and repository write

Show the exact diff, affected files, test evidence and requested permissions. Require explicit user approval before pushing a branch or opening a pull request; protected branch rules remain authoritative.

Before write, reauthorize the user, verify base SHA and branch head, and use compare-and-swap semantics. If the branch advanced, create a conflict result and ask for rebase/review instead of force-pushing.

VISUAL WALKTHROUGH

See the system in motion

Bind approval to the exact patch, reauthorize the principal and compare-and-swap the remote branch head.

Process overviewAvailable even when interactive playback cannot load.
  1. Present exact diff and test evidence.

  2. Obtain explicit user approval.

  3. Bind approval to patch hash and base SHA.

  4. Reauthorize repository write scope.

  5. Compare expected branch head.

  6. Create branch/commit/PR idempotently.

Loading interactive walkthrough…

Persist task state and recover safely

Model task lifecycle as queued, indexing, planning, patching, validating, awaiting approval, writing, completed, failed or cancelled. Persist checkpoints, immutable patch references, sandbox lease, budget and idempotency key.

A worker lease prevents concurrent mutation. On crash, recover from the last durable checkpoint; expire abandoned sandboxes and revoke capabilities. Duplicate webhook or retry events must not create duplicate branches or pull requests.

Evaluate usefulness, correctness and safety

Measure task success against a hidden acceptance suite, patch applicability, test pass rate, regression rate, localization quality, citation/provenance correctness, security-policy violations, user acceptance and time-to-verified-change.

Use repository- and language-stratified holdouts. Human review remains the gold standard for semantic correctness. Avoid optimizing only for benchmark pass rate or generated diff volume.

Estimate retrieval, model and sandbox capacity

Assume 2,000 concurrent sessions, 30 tool operations/s and 90-second bounded edit jobs. At 30 jobs/s × 90 seconds, Little's Law implies about 2,700 active or queued execution slots at saturation; admission control must cap concurrency well below unbounded queue growth.

Separate interactive read/chat pools from CPU-heavy sandbox jobs. Apply per-tenant concurrency, token and spend quotas; queue patch/test jobs with deadlines, priority and cancellation. Autoscale workers from queue age and utilization, not request rate alone.

Trace the complete coding-assistant architecture

The online path authenticates the developer, resolves repository and commit scope, retrieves verified code context, creates a constrained patch, executes validation in an isolated sandbox and waits for approval before any repository write. The indexing plane continuously publishes immutable commit snapshots.

The final walkthrough includes stale-index recovery, sandbox failure, policy denial, test failure, approval and compare-and-swap write behavior. Model output never bypasses the capability broker.

Design for adversarial and partial failure

Handle revoked OAuth grants, repository deletion, branch movement, missed webhooks, poisoned repository instructions, secret detection, dependency compromise, sandbox timeout, flaky tests, model/provider outage and duplicate write retries.

Fail closed for authorization and secrets; fall back to read-only explanation when write capability is unavailable. Preserve candidate patches and evidence for recovery, but never claim a write or test succeeded without authoritative confirmation.

Roll out safely and learn from outcomes

Start with read-only explain/search, then opt-in patch proposals, sandbox validation, and finally explicit branch/PR creation. Use tenant allowlists, feature flags, per-task budgets and staged language/repository cohorts.

Canary model, prompt, parser, embedding and index versions independently. Compare quality and safety slices; rollback a version without deleting immutable task evidence. Retain audit data according to tenant policy.

Compare alternatives and close the design

A hosted code-search index improves latency but adds freshness and permission complexity. On-demand Git reads are fresher but slower and rate-limited. Containers are cheaper to operate; microVMs provide stronger isolation for hostile builds. Human approval reduces automation but protects high-impact writes.

Do not start with autonomous multi-agent coding. A bounded planner plus deterministic tools, isolated execution and explicit approval is easier to reason about, test and recover.

Data model, schema and relationships

Logical schema for repository snapshots, exact code provenance, durable assistant tasks, immutable patch proposals, isolated execution, approval and idempotent remote writes.

Implementation boundary: Educational architecture contract only; no live Git provider integration, database migration, OAuth installation or sandbox service is deployed.

These are proposed logical schemas with field contracts, not executable database migrations. PK identifies a row, FK references an existing parent, UK is a uniqueness rule. A composite PK identifies the combination. Nullable references are marked with ?. A foreign key protects identity; cross-row limits, timing and state transitions also require the transaction rules below.

Repository: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

Repository relationshipsrepository 1 to repo_snapshot 0..*: Commit snapshots. repo_snapshot.repository_id. repository 1 to task 0..*: Assistant tasks. task.repository_id.Commit snapshots1 parent · 0..* childrenRepository snapshotid [PK]repository_idcommit_shaAssistant tasks1 parent · 0..* childrenAssistant taskid [PK]principal_idrepository_idRepositoryid [PK]provider_repo_idtenant_id
Repository snapshot: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

Repository snapshot relationshipsrepo_snapshot 1 to file_blob 0..*: Snapshot files. file_blob.snapshot_id.Snapshot files1 parent · 0..* childrenFile blobid [PK]snapshot_idpathRepository snapshotid [PK]repository_idcommit_sha
File blob: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

File blob relationshipsfile_blob 1 to symbol 0..*: Parsed symbols. symbol.file_blob_id.Parsed symbols1 parent · 0..* childrenSymbolid [PK]file_blob_idqualified_nameFile blobid [PK]snapshot_idpath
Assistant task: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

Assistant task relationshipstask 1 to context_manifest 0..*: Context manifests. context_manifest.task_id. task 1 to patch 0..*: Candidate patches. patch.task_id. task 1 to approval 0..*: Approvals. approval.task_id.Context manifests1 parent · 0..* childrenContext manifestid [PK]task_idsnapshot_idCandidate patches1 parent · 0..* childrenCandidate patchid [PK]task_idbase_commit_shaApprovals1 parent · 0..* childrenApprovalid [PK]task_idpatch_sha256Assistant taskid [PK]principal_idrepository_id
Assistant task: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

Assistant task relationshipstask 1 to repository_write 0..*: Repository writes. repository_write.task_id.Repository writes1 parent · 0..* childrenRepository writeid [PK]task_ididempotency_keyAssistant taskid [PK]principal_idrepository_id
Candidate patch: relationship map

Connectors name the relationship; multiplicities state parents per child and children per parent. 0..1 means optional, 1 required, 0..* any number. Self-links show two roles of the same entity.

Candidate patch relationshipspatch 1 to sandbox_run 0..*: Sandbox runs. sandbox_run.patch_id.Sandbox runs1 parent · 0..* childrenSandbox runid [PK]task_idpatch_idCandidate patchid [PK]task_idbase_commit_sha

Entity definitions and field contracts

Repository

Provider-scoped repository identity.

FieldType / keyMeaning and reference
idopaque_id · PKid for repository.
provider_repo_idstring · UNIQUEprovider_repo_id for repository.
tenant_idopaque_id · VALUEtenant_id for repository.
default_branchstring · VALUEdefault_branch for repository.

Code mapping: Logical architecture schema; not an installed migration.

    Repository snapshot

    Immutable tree snapshot at a commit.

    FieldType / keyMeaning and reference
    idopaque_id · PKid for repo_snapshot.
    repository_idopaque_id · FKrepository_id for repo_snapshot.
    commit_shastring · VALUEcommit_sha for repo_snapshot.
    parser_versionstring · VALUEparser_version for repo_snapshot.
    index_generationstring · VALUEindex_generation for repo_snapshot.

    Code mapping: Logical architecture schema; not an installed migration.

      File blob

      Versioned file content reference.

      FieldType / keyMeaning and reference
      idopaque_id · PKid for file_blob.
      snapshot_idopaque_id · FKsnapshot_id for file_blob.
      pathstring · VALUEpath for file_blob.
      blob_shastring · VALUEblob_sha for file_blob.
      languagestring · VALUElanguage for file_blob.

      Code mapping: Logical architecture schema; not an installed migration.

        Symbol

        Parsed definition/reference with source span.

        FieldType / keyMeaning and reference
        idopaque_id · PKid for symbol.
        file_blob_idopaque_id · FKfile_blob_id for symbol.
        qualified_namestring · VALUEqualified_name for symbol.
        kindenum · VALUEkind for symbol.
        start_lineinteger · VALUEstart_line for symbol.
        end_lineinteger · VALUEend_line for symbol.

        Code mapping: Logical architecture schema; not an installed migration.

          Assistant task

          Durable task and policy scope.

          FieldType / keyMeaning and reference
          idopaque_id · PKid for task.
          principal_idopaque_id · VALUEprincipal_id for task.
          repository_idopaque_id · FKrepository_id for task.
          base_commit_shastring · VALUEbase_commit_sha for task.
          statusenum · VALUEstatus for task.
          idempotency_keystring · UNIQUEidempotency_key for task.

          Code mapping: Logical architecture schema; not an installed migration.

            Context manifest

            Exact evidence supplied to the model.

            FieldType / keyMeaning and reference
            idopaque_id · PKid for context_manifest.
            task_idopaque_id · FKtask_id for context_manifest.
            snapshot_idopaque_id · FKsnapshot_id for context_manifest.
            evidence_refsjson · VALUEevidence_refs for context_manifest.
            prompt_versionstring · VALUEprompt_version for context_manifest.

            Code mapping: Logical architecture schema; not an installed migration.

              Candidate patch

              Immutable proposed diff.

              FieldType / keyMeaning and reference
              idopaque_id · PKid for patch.
              task_idopaque_id · FKtask_id for patch.
              base_commit_shastring · VALUEbase_commit_sha for patch.
              patch_sha256string · VALUEpatch_sha256 for patch.
              statusenum · VALUEstatus for patch.

              Code mapping: Logical architecture schema; not an installed migration.

                Sandbox run

                Isolated command execution evidence.

                FieldType / keyMeaning and reference
                idopaque_id · PKid for sandbox_run.
                task_idopaque_id · FKtask_id for sandbox_run.
                patch_idopaque_id · FKpatch_id for sandbox_run.
                image_digeststring · VALUEimage_digest for sandbox_run.
                statusenum · VALUEstatus for sandbox_run.
                expires_attimestamp · VALUEexpires_at for sandbox_run.

                Code mapping: Logical architecture schema; not an installed migration.

                  Approval

                  User confirmation bound to exact patch.

                  FieldType / keyMeaning and reference
                  idopaque_id · PKid for approval.
                  task_idopaque_id · FKtask_id for approval.
                  patch_sha256string · VALUEpatch_sha256 for approval.
                  principal_idopaque_id · VALUEprincipal_id for approval.
                  approved_attimestamp · VALUEapproved_at for approval.

                  Code mapping: Logical architecture schema; not an installed migration.

                    Repository write

                    Idempotent branch/commit/PR side effect.

                    FieldType / keyMeaning and reference
                    idopaque_id · PKid for repository_write.
                    task_idopaque_id · FKtask_id for repository_write.
                    idempotency_keystring · UNIQUEidempotency_key for repository_write.
                    expected_head_shastring · VALUEexpected_head_sha for repository_write.
                    result_refstring? · VALUEresult_ref for repository_write.
                    statusenum · VALUEstatus for repository_write.

                    Code mapping: Logical architecture schema; not an installed migration.

                      Relationship cardinalities and their reasons

                      Parent → childMultiplicityFK / why
                      repo_snapshot → file_blob

                      Snapshot files

                      1 parent per child; 0..* children per parentfile_blob.snapshot_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      file_blob → symbol

                      Parsed symbols

                      1 parent per child; 0..* children per parentsymbol.file_blob_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      repository → repo_snapshot

                      Commit snapshots

                      1 parent per child; 0..* children per parentrepo_snapshot.repository_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      repository → task

                      Assistant tasks

                      1 parent per child; 0..* children per parenttask.repository_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      task → context_manifest

                      Context manifests

                      1 parent per child; 0..* children per parentcontext_manifest.task_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      task → patch

                      Candidate patches

                      1 parent per child; 0..* children per parentpatch.task_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      patch → sandbox_run

                      Sandbox runs

                      1 parent per child; 0..* children per parentsandbox_run.patch_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      task → approval

                      Approvals

                      1 parent per child; 0..* children per parentapproval.task_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      task → repository_write

                      Repository writes

                      1 parent per child; 0..* children per parentrepository_write.task_id

                      The child record is scoped to one parent; multiple immutable revisions and attempts remain auditable.

                      Transaction boundaries

                      1. Task creation persists principal, tenant, repository, immutable base commit, policy scope and idempotency key before enqueue.
                      2. Snapshot publication advances the active index generation only after parser, symbol, provenance and retrieval smoke checks pass.
                      3. Patch acceptance verifies expected blob SHAs and stores the immutable patch hash before sandbox execution.
                      4. Approval is recorded against the exact patch hash and base commit; it cannot be reused for a changed diff.
                      5. Repository write reauthorizes the principal and compares expected branch head before creating a commit or pull request.

                      Indexes and uniqueness

                      1. UNIQUE(provider_repo_id) on repository.
                      2. UNIQUE(repository_id, commit_sha, parser_version, index_generation) on repo_snapshot.
                      3. UNIQUE(snapshot_id, path, blob_sha) on file_blob.
                      4. INDEX(file_blob_id, qualified_name) on symbol.
                      5. UNIQUE(idempotency_key) on task and repository_write.
                      6. INDEX(task_id, status, created_at) for task recovery and queue scheduling.

                      Schema traps and failure cases

                      1. Revoked provider access blocks new reads and writes; cached content follows tenant retention and deletion policy.
                      2. Missed webhook is repaired by periodic tree/blob reconciliation.
                      3. Stale blob SHA rejects patch application and triggers re-retrieval against the requested base commit.
                      4. Sandbox timeout expires the lease and records partial logs; retry starts from an immutable snapshot.
                      5. Approval for a changed patch hash is invalid; branch movement causes compare-and-swap conflict.
                      6. Duplicate write retries return the existing repository_write result rather than creating a second PR.

                      Trace the records through one operation

                      1. Developer asks to fix a null dereference; identity and repository membership are verified and the task is pinned to commit C1.
                      2. Hybrid retrieval finds the handler, call sites and tests; every file range is verified against C1 and stored in a context manifest.
                      3. The model proposes a diff; policy validates paths and expected blob SHAs, then an ephemeral workspace applies it.
                      4. Sandbox runs targeted tests and static checks; failures feed one bounded repair attempt with the same task budget.
                      5. Developer reviews the exact patch and test evidence, approves its hash, and the broker reauthorizes before compare-and-swap branch/PR creation.
                      6. If the branch moved or sandbox failed, the task preserves evidence and returns a conflict/retry state without silently overwriting changes.

                      Diagrams and relationships

                      Indexing and freshness plane

                      A full baseline scan is followed by commit/webhook-driven incremental indexing; immutable snapshots are published only after parser and symbol checks.

                      Scroll horizontally on smaller screens, or enlarge the diagram.

                      Indexing and freshness planeA full baseline scan is followed by commit/webhook-driven incremental indexing; immutable snapshots are published only after parser and symbol checks. Git provider to Webhook + reconcile: commit events. Webhook + reconcile to Parser + symbol graph: tree/blob SHAs. Parser + symbol graph to Lexical + vector index: symbols + chunks. Parser + symbol graph to Commit snapshot: provenance. Lexical + vector index to Validated generation: validated. Commit snapshot to Validated generation: atomic manifest.commit eventstree/blob SHAssymbols + chunksprovenancevalidatedatomic manifestGit providerWebhook + reconcileParser + symbol graphLexical + vector indexCommit snapshotValidated generation
                      Indexing and freshness planeA full baseline scan is followed by commit/webhook-driven incremental indexing; immutable snapshots are published only after parser and symbol checks. Git provider to Webhook + reconcile: commit events. Webhook + reconcile to Parser + symbol graph: tree/blob SHAs. Parser + symbol graph to Lexical + vector index: symbols + chunks. Parser + symbol graph to Commit snapshot: provenance. Lexical + vector index to Validated generation: validated. Commit snapshot to Validated generation: atomic manifest.commit eventstree/blob SHAssymbols + chunksprovenancevalidatedatomic manifestGit providerWebhook + reconcileParser + symbol graphLexical + vector indexCommit snapshotValidated generation
                      Online retrieval and context assembly

                      The query path verifies every evidence range against the immutable base commit before model context is built.

                      Scroll horizontally on smaller screens, or enlarge the diagram.

                      Online retrieval and context assemblyThe query path verifies every evidence range against the immutable base commit before model context is built. Developer request to Identity + repo policy: task. Identity + repo policy to Hybrid + symbol retrieval: authorized scope. Hybrid + symbol retrieval to Commit/blob verifier: candidate ranges. Commit/blob verifier to Context manifest: verified spans. Context manifest to LLM planner: bounded context.taskauthorized scopecandidate rangesverified spansbounded contextDeveloper requestIdentity + repo policyHybrid + symbol retrievalCommit/blob verifierContext manifestLLM planner
                      Online retrieval and context assemblyThe query path verifies every evidence range against the immutable base commit before model context is built. Developer request to Identity + repo policy: task. Identity + repo policy to Hybrid + symbol retrieval: authorized scope. Hybrid + symbol retrieval to Commit/blob verifier: candidate ranges. Commit/blob verifier to Context manifest: verified spans. Context manifest to LLM planner: bounded context.taskauthorized scopecandidate rangesverified spansbounded contextDeveloper requestIdentity + repo policyHybrid + symbol retrievalCommit/blob verifierContext manifestLLM planner
                      Patch validation and approval boundary

                      Candidate patches are applied to an ephemeral snapshot, validated, then shown to the user before a separately authorized write.

                      Scroll horizontally on smaller screens, or enlarge the diagram.

                      Patch validation and approval boundaryCandidate patches are applied to an ephemeral snapshot, validated, then shown to the user before a separately authorized write. Patch proposal to Patch policy: untrusted diff. Patch policy to Isolated sandbox: validated patch. Isolated sandbox to Tests + scanners: execution evidence. Tests + scanners to Diff + approval: results. Diff + approval to CAS repository write: approved hash.untrusted diffvalidated patchexecution evidenceresultsapproved hashPatch proposalPatch policyIsolated sandboxTests + scannersDiff + approvalCAS repository write
                      Patch validation and approval boundaryCandidate patches are applied to an ephemeral snapshot, validated, then shown to the user before a separately authorized write. Patch proposal to Patch policy: untrusted diff. Patch policy to Isolated sandbox: validated patch. Isolated sandbox to Tests + scanners: execution evidence. Tests + scanners to Diff + approval: results. Diff + approval to CAS repository write: approved hash.untrusted diffvalidated patchexecution evidenceresultsapproved hashPatch proposalPatch policyIsolated sandboxTests + scannersDiff + approvalCAS repository write
                      Durable task state machine

                      A task can recover from a worker crash without repeating a non-idempotent repository side effect.

                      Scroll horizontally on smaller screens, or enlarge the diagram.

                      Durable task state machineA task can recover from a worker crash without repeating a non-idempotent repository side effect. Queued to Planning: lease. Planning to Patch ready: plan. Patch ready to Validating: sandbox. Validating to Await approval: passed. Await approval to Written / complete: approved + CAS.leaseplansandboxpassedapproved + CASQueuedPlanningPatch readyValidatingAwait approvalWritten / complete
                      Durable task state machineA task can recover from a worker crash without repeating a non-idempotent repository side effect. Queued to Planning: lease. Planning to Patch ready: plan. Patch ready to Validating: sandbox. Validating to Await approval: passed. Await approval to Written / complete: approved + CAS.leaseplansandboxpassedapproved + CASQueuedPlanningPatch readyValidatingAwait approvalWritten / complete

                      Engineer, Senior and Staff follow-ups

                      These are teaching lenses. Each answer changes the scope of reasoning; they are not official employer leveling criteria.

                      Engineer: Why not send the whole repository to the model?

                      Context windows, cost, latency and privacy make this wasteful. More importantly, whole-repository dumps lose precise provenance and can include unrelated secrets. Use structural/lexical/semantic retrieval with commit-pinned spans and a context manifest.

                      Engineer: How do you prevent a prompt injection in a README from invoking a shell command?

                      Repository text is data, not authority. The model cannot call a raw shell directly; a policy broker validates typed tool requests against task scope. Sandbox capabilities are independently constrained and network access is denied unless explicitly granted.

                      Senior: How do you handle an index that is behind the branch head?

                      Pin each task to a base commit. If the active index snapshot does not cover that SHA, perform bounded on-demand retrieval or wait for indexing; verify blob SHAs before context assembly. Never cite a stale range as current.

                      Senior: What happens if a developer edits a file while the assistant is generating a patch?

                      The patch records expected blob SHAs. Application rejects mismatches and re-reads the changed file. The assistant regenerates a patch against the new base; it must not overwrite unreviewed developer edits.

                      Senior: How do you isolate untrusted build scripts?

                      Use an ephemeral container or microVM with resource quotas, no host mounts or ambient credentials, read-only base snapshot, writable scratch overlay and deny-by-default egress. Treat dependency installation as code execution.

                      Staff: How would you support thousands of repositories without a single hot index?

                      Partition by tenant and repository, shard immutable snapshots, route retrieval by repo/snapshot ID, and use per-tenant concurrency and storage quotas. Separate interactive retrieval from sandbox pools. Reconcile event gaps and monitor queue age, freshness lag and hot-repository skew.

                      Staff: How do you prove the assistant is safe and useful?

                      Evaluate task completion on hidden tests and human-reviewed patches, plus policy violations, secret exposure, sandbox escapes, unauthorized reads/writes, regression rate and user acceptance. Slice by language, repository size, task type and permission level; block rollout on safety regressions.

                      Practice and self-review

                      Your practice draft

                      Design an AI coding assistant for a multi-tenant developer platform. It must answer repository questions and propose safe changes across large repositories. Explain indexing, retrieval, context provenance, patching, sandboxing, approval, recovery, evaluation and capacity.

                      Saved locally on this device. The worked answer does not score your draft. Existing lesson notes and completion are separate.

                      Progressive hints

                      Hint 1

                      Start by pinning every task to an authenticated principal, repository and immutable base commit.

                      Hint 2

                      Separate repository indexing and online retrieval; combine symbol/lexical/semantic search and verify blob SHAs.

                      Hint 3

                      Treat model output as an untrusted patch proposal. Use an isolated sandbox and deterministic policy broker.

                      Hint 4

                      Bind approval to the exact patch hash, reauthorize, and compare-and-swap the branch head before writing.

                      Reveal worked answer guidance

                      A strong design uses a provider connector with short-lived scoped capabilities; an event-driven indexer publishes immutable commit snapshots; a retrieval service combines symbol, lexical and dense search; a context builder records exact source spans; an LLM proposes a patch; a policy broker validates it; an ephemeral sandbox runs tests and scanners; the user approves the exact diff; and a write broker reauthorizes and uses compare-and-swap against the branch head. Durable task state and idempotency make retries safe. Read-only explanation remains available when write policy or sandbox execution is unavailable.

                      Evidence to check in your answer

                      • Identity, tenant, repository and commit scope are explicit.
                      • Index freshness, webhook reconciliation and exact source provenance are addressed.
                      • Prompt injection, secrets and untrusted repository code are handled.
                      • Patch paths/blob SHAs are validated and writes are approval-gated.
                      • Sandbox has resource and network isolation with no ambient credentials.
                      • Retries, cancellation, idempotency and branch conflicts are recoverable.
                      • Quality, safety, latency and cost are measured separately.

                      For each item, record Missing, Prompted, Independent or Adaptive evidence. Adaptive means you can revise the reasoning under a changed constraint. Reading completion and readiness are separate.

                      Sources and verification scope

                      Original synthetic examples and reference calculations. Sources support narrowly scoped background; they do not establish production performance or independent chapter review.

                      Primary background links checked during authoring on 2026-10-19. Arithmetic, temporal eligibility, maturity and split reference functions are checked by the bounded local fixture suite. SQL is explanatory, not a migrated production query. No GPU, external dataset, model API or training job is required.