Appearance

Core Concepts ​

The first-class objects in Escher, how they relate, and the execution model that connects them.

Source of truth

The canonical model lives in v3-architecture-docs/Appendix_A_Object_Model_Final_V1.md in the repos. This page reflects that model — eleven first-class objects: Estate, Observer Context, EstateView, Report, Finding, Plan, Bundle, Run, Evidence, Playbook, and Deployment Group.

The object model at a glance ​

Every object above is explicit, durable, and auditable. Nothing is implicit. Nothing disappears.

The objects ​

1. Estate ​

The boundary of cloud reality that Escher observes and reasons about.

The Estate is not a CMDB. It is not a workflow object. It is the conceptual canvas — the stable reference point for all observation, planning, and execution reasoning.

The cloud provider remains the source of truth. Escher's Estate reflects it. Escher never owns, modifies, or deletes cloud resources directly through the Estate layer.

Estate includes:
  - cloud accounts / subscriptions
  - regions
  - environments (dev / staging / prod)
  - resources and their relationships (graph)

OS Analogy

If Escher is a cloud OS, the Estate is the filesystem — you can read it, navigate it, and annotate it. You cannot delete it. Cloud reality is the disk.

2. EstateView ​

A materialized, time-bound, versioned snapshot of the Estate.

Every scan produces a new EstateView version. EstateViews are stored locally in a graph database (SurrealDB) — nodes are resources, edges are relationships. This enables:

  • Fast offline queries (no cloud API calls after scan)
  • Temporal reasoning (what changed since last Tuesday?)
  • Deterministic planning (Plans are built against a pinned snapshot — blast radius is reliable)
  • Drift detection between snapshots
EstateView v3 (refreshed 12 min ago)
  Profiles contributing: 6/7
  Resources: 380
  Accounts: AWS-123456, AWS-234567, Azure-Corp
  Changes vs v2: +8 resources, -1, ~6 modified

Two users with different permissions see different EstateViews at the same time. This is expected and surfaced explicitly via the Observer Context.

3. Observer Context (Profile) ​

The identity, scope, and permissions under which an EstateView is produced.

Every observation is made under an Observer Context. It includes:

  • The cloud principal (AWS IAM user/role, Azure service principal)
  • Allowed accounts and regions
  • Effective read permissions

Escher discovers Observer Contexts from your local cloud CLI configuration (~/.aws/credentials, az login state). It does not create or manage cloud credentials — it consumes what you've already configured.

Observer Context:
  Profile name: prod-admin
  Provider: AWS
  Account: 123456789012
  Permissions: ec2:Describe*, s3:List*, iam:Get*, rds:Describe*
  Status: Active

TIP

Adding a second profile (e.g. audit-readonly) for the same account gives you a different EstateView — useful for validating that least-privilege access produces the expected visibility.

4. Report ​

A structured analysis artifact generated from an EstateView.

Reports answer: What issues or signals do we observe in the estate?

They aggregate analysis results from a scan pass and contain Report Items (individual observed issues). Reports maintain version history — re-running a report on a newer EstateView produces a new version, not a replacement.

Reports do not execute. They observe and surface.

Report: Security Baseline
  Category: Security
  Profile: prod-admin
  Items: 7
  Findings spawned: 3
  Versions: 5
  Last run: 12m ago

A Report Item is the raw observation. A Finding is the actionable interpretation of one or more Report Items.

5. Finding ​

An actionable interpretation of an observation — the operational unit of work.

Findings bridge analysis to remediation. They can originate from Reports, from estate inspection, or from manual investigation.

Unlike Reports (which are analytical snapshots), Findings are living artifacts. They evolve through these states:

new → acknowledged → delegated → resolved
                  ↘
                 dismissed

One Finding can link to multiple Plans. One Plan can address multiple Findings. The link is explicit — never implicit.

Finding: EC2 Instances Missing Name Tag
  Severity: Medium
  Resources: 12
  Account: 123456789012 (prod-core / us-east-1)
  Evidence: attached (instance list, ages, types)
  Linked plans: 1
  Status: Open

6. Plan ​

Developed intent to change the estate — what should be done.

Plans answer: What changes do we intend to make?

Plans are first-class objects. They are not children of a Finding — they can exist independently, address multiple Findings, or be created proactively without any Finding.

Plans do not execute directly. Execution path:

