Your Enterprise Knowledge Graph,
populated automatically.

Section 2 · v1 mandatory probes

Four concrete probes ship in v1. CXO Sales

The end-of-v1 demo is the Probe Analyzer running these four probes against the live Arcitopsia production stack and producing an Enterprise Knowledge Graph rich enough to generate a complete, traceable Solution Architecture Document about Arcitopsia itself — the dogfood acceptance contract (§24).

Section 4 · Probe Analyzer

A six-phase wizard turns "we have lots of tools" into a deterministic execution plan. Architect

Probes work best when the platform already knows which systems are authoritative for which facts. The Probe Analyzer captures that upfront, runs a shallow discovery sweep to validate scope, and produces a stage-ordered DAG of which probes to run, with which targets, in what sequence, and where parallelism is safe.

flowchart LR
    A["A · Inventory
What systems
do you have?"]:::phase
    Ap["A' · Connect
Map systems to
ConnectorInstance"]:::phase
    B["B · Source-of-Truth
Pick primary source
per FactCategory"]:::phase
    Bp["B' · EA Content
Pre-Probe + Package
Gap Analysis"]:::phase
    C["C · Discovery Sweep
Shallow probes
~30-120s"]:::phase
    D["D · Plan Generation
Pure function
topological sort"]:::phase
    E["E · Approve & Run
Credit reservation
+ ProbeExecutionRun"]:::phase

    A --> Ap --> B --> Bp --> C --> D --> E

    classDef phase fill:#161616,stroke:#a3e635,stroke-width:1.5px,color:#e5e5e5,font-family:JetBrains Mono;
                

Canonical probe DAG

flowchart TB
    subgraph S0["Stage 0 · Foundation"]
        HR[HRProbe]:::s0
        ID[IdentityProbe]:::s0
        CO[CloudOrgProbe]:::s0
        VC[VCSOrgProbe]:::s0
    end
    subgraph S1["Stage 1 · System Scanning"]
        SC[SourceCodeProbe]:::s1
        IN[InfrastructureProbe]:::s1
        DP[DataPlatformOrgProbe]:::s1
        CI[CI_CDProbe]:::s1
    end
    subgraph S2["Stage 2 · Detail Scanning"]
        DA[DataProbe]:::s2
        OB[ObservabilityProbe]:::s2
        DO[DocumentProbe]:::s2
    end
    subgraph S3["Stage 3 · Analytical / Derived"]
        PM[PatternMatchProbe]:::s3
        GA[GapAnalysisProbe]:::s3
        HS[HierarchySynthesisProbe]:::s3
    end
    subgraph S4["Stage 4 · Generative"]
        BG[BacklogGenerationWorkflow]:::s4
        DG[DocDraftGenerationWorkflow]:::s4
    end

    HR --> SC
    ID --> SC
    CO --> IN
    VC --> SC
    SC --> DA
    IN --> DA
    DP --> DA
    SC --> OB
    IN --> OB
    SC --> DO
    DA --> PM
    DA --> GA
    DA --> HS
    PM --> DG
    GA --> BG
    HS --> DG

    classDef s0 fill:#0d1a0d,stroke:#a3e635,color:#fff;
    classDef s1 fill:#1e2a3a,stroke:#38bdf8,color:#fff;
    classDef s2 fill:#3b2e1a,stroke:#fbbf24,color:#fff;
    classDef s3 fill:#3b0764,stroke:#c084fc,color:#fff;
    classDef s4 fill:#3f1d1d,stroke:#fb7185,color:#fff;
                

Section 6 · Library-First Doctrine

LLM tokens are economics, not magic. Most extraction is library work. Architect CXO

Every ProbeStageDefinition declares extractionStrategy ∈ {LIBRARY, LLM, HYBRID, COMPUTED}. LLM strategy without a justification (whyLlm) fails package validation. Plan-review surfaces the library coverage ratio; anything below 70% earns a yellow warning.

Tooling catalogue (v1 bundled)

When LLM is justified (v1)

• Ownership inference when CODEOWNERS / tags exhausted (§3.2 step 5)
• Identity resolution / dedup across naming-divergent systems (§15 #4)
• EA artefact drafting — no library writes a "Postgres Standards" document (§14, §15 #6)
• One-line semantic descriptors for routines / classes / endpoints
• Anomaly natural-language synthesis (library detects; LLM phrases)
• Document summarisation (Tika extracts text; only LLM produces summary)

Section 8 · Publication policy

Auto-publish or human-review is policy-driven, not a single boolean. Architect

A DBA running the DataProbe should auto-publish discovered table metadata but must review newly drafted stored-procedure semantic summaries. ProbeDefinition.publicationPolicyKey references a PublicationPolicy row; each policy carries an ordered rule list (first-match wins).

Worked policy — data-probe-default

{
  "key": "data-probe-default",
  "defaultDecision": "PENDING_DISCOVERY",
  "rules": [
    { specTypeKey: "table",
      matchSynthesisOrigin: ["DISCOVERED"],
      decision: "AUTO_PUBLISH",
      rationale: "Structural facts from JDBC are reliable" },

    { specTypeKey: "table",
      matchSensitivity: ["PII"],
      decision: "PENDING_DISCOVERY",
      requiredApproverPersonas: ["data-steward"],
      rationale: "PII tables require data steward sign-off" },

    { specTypeKey: "stored-procedure",
      matchAiConfidenceLt: 0.85,
      decision: "PENDING_DISCOVERY",
      requiredApproverRoleCategories: ["DBA"] },

    { specTypeKey: "architecture-standard",
      matchSynthesisOrigin: ["AI_DRAFTED_ARTIFACT"],
      decision: "PENDING_DISCOVERY",
      requiredApproverPersonas: ["ea-architect", "domain-architect"] }
  ]
}

Bulk-approve endpoints (POST /api/probe-runs/:id/approve) slice their updateMany by matching rule; the caller's roles/personas determine which Records flip to APPROVED in a single call.

Section 10 · Context Resolution Pipeline

Generated artefacts are grounded in real Records. Nothing else. Architect LLM

A context-resolver is a Record of SpecType context-resolver (so resolvers are tenant-customisable, versioned, and shipped via PDL). Its body is a declarative DSL: anchor SpecType, facets (multi-hop graph queries with dependencies), and a completeness gate.

Resolver DSL — solution-architecture-doc-context (excerpt)

{
  "anchor": { specTypeKey: "solution-architecture", required: true },
  "facets": [
    { key: "technologyStack",
      traversal: { from: "anchor", linkType: "uses-technology", direction: "OUTBOUND" },
      required: true,
      completenessRule: "AT_LEAST_ONE" },

    { key: "standardsPerTech",
      dependsOn: "technologyStack",
      traversal: { fromEach: "technologies", linkType: "governed-by",
                   filterSpecType: "architecture-standard", filterStatusIn: ["APPROVED"] },
      required: true,
      completenessRule: "AT_LEAST_ONE_PER_INPUT" },

    // ... 19 more facets: refArchs, guardrails, patterns, ADRs, NFRs, compliance, ...
  ],
  "completenessGate": {
    minimumRequiredFacetsPresent: 1.0,
    onMissing: "BLOCK_GENERATION"
  }
}

Reverse traceability — every generated Record knows what fed it

• Record.contextResolverKey — which resolver, if AI-generated
• Record.contextRecordIds[] — exact Record IDs that fed the LLM
• Record.contextRecordVersionIds[] — per-Record version pinned at generation time
• Record.aiInvocationIds[] — all LLM calls that produced this Record
• Record.generationStaleness — FRESH | DRIFT_DETECTED | STALE | REGENERATING

Section 12 · Governed Entity Pattern

Canonical state + version snapshots + project change proposals. One pattern, ten governed types. Architect

The canonical-vs-change separation applies to every governed entity type that multiple projects can modify concurrently: Applications, Services, APIs, Workflows, Databases, Systems, Tech Stacks, Reference Architectures, EA artefacts. The same three SpecTypes + six LinkTypes + one concurrency-analyser workflow handle them all (parameterised by canonical SpecType).

Concurrent change detection

The change-concurrency-analyzer workflow is parameterised by canonicalSpecTypeKey — not hardcoded for Applications. Triggered on every new/updated change-proposal Record across all 10 entity types, plus a nightly catch-up sweep. For each canonical entity with ≥ 2 in-flight proposals, runs a structural diff (deterministic), then an LLM judge call (§15 confidence-gate) only for ambiguous text cases. Emits change-conflict-finding Records with severity BLOCKER | HIGH | LOW.

Section 14 · EA Content Pre-Probe + Package Gap Analysis

Don't overwrite the customer's existing investment. CXO Sales

Many enterprise customers hold years of EA documentation in Confluence / SharePoint / Notion / Git docs. Installing PDL packages first risks overwriting or duplicating that material, devaluing prior investment. The customer-friendly approach: probe the existing EA corpus first, compare against what PDL packages provide, and surface per-item architect consent.

Per-item consent options

Decisions persist as OrganizationProbeProfile.packageInstallationDecisions — durable record of {packageKey, itemKey, choice, decidedByUserId, decidedAt, matchedCandidateId?} per item. Re-running gap analysis after a package update only re-evaluates changed items, preserving prior decisions. Adopted customer documents are marked synthesisOrigin = CUSTOMER_DOC_ADOPTED with source URL + last-modified date.

Section 16 · AI LLM Integration

Ten integration points. One confidence-gate. Full provenance. Architect LLM

Every LLM call in v1 goes through lib/ai/confidence-gate.ts — context injection, schema validation, confidence thresholds, provenance recording, and cost caps in one gateway. Below threshold → Record forced to PENDING_DISCOVERY regardless of autoPublish.

Confidence sources (template-declared)

• MODEL_SELF_REPORT — model returns a confidence field. Cheap; default for classification/tagging.
• MULTI_SHOT_CONSISTENCY — call N times with temperature > 0, compute agreement. Used for dedup + ownership (expensive but high-trust).
• HEURISTIC — derived from input quality signals (e.g. "doc text length < 200 chars → confidence ≤ 0.5"). Used for document extraction.

Section 18 · Self-Discovery Dogfood Acceptance

v1 ships when an architect can scan Arcitopsia itself and generate a real architecture doc. CXO Sales Architect

A "framework with no probes" is not deliverable. The v1 acceptance test is an architect sitting down, completing the wizard against the Arcitopsia production stack, running the plan, and producing a Solution Architecture Document that cites only Records discovered by the four v1 probes — and passes architect spot-check.

The acceptance test in one paragraph

Open /admin/probe-analyzer/ → register 4 SystemRegistrations (GitHub org arcitopsia, AWS account 848111426925, AWS-RDS prod DB, ECS cluster arcitopsia-cluster) → connect each via Phase A' with the 5-step gauntlet → assign FactCategoryMappings → run Discovery Sweep → Plan Generation produces a 4-stage DAG → Approve & Run reserves ≤ 5,000 credits → 4 probes execute in correct order → Hierarchy Synthesis auto-drafts ~28 EA artefacts → architect approves a subset in /admin/ea-review-queue/ → click "Generate Solution Architecture Document" on the synthesised application:arcitopsia-platform Record → Context Resolver application-context runs (completeness gate passes after approvals) → 11-section doc generated via §19 child-workflow fan-out → architect spot-checks 10 random claims → all 10 trace cleanly to source Records.

Section 20 · PDL Distribution

Probes, policies, resolvers, and TaxMaps ship as PDL packages. Architect

The Package Definition Language (PDL) is the platform's portable, idempotent, version-controlled installer format. Every Probe Framework artefact has a corresponding PDL component type so packages travel cleanly across tenants.

New PDL component types added for Probe Framework

Two reference distributions ship with v1: ea-foundation v-next (new SpecTypes + LinkTypes for the governance chain + Governed Entity Pattern) and ea-probes-arcitopsia-v1 (the 4 dogfood probe definitions + their ProbeConnectionTarget seeds for the Arcitopsia prod tenant — not installed by default; architect installs manually for the §24 acceptance test).

Section 22 · Application Architecture Ownership

EA owns the canonical Application. Projects own change proposals. They link, never duplicate. CXO Architect

The original motivating case for the Governed Entity Pattern (§12). One Application has one canonical Record (slow-changing, EA-owned) and many in-flight application-change-proposal Records (one per project modifying it). Project proposals carry only the delta — the canonical Record stays stable across many parallel projects.

The three Application-tier SpecTypes

Cross-project concurrency detection

The change-concurrency-analyzer workflow (per §12 — generic across all 10 Governed Entity types) fires whenever an application-change-proposal is created or updated, plus a nightly catch-up sweep. For each application with ≥ 2 in-flight proposals, it runs a structural diff (deterministic) over the proposal bodies — and only escalates to an LLM judge for ambiguous text cases. Emits change-conflict-finding Records with severity BLOCKER | HIGH | LOW, owner = App Architecture Team.

Section 24 · Resolver Inferencer

Starter resolvers inferred from observed graph topology. Architect LLM

Hand-authoring Context Resolver DSL is precise but expensive. The Resolver Inferencer drafts starter resolvers automatically by observing the LinkType usage patterns in a working tenant — ea-package-demo3 in v1. A mature, well-linked tenant graph encodes its own best practices; the inferencer extracts them mechanically.

Algorithm

function inferResolverForAnchor(anchorSpecTypeKey, tenantGraph) {
  candidates = top-20 most-linked Records of SpecType anchorSpecTypeKey
  for each candidate:
    walk OUTBOUND Links → tally (LinkType, target SpecType) pairs
    walk INBOUND  Links → tally same
    walk 2-hop transitive for governance LinkTypes
  rank facets by frequency-across-candidates
  set required=true for facets present on ≥80% of candidates
  set completenessRule="AT_LEAST_ONE_PER_INPUT" for fan-out facets
  order facets by dependency (foundation first — team, program, technology)
  return draft ContextResolver DSL JSON
}

v1 — build-time only

A CI job runs scripts/generate-starter-resolvers.ts against a freshly-rehydrated ea-package-demo3 tenant on every release branch. Output is committed to packages/ea-foundation-v-next/resolvers/. Tenants get the starter resolvers by installing the package; they edit per-tenant in the standard record editor afterwards.

Section 26 · EA Stream vs Delivery Stream Routing

A Record's stream is derived, not stored. Architect

Routing to EA Stream vs Delivery Stream is automatic the moment a Record's ownership is resolved. Existing platform permission logic (lib/auth/permissions/ea-delivery-separation.ts) keys off record.ownerTeam.program.programType — probes inherit it for free, no new column needed.

The derivation rule

record.stream = record.ownerTeam.program.programType
              ∈ { EA, GOVERNANCE, PLATFORM }  → "EA Stream"
              ∈ { DELIVERY, SHARED }            → "Delivery Stream"

Five-step ownership resolution (§3.2)

For every Record a probe is about to upsert, the resolver walks this pipeline in order; stops at the first match. Step 5 (AI inference) under threshold forces the Record to PENDING_DISCOVERY regardless of probe autoPublish.

Conflict case — shared infrastructure

A Kafka cluster used by both Delivery and EA streams: the probe writes one Record owned by the Platform team (L7/L9 DTT) and emits cross-stream Links (used-by) to the consuming Delivery teams. No duplication, no ambiguity about which Record is authoritative.

Section 28 · Glossary

Vocabulary for AI LLM grounding + onboarding. LLM Architect

A canonical glossary keyed to the runtime types. When ground-truthing an LLM about Arcitopsia, paste this section + the §3 taxonomy table + the §4 analyzer DAG.

Record

A typed instance of a SpecType in a tenant's Knowledge Graph. Carries status (PENDING_DISCOVERY / APPROVED / REJECTED / ARCHIVED), ownerTeamId, programId, projectId, and arbitrary data JSON.

SpecType

The schema definition for a class of Record (e.g. service, database, architecture-standard). Versioned; tenant-customisable.

Link

A typed edge between two Records. Has source SpecType, target SpecType, and a LinkType (e.g. uses-technology, governed-by).

LinkType

The schema for a class of Link. Defines from/to SpecType constraints, cardinality, and traversal directionality.

ProbeDefinition

A scanner spec: category, workflowId, target selector, publication policy, default owner team, list of ProbeStageDefinition sub-stages.

ProbeRun

One execution of a ProbeDefinition. Wraps a parent WorkflowJob + fans out into N child WorkflowJobs (one per ProbeConnectionTarget). Shares one changeSetId for audit / rollback.

ProbeStageRun

One sub-stage execution of a ProbeRun against a specific target. Strict intra-target ordering; cross-target parallel.

ProbeConnectionTarget

A specific scan target under a ProbeDefinition (e.g. one AWS account, one GitHub org). Carries per-target credentials + scope hints.

SystemRegistration

Probe-Analyzer wizard Phase A output. Declares "we have this kind of system" — kind ∈ {IDP, HR_SYSTEM, CLOUD_ORG, VCS_ORG, CI_CD_PLATFORM, OBSERVABILITY, DOC_REPO, DATABASE_PLATFORM, MESSAGING, DATA_WAREHOUSE, GRC_TOOL, FINANCE_SYSTEM, MANUAL_INPUT}.

FactCategoryMapping

Phase B output. Maps a FactCategory (e.g. ORG_HIERARCHY, CLOUD_ACCOUNT_INVENTORY) to a primary source + sourcing decision (PROBED / MANUAL / AI_INFERRED / DEFERRED).

ProbeExecutionPlan

Phase D output. Versioned, supersedeable DAG: stages → items. Pure function of inputs — re-runnable deterministically.

Hierarchy Synthesis

The post-Stage-1 probe that walks the EA chain upward from each newly-discovered Delivery-Stream Record, auto-creating missing Teams + drafting missing EA artefacts as PENDING_DISCOVERY. Idempotent.

Context Resolver

A Record of SpecType context-resolver. Body is a DSL declaring an anchor SpecType + multi-hop facets + a completeness gate. Used by AI workflows to fetch grounded context.

Completeness Gate

The mechanism by which a resolver refuses to feed an LLM call with incomplete context. Modes: BLOCK_GENERATION, DEGRADE, WARN.

Two-Gate Injection

The pair of gates that protect against silent AI degradation: (1) Resolver Completeness — facets fetched; (2) Injection Completeness — mandatory facets reach the rendered prompt text.

Governed Entity

Any SpecType that follows the canonical-vs-change separation: one EA-owned canonical Record + N implementation snapshots + M project change proposals. Applies to ten entity types in v1.

EA Stream vs Delivery Stream

Streams are derived, not stored: record.stream = record.ownerTeam.program.programType. EA / GOVERNANCE / PLATFORM programs → EA Stream; DELIVERY / SHARED programs → Delivery Stream. Governs visibility + approval rules.

Direction of Authority

The set of rules (§13) that resolve probes-vs-architects conflicts: probes never silently overwrite architect decisions; architects never silently override discovered reality; both flag divergence as findings.

Library-First Doctrine

The rule: every stage that can use a deterministic library MUST use one. LLM is for semantic judgment, not structural extraction. Validated by package validator + plan-review library-coverage ratio.

Confidence Gate

lib/ai/confidence-gate.ts — the single AI gateway. Looks up template, injects context, calls model, validates output schema, computes confidence, enforces threshold + fallback, persists AIUsageLog with full provenance.

Provenance

Record.aiProvenance + Record.contextRecordIds[] + Record.aiInvocationIds[] + AIUsageLog entries. Every AI-touched Record traces back to its model, prompt template, confidence, source Records, and pinned versions at generation time.

Credit Ledger

The PSP-agnostic CreditTransaction table that records every credit movement (DEDUCTION / TOPUP / MONTHLY_GRANT / EXPIRY / REFUND). Idempotent via (executionId, type) unique index. Never deleted.

Reserve / Settle / Release

The credit lifecycle: reserve the worst-case at Phase E (hold against balance); settle the actual after complexity computation (deduct, release remainder); release the full reservation if execution failed.

Complexity Multiplier

10 runtime dimensions × weights, sum normalised, then log₂(score + 1) × 1.44 dampening, clamped to [contract.min, contract.max]. Captures real cost variation without runaway bills on legitimately large scans.

PSP-Agnostic Invariant

Per PAYG §9.6: the credit ledger (credit-engine.ts, credit-service.ts, complexity-calculator.ts) contains zero Stripe-specific types/IDs/imports. Stripe is isolated to stripe-credits.ts + webhook handler. Future PSPs (Razorpay v1.5, Chargebee v2, Paddle v3) drop in without touching the ledger.

Two-Layer Measurement

Per PAYG §7.0: internal telemetry (iArchitron-only — WorkflowExecutionTelemetry with compute units, tokens, LLM cost, gross margin) is strictly separated from customer-facing credits (CreditTransaction with fixed activity-type base × complexity × tier).