@intentius/chant-lexicon-terraform 0.124.44 → 0.124.46

package/dist/__fixtures__/capabilities/chant.config.d.ts

@@ -0,0 +1,26 @@
+import "@intentius/chant-lexicon-terraform";
+declare const _default: {
+    lexicons: string[];
+    lint: {
+        rules: {
+            TF022: "off";
+            TF030: "off";
+            TF033: "off";
+        };
+    };
+    terraform: {
+        roots: {
+            ledger: {
+                dir: string;
+            };
+            catalog: {
+                dir: string;
+            };
+            findings: {
+                dir: string;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=chant.config.d.ts.map

package/dist/__fixtures__/capabilities/chant.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chant.config.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/capabilities/chant.config.ts"],"names":[],"mappings":"AACA,OAAO,oCAAoC,CAAC;;;;;;;;;;;QAOxC,KAAK;YACH,MAAM;gBAAI,GAAG;;YACb,OAAO;gBAAI,GAAG;;YACd,QAAQ;gBAAI,GAAG"}

package/dist/__fixtures__/capabilities/chant.config.js

@@ -0,0 +1,13 @@
+import "@intentius/chant-lexicon-terraform";
+export default {
+    lexicons: ["terraform"],
+    // The estates hold the findings these rules report on purpose.
+    lint: { rules: { TF022: "off", TF030: "off", TF033: "off" } },
+    terraform: {
+        roots: {
+            ledger: { dir: "./ledger" },
+            catalog: { dir: "./catalog" },
+            findings: { dir: "./findings" },
+        },
+    },
+};

package/dist/__fixtures__/effective-topology/chant.config.d.ts

@@ -0,0 +1,13 @@
+import "@intentius/chant-lexicon-terraform";
+declare const _default: {
+    lexicons: string[];
+    terraform: {
+        roots: {
+            net: {
+                dir: string;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=chant.config.d.ts.map

package/dist/__fixtures__/effective-topology/chant.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chant.config.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/effective-topology/chant.config.ts"],"names":[],"mappings":"AACA,OAAO,oCAAoC,CAAC;;;;QAKxC,KAAK;YACH,GAAG;gBAAI,GAAG"}

package/dist/__fixtures__/effective-topology/chant.config.js

@@ -0,0 +1,9 @@
+import "@intentius/chant-lexicon-terraform";
+export default {
+    lexicons: ["terraform"],
+    terraform: {
+        roots: {
+            net: { dir: "./net" },
+        },
+    },
+};

package/dist/__fixtures__/kind-type/chant.config.d.ts

@@ -0,0 +1,13 @@
+import "@intentius/chant-lexicon-terraform";
+declare const _default: {
+    lexicons: string[];
+    terraform: {
+        roots: {
+            app: {
+                dir: string;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=chant.config.d.ts.map

package/dist/__fixtures__/kind-type/chant.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chant.config.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/kind-type/chant.config.ts"],"names":[],"mappings":"AACA,OAAO,oCAAoC,CAAC;;;;QAKxC,KAAK;YACH,GAAG;gBAAI,GAAG"}

package/dist/__fixtures__/kind-type/chant.config.js

@@ -0,0 +1,9 @@
+import "@intentius/chant-lexicon-terraform";
+export default {
+    lexicons: ["terraform"],
+    terraform: {
+        roots: {
+            app: { dir: "./app" },
+        },
+    },
+};

package/dist/__fixtures__/search-roots/chant.config.d.ts

@@ -0,0 +1,13 @@
+import "@intentius/chant-lexicon-terraform";
+declare const _default: {
+    lexicons: string[];
+    terraform: {
+        roots: {
+            net: {
+                dir: string;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=chant.config.d.ts.map

package/dist/__fixtures__/search-roots/chant.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chant.config.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/search-roots/chant.config.ts"],"names":[],"mappings":"AACA,OAAO,oCAAoC,CAAC;;;;QAKxC,KAAK;YACH,GAAG;gBAAI,GAAG"}

package/dist/__fixtures__/search-roots/chant.config.js

@@ -0,0 +1,9 @@
+import "@intentius/chant-lexicon-terraform";
+export default {
+    lexicons: ["terraform"],
+    terraform: {
+        roots: {
+            net: { dir: "./net" },
+        },
+    },
+};

package/dist/__fixtures__/sensitive-default/chant.config.d.ts

@@ -0,0 +1,13 @@
+import "@intentius/chant-lexicon-terraform";
+declare const _default: {
+    lexicons: string[];
+    terraform: {
+        roots: {
+            net: {
+                dir: string;
+            };
+        };
+    };
+};
+export default _default;
+//# sourceMappingURL=chant.config.d.ts.map

package/dist/__fixtures__/sensitive-default/chant.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chant.config.d.ts","sourceRoot":"","sources":["../../../src/__fixtures__/sensitive-default/chant.config.ts"],"names":[],"mappings":"AACA,OAAO,oCAAoC,CAAC;;;;QAKxC,KAAK;YACH,GAAG;gBAAI,GAAG"}

package/dist/__fixtures__/sensitive-default/chant.config.js

@@ -0,0 +1,9 @@
+import "@intentius/chant-lexicon-terraform";
+export default {
+    lexicons: ["terraform"],
+    terraform: {
+        roots: {
+            net: { dir: "./net" },
+        },
+    },
+};

package/dist/capabilities/adapter.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The terraform lexicon's capability pack (#4375): its mapping onto the
+ * lexicon-neutral view, as data, and the one thing the mapping can't say as
+ * data, how to read a policy written as `jsonencode({...})`.
+ */
+import type { CapabilityAdapter, CapabilityPack } from "@intentius/chant/capabilities/view";
+export declare const terraformCapabilityAdapter: CapabilityAdapter;
+export declare const terraformCapabilityPack: CapabilityPack;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/capabilities/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/capabilities/adapter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAqB,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAc/G,eAAO,MAAM,0BAA0B,EAAE,iBAOxC,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAGrC,CAAC"}

package/dist/capabilities/adapter.js

@@ -0,0 +1,25 @@
+import mapping from "./mapping.json" with { type: "json" };
+import { isUnknown, readJsonencode } from "../hcl/jsonencode.js";
+/** Turn each value position `readJsonencode` couldn't read into its expression, as `${...}` text. */
+function withExpressions(v) {
+    if (isUnknown(v))
+        return v.source !== undefined ? `\${${v.source}}` : undefined;
+    if (Array.isArray(v))
+        return v.map(withExpressions);
+    if (v && typeof v === "object") {
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, withExpressions(x)]));
+    }
+    return v;
+}
+export const terraformCapabilityAdapter = {
+    readDocument(value) {
+        // An inline_policy block carries the document in its `policy` argument.
+        const raw = value && typeof value === "object" && !Array.isArray(value) ? value.policy : value;
+        const read = readJsonencode(raw, { unknownLeaves: true });
+        return read.kind === "literal" ? withExpressions(read.value) : undefined;
+    },
+};
+export const terraformCapabilityPack = {
+    mapping: mapping,
+    adapter: terraformCapabilityAdapter,
+};

package/dist/capabilities/mapping.json

@@ -0,0 +1,166 @@
+{
+    "lexicon": "terraform",
+    "types": "terraform",
+    "body": "body",
+    "refs": "terraform",
+    "labels": {
+        "aws_vpc": "Vpc",
+        "aws_default_vpc": {
+            "label": "Vpc",
+            "set": {
+                "isDefault": true
+            }
+        },
+        "aws_default_security_group": "SecurityGroup",
+        "aws_network_interface": "NetworkInterface",
+        "aws_ebs_volume": "Volume",
+        "aws_lambda_function": "Function",
+        "aws_lambda_function_url": "FunctionUrl",
+        "aws_iam_instance_profile": "InstanceProfile",
+        "aws_iam_role": "Role",
+        "aws_iam_policy": "Policy",
+        "aws_iam_role_policy": "Policy",
+        "aws_iam_role_policy_attachment": "PolicyAttachment",
+        "aws_s3_bucket_policy": "ResourcePolicy",
+        "aws_sqs_queue_policy": "ResourcePolicy",
+        "aws_s3_bucket": "Bucket",
+        "aws_s3_bucket_public_access_block": "PublicAccessBlock",
+        "aws_dynamodb_table": "Table",
+        "aws_db_instance": "Database",
+        "aws_rds_cluster": "Database",
+        "aws_secretsmanager_secret": "Secret",
+        "aws_sqs_queue": "Queue",
+        "aws_efs_file_system": "FileSystem",
+        "aws_ssm_parameter": "Parameter",
+        "aws_ecs_service": "Service",
+        "aws_ecs_task_definition": "TaskDefinition",
+        "aws_db_subnet_group": "SubnetGroup",
+        "aws_nat_gateway": "NatGateway",
+        "aws_lb": "LoadBalancer",
+        "aws_alb": "LoadBalancer"
+    },
+    "edges": {
+        "Instance": {
+            "iam_instance_profile": "profile"
+        },
+        "LaunchTemplate": {
+            "iam_instance_profile": "profile"
+        },
+        "Subnet": {
+            "vpc_id": "vpc"
+        },
+        "SecurityGroup": {
+            "vpc_id": "vpc"
+        },
+        "NetworkInterface": {
+            "subnet_id": "subnet",
+            "security_groups": "sg"
+        },
+        "Database": {
+            "vpc_security_group_ids": "sg",
+            "db_subnet_group_name": "subnetGroup"
+        },
+        "Function": {
+            "role": "role",
+            "vpc_config": {
+                "SecurityGroup": "sg",
+                "Subnet": "subnet"
+            }
+        },
+        "FunctionUrl": {
+            "function_name": "function"
+        },
+        "InstanceProfile": {
+            "role": "role"
+        },
+        "Policy": {
+            "role": "attachedTo"
+        },
+        "PolicyAttachment": {
+            "role": "role",
+            "policy_arn": "policy"
+        },
+        "ResourcePolicy": {
+            "bucket": "policyOf",
+            "queue_url": "policyOf"
+        },
+        "PublicAccessBlock": {
+            "bucket": "blocks"
+        },
+        "Service": {
+            "task_definition": "task",
+            "network_configuration": {
+                "SecurityGroup": "sg",
+                "Subnet": "subnet"
+            }
+        },
+        "TaskDefinition": {
+            "task_role_arn": "role"
+        },
+        "SubnetGroup": {
+            "subnet_ids": "subnet"
+        },
+        "NatGateway": {
+            "subnet_id": "subnet"
+        },
+        "LoadBalancer": {
+            "subnets": "subnet",
+            "security_groups": "sg"
+        }
+    },
+    "links": {
+        "PolicyAttachment": {
+            "from": "policy",
+            "to": "role",
+            "edge": "attachedTo"
+        }
+    },
+    "attrs": {
+        "FunctionUrl": {
+            "authType": "authorization_type"
+        },
+        "Role": {
+            "name": "name"
+        },
+        "Bucket": {
+            "name": "bucket",
+            "acl": "acl"
+        },
+        "PublicAccessBlock": {
+            "blockPublicPolicy": "block_public_policy"
+        },
+        "Table": {
+            "name": "name"
+        },
+        "Database": {
+            "encrypted": "storage_encrypted"
+        },
+        "FileSystem": {
+            "encrypted": "encrypted"
+        },
+        "Volume": {
+            "encrypted": "encrypted"
+        },
+        "Parameter": {
+            "paramType": "type"
+        }
+    },
+    "documents": {
+        "Role": {
+            "assume_role_policy": "trust",
+            "inline_policy[].policy": "permission"
+        },
+        "Policy": {
+            "policy": "permission"
+        },
+        "ResourcePolicy": {
+            "policy": "resource"
+        }
+    },
+    "tags": [
+        "tags"
+    ],
+    "classificationTags": [
+        "data-classification"
+    ]
+}

package/dist/config.d.ts

@@ -49,6 +49,15 @@ export type TerraformDeleteMode = z.infer<typeof terraformDeleteModeSchema>;
  * strict, and a root entry is exactly where a typo (`varfiles`) would
  * otherwise land silently.
  */
+/**
+ * How deep a root is observed (#4358): `"state"` reads state, `"plan"`
+ * reads a saved plan. See {@link TerraformRootConfig.observe}.
+ */
+export declare const terraformObserveDepthSchema: z.ZodEnum<{
+    plan: "plan";
+    state: "state";
+}>;
+export type TerraformObserveDepth = z.infer<typeof terraformObserveDepthSchema>;
 export declare const terraformRootSchema: z.ZodObject<{
     /** Root module directory, relative to the project root (where `chant.config.*` lives). */
     dir: z.ZodString;
@@ -90,6 +99,25 @@ export declare const terraformRootSchema: z.ZodObject<{
         never: "never";
         "owned-only": "owned-only";
     }>>;
+    /**
+     * How deep `describeResources` reads this root (#4358). `"state"`, the
+     * default, is `terraform show -json` over state: what the last apply
+     * recorded. `"plan"` is a saved plan, `plan -lock=false -out=<tmp>` then
+     * `show -json`: what the next apply would do, with replace reasons,
+     * values unknown until apply and drift. It needs provider credentials and
+     * an initialised root, and falls back to the state read, then to declared
+     * only, saying which read answered. A live choudoufu root keeps its
+     * `live-plan -json` read for ownership at either depth; at `"plan"` the
+     * plan read runs beside it and its attributes go on the blocks `live-plan`
+     * bound (#4371).
+     *
+     * The `CHANT_TERRAFORM_OBSERVE` environment variable overrides it for
+     * every root, for one run.
+     */
+    observe: z.ZodOptional<z.ZodEnum<{
+        plan: "plan";
+        state: "state";
+    }>>;
 }, z.core.$strict>;
 export declare const terraformConfigSchema: z.ZodObject<{
     /**
@@ -131,6 +159,11 @@ export declare const terraformConfigSchema: z.ZodObject<{
      * project does not own.
      */
     moduleRoot: z.ZodOptional<z.ZodString>;
+    /** The default {@link TerraformRootConfig.observe} for every root that sets none (#4358). */
+    observe: z.ZodOptional<z.ZodEnum<{
+        plan: "plan";
+        state: "state";
+    }>>;
     /** Named root modules. The name is the entity-key prefix, so keep it stable. */
     roots: z.ZodRecord<z.ZodString, z.ZodObject<{
         /** Root module directory, relative to the project root (where `chant.config.*` lives). */
@@ -173,6 +206,25 @@ export declare const terraformConfigSchema: z.ZodObject<{
             never: "never";
             "owned-only": "owned-only";
         }>>;
+        /**
+         * How deep `describeResources` reads this root (#4358). `"state"`, the
+         * default, is `terraform show -json` over state: what the last apply
+         * recorded. `"plan"` is a saved plan, `plan -lock=false -out=<tmp>` then
+         * `show -json`: what the next apply would do, with replace reasons,
+         * values unknown until apply and drift. It needs provider credentials and
+         * an initialised root, and falls back to the state read, then to declared
+         * only, saying which read answered. A live choudoufu root keeps its
+         * `live-plan -json` read for ownership at either depth; at `"plan"` the
+         * plan read runs beside it and its attributes go on the blocks `live-plan`
+         * bound (#4371).
+         *
+         * The `CHANT_TERRAFORM_OBSERVE` environment variable overrides it for
+         * every root, for one run.
+         */
+        observe: z.ZodOptional<z.ZodEnum<{
+            plan: "plan";
+            state: "state";
+        }>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type TerraformRootConfig = z.infer<typeof terraformRootSchema>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;EAA2C,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;;IAEH,+EAA+E;;;;;;kBAE/E,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;OAOG;;;;;;IAEH;;;;;;;OAOG;;;;;;IAEH;;;;;;;;;;;OAWG;;IAEH,gFAAgF;;QAtEhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;QAE1D;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;;QAEH,+EAA+E;;;;;;;kBAsC/E,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB;;;;EAA2C,CAAC;AAClF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E;;;;;;;;GAQG;AACH;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;EAA4B,CAAC;AAErE,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,mBAAmB;IAC9B,0FAA0F;;IAE1F,4EAA4E;;IAE5E,0DAA0D;;IAE1D,0DAA0D;;IAE1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;;IAEH,+EAA+E;;;;;;IAE/E;;;;;;;;;;;;;;OAcG;;;;;kBAEH,CAAC;AAEH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;OAOG;;;;;;IAEH;;;;;;;OAOG;;;;;;IAEH;;;;;;;;;;;OAWG;;IAEH,6FAA6F;;;;;IAE7F,gFAAgF;;QAxFhF,0FAA0F;;QAE1F,4EAA4E;;QAE5E,0DAA0D;;QAE1D,0DAA0D;;QAE1D;;;;;;;;;;;;;;;;;;;;;;;;WAwBG;;QAEH,+EAA+E;;;;;;QAE/E;;;;;;;;;;;;;;WAcG;;;;;;kBAwCH,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,OAAO,QAAQ,yBAAyB,CAAC;IACvC,UAAU,WAAW;QACnB,SAAS,CAAC,EAAE,eAAe,CAAC;KAC7B;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,wBAAwB,GAAG,WAAW,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC"}

package/dist/config.js

@@ -43,6 +43,11 @@ export const terraformDeleteModeSchema = z.enum(["never", "owned-only", "gated"]
  * strict, and a root entry is exactly where a typo (`varfiles`) would
  * otherwise land silently.
  */
+/**
+ * How deep a root is observed (#4358): `"state"` reads state, `"plan"`
+ * reads a saved plan. See {@link TerraformRootConfig.observe}.
+ */
+export const terraformObserveDepthSchema = z.enum(["state", "plan"]);
 export const terraformRootSchema = z.strictObject({
     /** Root module directory, relative to the project root (where `chant.config.*` lives). */
     dir: z.string(),
@@ -80,6 +85,22 @@ export const terraformRootSchema = z.strictObject({
     estate: z.string().optional(),
     /** This root's declared delete mode. See {@link terraformDeleteModeSchema}. */
     delete: terraformDeleteModeSchema.optional(),
+    /**
+     * How deep `describeResources` reads this root (#4358). `"state"`, the
+     * default, is `terraform show -json` over state: what the last apply
+     * recorded. `"plan"` is a saved plan, `plan -lock=false -out=<tmp>` then
+     * `show -json`: what the next apply would do, with replace reasons,
+     * values unknown until apply and drift. It needs provider credentials and
+     * an initialised root, and falls back to the state read, then to declared
+     * only, saying which read answered. A live choudoufu root keeps its
+     * `live-plan -json` read for ownership at either depth; at `"plan"` the
+     * plan read runs beside it and its attributes go on the blocks `live-plan`
+     * bound (#4371).
+     *
+     * The `CHANT_TERRAFORM_OBSERVE` environment variable overrides it for
+     * every root, for one run.
+     */
+    observe: terraformObserveDepthSchema.optional(),
 });
 export const terraformConfigSchema = z.strictObject({
     /**
@@ -113,6 +134,8 @@ export const terraformConfigSchema = z.strictObject({
      * project does not own.
      */
     moduleRoot: z.string().optional(),
+    /** The default {@link TerraformRootConfig.observe} for every root that sets none (#4358). */
+    observe: terraformObserveDepthSchema.optional(),
     /** Named root modules. The name is the entity-key prefix, so keep it stable. */
     roots: z.record(z.string(), terraformRootSchema),
 });

package/dist/describe-resources.d.ts

@@ -24,18 +24,26 @@
  * is a different one.
  *
  * So the returned `ObservationResult` carries `sources`, keyed by chant entity
- * name, with one of exactly two values:
+ * name, with one of exactly four values:
  *
- * - `"state"` — this entity's root was read with `terraform show -json`.
- * - `"live"` — this entity's root was read with `choudoufu live-plan -json`.
+ * - `"state"`: this entity's root was read with `terraform show -json`.
+ * - `"live"`: this entity's root was read with `choudoufu live-plan -json`.
+ * - `"plan"`: this entity's root was read at the plan depth (#4358), a saved
+ *   plan's `show -json`, which says what the next apply would do. See the
+ *   plan depth section below.
+ * - `"live+plan"`: a live root at the plan depth (#4371), where both reads
+ *   answered: `live-plan -json` for presence and ownership, the plan read for
+ *   the attributes. A live root whose plan read failed says `"live"`.
  *
  * Three guarantees a consumer may rely on. Every entity `describeResources`
  * was asked about that belongs to a root has an entry, whatever verdict it
  * came back with: present, absent and not-observed alike, because which read
- * was attempted is a fact independent of what it found. The value equals the
- * declared entity's own `props.mode` (`./hcl/parse.ts`), since one fact
- * decides both, so `props.mode` is also a valid join key for a consumer
- * holding the declared graph and no observation. And a project mixing stock
+ * was attempted is a fact independent of what it found. On a root read at the
+ * default depth the value equals the declared entity's own `props.mode`
+ * (`./hcl/parse.ts`), since one fact decides both, so `props.mode` is also a
+ * valid join key for a consumer holding the declared graph and no
+ * observation; the plan depth is chosen at read time, so only `sources` says
+ * it was used. And a project mixing stock
  * and live roots gets both values in one document, which is why this is a map
  * and not a field on the result as a whole.
  *
@@ -144,6 +152,49 @@
  * (`live-ls`'s own help text) and a listing taken right after an apply can
  * otherwise show a resource under both its old and new estate, or neither.
  *
+ * ## The plan depth (#4358)
+ *
+ * A stock root can be read one depth further: `terraform.observe` (or a
+ * root's own `observe`) set to `"plan"`, or `CHANT_TERRAFORM_OBSERVE=plan`,
+ * or `depth: "plan"` from a caller. The read is `terraformPlanRead`:
+ * `plan -input=false -lock=false -out=<tmp>/plan.tfplan`, then `show -json`,
+ * with `<tmp>` under the OS temp directory and removed afterwards, and no
+ * `init`. Presence and ownership come from the plan's `prior_state` by the
+ * state read's own rule; `./plan-observation.ts` adds the plan's attributes
+ * (`planAction`, `planReplacePaths`, `planAfterUnknown`, `planDrift`, ...)
+ * to each present block, with sensitive values redacted.
+ *
+ * It falls back by depth (`planAdapter`): no provider credentials -> the
+ * state read; no backend, or a root that needs `init` -> declared only. Each
+ * root gets a note saying which read answered. A planned create has no row in
+ * `prior_state` and reads absent, as on the state read, so its plan
+ * attributes have nowhere to ride.
+ *
+ * ### On a live root (#4371)
+ *
+ * `live-plan -json` carries ownership and no attribute values (behold#404),
+ * and `choudoufu plan -out` writes a stock plan file (choudoufu #878). So a
+ * live root at the plan depth runs both (`livePlanDepthAdapter`):
+ * `live-plan -json` first, unchanged, for presence and ownership, then the
+ * same `terraformPlanRead` a stock root gets, whose attributes are added to
+ * each block `live-plan` bound. A foreign or adoptable block gets none: the
+ * plan proposes a create there, which is choudoufu's answer for an instance
+ * it does not own, not a fact about the live resource. `sources` reads
+ * `"live+plan"`.
+ *
+ * choudoufu rebuilds prior state from the account on every run, so on a live
+ * root out-of-band drift is not in `resource_drift`. It is the planned
+ * `update` itself: `planChanges` has the live value as `before` and the
+ * declared one as `after`, and `planDrift` stays empty. That is where #2472's
+ * property-level drift for a live root comes from.
+ *
+ * Falling back is one step: if the plan read fails, `live-plan` alone
+ * answered, the note says why, and `sources` reads `"live"`. If `live-plan`
+ * fails the root is not observed, as at the default depth, and the plan read
+ * is not tried, since its attributes would have no present block to ride.
+ * The cost is two refreshes of the estate per read, run one after the other
+ * so they never share the root's cache file.
+ *
  * ## Nothing from `values` is surfaced
  *
  * A state row's `values` are the resource's full attribute set, secrets
@@ -155,7 +206,8 @@
 import type { DescribeResourcesResult, ResourceMetadata, TeardownEnumeration } from "@intentius/chant/lexicon";
 import { type DeclaredEntity, type UnobservedReason } from "@intentius/chant/observation";
 import type { OwnershipMarker } from "@intentius/chant/ownership";
-import { choudoufuLiveLs, choudoufuLivePlanDocument, terraformInit, terraformShow } from "./op/activities/terraform.js";
+import { choudoufuLiveLs, choudoufuLivePlanDocument, terraformInit, terraformPlanRead, terraformShow } from "./op/activities/terraform.js";
+import type { TerraformObserveDepth } from "./config.js";
 export { TERRAFORM_STATE_OWNERSHIP_KEYS } from "./state-ownership.js";
 export { TERRAFORM_LIVE_MARKER_KEYS } from "./live-ownership.js";
 /** One row out of `values.root_module.resources[]`, at any module depth. */
@@ -315,6 +367,26 @@ export type InstanceVerdict = {
  * (choudoufu #962, chant #2241).
  */
 export declare function classifyLiveInstance(address: string, index: LivePlanIndex): InstanceVerdict;
+/**
+ * The environment variable that asks for each live root's `live-plan -json`
+ * document as a file, in a directory the caller owns (behold#924).
+ *
+ * The overlay keeps chant's verdict per block and drops the rows behind it:
+ * each instance's omission reason and detail, `identity_values`, the adoptable
+ * row's own fields. A caller that paints ownership from those rows and wants
+ * the plan's attributes from the plan depth would otherwise run its own
+ * `live-plan` beside this one, two refreshes of the estate that can disagree
+ * (choudoufu #1014). With this set to an absolute directory, the document this
+ * read used is written there as `<root>.live-plan.json`, so the caller reads
+ * the same `live-plan` the verdicts came from.
+ *
+ * Opt-in, and never inside the root: a relative path is ignored, so nothing
+ * lands in the root by accident (#4379). A write that fails is ignored too;
+ * the read answers either way, and the caller sees no file.
+ */
+export declare const TERRAFORM_LIVE_PLAN_DIR_ENV = "CHANT_TERRAFORM_LIVE_PLAN_DIR";
+/** The file {@link TERRAFORM_LIVE_PLAN_DIR_ENV} names for a root: the root's name, made safe for a file name. */
+export declare function livePlanDocumentFile(root: string): string;
 /** One `items[]` entry of a `live-ls -json` listing. */
 export interface LiveLsItem {
     /** ARN or other stable identity. */
@@ -421,6 +493,11 @@ export interface TerraformReadDeps {
     /** The document alone (chant #2498): this reader indexes it and never reads the human render. */
     livePlan: typeof choudoufuLivePlanDocument;
     liveLs: typeof choudoufuLiveLs;
+    /**
+     * The plan depth's read (#4358). Optional so a test that never asks for the
+     * plan depth need not stub it; omitted, the real activity runs.
+     */
+    planRead?: typeof terraformPlanRead;
 }
 /** A declared entity, plus the root, address and mode `buildRoots()` recorded on it. */
 export interface TerraformDeclared extends DeclaredEntity {
@@ -448,6 +525,14 @@ export declare function declaredOf(name: string, entity: {
     entityType: string;
     props: Record<string, unknown>;
 } | undefined): TerraformDeclared;
+/** Which read answered a plan-depth root. */
+export type PlanDepthAnswer = "plan" | "state" | "declared";
+/** Does this text name a credentials or authorization failure? Exported for the fallback tests. */
+export declare function planFailureIsCredentials(text: string): boolean;
+/** Which reads answered a live root at the plan depth (#4371). */
+export type LivePlanDepthAnswer = "live+plan" | "live";
+/** The environment variable that overrides every root's observation depth for one run (#4358). */
+export declare const TERRAFORM_OBSERVE_ENV = "CHANT_TERRAFORM_OBSERVE";
 export interface DescribeResourcesOptions {
     environment: string;
     buildOutput: string;
@@ -467,6 +552,14 @@ export interface DescribeResourcesOptions {
      * the running process's cwd. Same meaning as `TerraformWatchOpConfig.cwd`.
      */
     cwd?: string;
+    /**
+     * Read every stock root at this depth (#4358), over the config's
+     * `terraform.observe` and `terraform.roots.<name>.observe` and the
+     * `CHANT_TERRAFORM_OBSERVE` variable. Not a core option: a caller holding
+     * this lexicon directly (behold) passes it, and the CLI reaches it through
+     * the config or the variable.
+     */
+    depth?: TerraformObserveDepth;
 }
 /**
  * Observe every declared terraform entity, one `init` + `show` per configured