Finding(s) → Plan → Bundle(s) → Run(s)

Plans evolve via revisions. A revision becomes immutable once it is bound to an execution (a Bundle is materialized from it and a Run starts).

Bundles materialized from a Plan move through their own state machine:

draft → ready → stale

A Bundle becomes stale automatically if the underlying EstateView changes after the Bundle was built — protecting you from acting on outdated information.

Runs (the actual execution) have their own non-terminal and terminal states:

Non-terminal: created → preflight → running → paused
Terminal:     completed_success | completed_partial | completed_fail

WARNING

Escher separates what should be done (Plan) from what will actually run (Bundle) from what actually ran (Run). This separation is the foundation of safety and auditability. Never conflate the three.

7. Bundle ​

Exact execution steps materialized from a Plan — what will run.

A Bundle is concrete. Where a Plan says "restrict SSH access to production security groups," the Bundle says:

Step 1: aws ec2 revoke-security-group-ingress
        --group-id sg-0abc123
        --protocol tcp --port 22 --cidr 0.0.0.0/0

Step 2: aws ec2 authorize-security-group-ingress
        --group-id sg-0abc123
        --protocol tcp --port 22 --cidr 10.0.0.0/8

A Bundle is built against a pinned EstateView version. If the estate drifts between Bundle creation and execution, the Bundle is automatically flagged as stale — protecting against acting on outdated information.

A single Plan can produce multiple Bundles (for different environments, or different execution strategies).

8. Run ​

A single execution of a Bundle — what actually happened.

Runs are append-only. They cannot be modified after creation. Each step's outcome is recorded:

Run: Restrict SSH Access — prod-core
  Started: 10:15 UTC
  Duration: 4m 12s
  Status: Completed
  Steps:
    ✓ Step 1: revoke ingress rule (sg-0abc123) — 1.2s
    ✓ Step 2: authorize restricted ingress (sg-0abc123) — 0.9s
  Evidence: attached (API responses, before/after state)

Runs are pauseable, retryable, and support partial completion explicitly. History is never rewritten.

9. Evidence ​

The append-only audit trail attached to a Run.

Evidence is everything Escher captured during execution:

  • API call inputs and outputs
  • Before/after resource state
  • Timestamps
  • Agent reasoning summaries
  • Human approval records

Evidence is human-readable (explanations, deltas) and machine-readable (logs, outputs, hashes). It is attached to Runs and surfaced in Reports.

Evidence record: Run-2847
  Type: execution_record
  Steps: 2
  API calls logged: 4
  Before state: { ingress_rules: [{ port: 22, cidr: "0.0.0.0/0" }] }
  After state:  { ingress_rules: [{ port: 22, cidr: "10.0.0.0/8" }] }
  Approved by: alice@company.com at 10:14:52 UTC

10. Playbook ​

A reusable, named operational procedure.

Playbooks encode sequences of remediation steps that have been proven and approved. They can be triggered by Findings, called explicitly, or generated dynamically by the Code Agent when no registered Playbook matches.

Playbooks are registered via the ADK. They always require human confirmation before execution and always produce Evidence.

Playbook: security.remediate_public_exposure
  Trigger: Finding with category=network_exposure, severity=HIGH
  Steps: 3
  Target language: Python
  Safety class: advisory
  Requires human review: yes

The full lifecycle — one concrete example ​

1. Estate refresh runs at 09:00
   → EstateView v12 committed (380 resources)

2. Security Report runs against v12
   → Report Item: "S3 bucket 'prod-logs' has public read ACL"

3. Finding created automatically
   → Finding: Public S3 Bucket — prod-logs (HIGH)

4. User asks: "Create a plan to fix the public S3 bucket"
   → Plan: Restrict prod-logs bucket ACL (Draft)

5. Escher materializes a Bundle
   → Bundle: 2 steps, blast radius = 0 downtime
   → Plan status: Proposed

6. User reviews and approves
   → Plan status: Approved

7. Escher executes the Bundle
   → Run created, steps execute sequentially
   → Evidence captured for each step

8. Run completes
   → Finding status: Closed
   → Evidence report available for audit

Total time from observation to closed Finding: under 5 minutes for a change that used to take a ticket, a runbook, and a change window.

Next steps ​

Escher — Agentic CloudOps by Tessell

© 2026 Tessell, Inc.