@intentius/chant 0.124.52 → 0.124.54

package/dist/drift-record.d.ts

@@ -0,0 +1,542 @@
+/**
+ * One drift record across engines (#4450, #4451).
+ *
+ * Drift had four vocabularies for one question: the converge observers'
+ * `in-sync | drifted | unknown` (`./lifecycle/symptoms.ts`), component
+ * status's `reconciled | unrecorded | stale | drifted | unknown`
+ * (`./lifecycle/status.ts`), the graph overlay's tones, and the live diff's
+ * buckets (`./lifecycle/live-diff.ts`). A renderer colouring a terraform, a
+ * choudoufu and a chant member side by side had to know all four, and behold
+ * read choudoufu's documents itself. This module is the one shape they all
+ * become: a {@link DriftRecord} per resource instance, and a
+ * {@link DriftDocument} (`drift: "v1"`) that holds them. Its schema is
+ * `./workspace/drift.schema.json`, `$id` {@link DRIFT_SCHEMA_ID}.
+ *
+ * A record says which read answered (`read`) and what it found (`status`).
+ * The two travel together because they are different claims: a `state` read
+ * says what the last apply recorded and can never say the account matches,
+ * so {@link driftRecord} refuses a state read whose status is anything but
+ * `recorded`, `pending` or `not-observed`. Every record goes through that
+ * constructor, so the rule holds for every adapter, and for a document read
+ * back with {@link parseDriftDocument}.
+ *
+ * `not-observed` is never absence. It always carries a reason from the
+ * observation contract's closed list (`./observation.ts`), and
+ * `not-reached` is the reason a stream gives an address it expected and
+ * never heard about ({@link driftSettle}).
+ *
+ * ## Redaction
+ *
+ * An attribute the planner marked sensitive keeps its path and loses both
+ * values (`sensitive: true`), as the change set spells it
+ * (`./change-set.ts`). A second pass redacts any path with a segment
+ * {@link isSensitiveKey} names, whatever the planner said, so an engine
+ * that marks nothing still never ships a `password` value. Values are
+ * optional: a card needs only the names.
+ *
+ * ## Not digest-bound
+ *
+ * A drift read authorizes nothing and goes stale on the next read, so a
+ * record is ephemeral. {@link driftDocumentDigest} exists for one case, a
+ * WatchOp writing its document into its own run ledger as evidence, and
+ * leaves out `observedAt` and `evidence`, which change on every read.
+ *
+ * ## Adapters
+ *
+ * The chant ones are here: `lifecycle diff --live` ({@link liveDiffDriftRecords}),
+ * deep observe ({@link deepDiffDriftRecords}, {@link mergeDeepDrift}) and
+ * component status ({@link componentStatusDriftRecords}). The terraform and
+ * choudoufu ones live in the terraform lexicon's `drift-record` subpath,
+ * beside its readers, and the Pulumi one (`refresh --preview-only`, #4453)
+ * in the pulumi lexicon's.
+ *
+ * ## The graph and the rollup
+ *
+ * A record's `node` and `instanceOf` come from the change set's own rule
+ * (`graphNodeFor`, #4454), and a block's status from core's one rollup
+ * (`rollupInstances`) over {@link DRIFT_INSTANCE_ROLLUP}. Neither is
+ * written a second time here.
+ *
+ * ## The import graph
+ *
+ * This module ships in the change-set bundle (`change-set-bundle.test.ts`,
+ * #3421): at run time it imports the plan digest, the observation
+ * contract's reason list, the change-set graph's node rule, the instance
+ * rollup and the sensitive-key list, and types only otherwise.
+ */
+import { type ChangeSetGraphNodes } from "./change-set-graph.js";
+import type { ChangeSetPlanner } from "./change-set.js";
+import type { DeepDiffResult } from "./lifecycle/deep-diff.js";
+import type { LiveDiffResult } from "./lifecycle/live-diff.js";
+import type { ComponentStatusRow } from "./lifecycle/status.js";
+import { type UnobservedReason } from "./observation.js";
+/** The schema a drift document names in `$schema`. */
+export declare const DRIFT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/drift/v1/drift.schema.json";
+/** The document's version. */
+export declare const DRIFT_VERSION = "v1";
+/**
+ * Which engine read the resource: a change-set planner (`pulumi` among them
+ * since #4453), or plunge, which has no planner of its own. A plunge
+ * address is a Pulumi URN, so a plunge record is placed on the graph by the
+ * `pulumi` planner's rule ({@link driftPlanner}).
+ */
+export type DriftEngine = ChangeSetPlanner | "plunge";
+/** The planner whose node rule places an engine's records: plunge's URNs go by `pulumi`'s (#4453). */
+export declare function driftPlanner(engine: DriftEngine): ChangeSetPlanner;
+/** Every engine, in the order the schema lists them. */
+export declare const DRIFT_ENGINES: readonly DriftEngine[];
+/**
+ * Which read answered.
+ *
+ * - `state` — the engine's state file: what the last apply recorded.
+ * - `plan` — a plan: what the next apply would do, after a refresh.
+ * - `refresh` — a refresh preview (Pulumi's `refresh --preview-only`).
+ * - `live-read` — chant's own read of the provider.
+ * - `ownership` — an ownership read (choudoufu's `live-plan` and `live-ls`),
+ *   which says who holds each object and not what its attributes are.
+ */
+export type DriftRead = "state" | "plan" | "refresh" | "live-read" | "ownership";
+/** Every read, in the order the schema lists them. */
+export declare const DRIFT_READS: readonly DriftRead[];
+/**
+ * What the read found.
+ *
+ * - `in-sync` — present, and nothing the read compares differs.
+ * - `drifted` — present, and something differs; `attributes` says what.
+ * - `pending` — declared and confirmed absent, never deployed.
+ * - `missing` — recorded or deployed, and now gone.
+ * - `unclaimed` — something live sits at a declared identity and does not
+ *   carry this member's marker: adoptable, or held by someone else.
+ * - `undeclared` — live or recorded, and the member does not declare it.
+ * - `runtime` — live, undeclared, and expected: a controller's child.
+ * - `recorded` — in the engine's state. The only presence a state read gives.
+ * - `not-observed` — the read could not say; `unobserved` says why.
+ */
+export type DriftStatus = "in-sync" | "drifted" | "pending" | "missing" | "unclaimed" | "undeclared" | "runtime" | "recorded" | "not-observed";
+/** Every status, in the order the schema lists them. */
+export declare const DRIFT_STATUSES: readonly DriftStatus[];
+/** The only statuses a `state` read may give. It never says in-sync or drifted. */
+export declare const STATE_READ_STATUSES: readonly DriftStatus[];
+/** Who an ownership facet says holds the object. */
+export type DriftOwnershipVerdict = "owned" | "foreign" | "adoptable" | "unknown";
+/** Every ownership verdict. */
+export declare const DRIFT_OWNERSHIP_VERDICTS: readonly DriftOwnershipVerdict[];
+/** What the ownership verdict rests on. */
+export type DriftOwnershipBy = "marker" | "derived" | "record" | "cache" | "state" | "label";
+/** Every ownership basis. */
+export declare const DRIFT_OWNERSHIP_BY: readonly DriftOwnershipBy[];
+/**
+ * One attribute that differs. `before` is what was expected (the record, the
+ * snapshot, the declaration) and `after` what the read found. A path in the
+ * plan-observation grammar: keys joined with `.`, indexes and keys that are
+ * not identifiers in brackets (`tags["kubernetes.io/role"]`).
+ */
+export interface DriftAttribute {
+    path: string;
+    before?: unknown;
+    after?: unknown;
+    /** The planner marked it sensitive, or its name looks secret-bearing, so neither value is carried. */
+    sensitive?: true;
+}
+/** Why a record is `not-observed`. */
+export interface DriftUnobserved {
+    reason: UnobservedReason;
+    detail?: string;
+    /** The address the read was issued against, when the engine reported one. */
+    queried?: string;
+}
+/** Who holds the object, from an ownership read. */
+export interface DriftOwnership {
+    verdict: DriftOwnershipVerdict;
+    by?: DriftOwnershipBy;
+    /** The marker was read off the object itself, not derived or remembered. */
+    markerOnObject?: boolean;
+    /** The estate, stack or controller that does hold it, when not this member. */
+    ownedBy?: string;
+    /** The address an adoption would write onto the object. */
+    adopt?: string;
+}
+/** What produced the record. */
+export interface DriftEvidence {
+    tool: string;
+    version?: string;
+    command?: string;
+    /** The engine's own token for the verdict (`UNOWNED`, `NEEDS_DISCOVERY`, `ABSENT`), so a pane can show it. */
+    engineCode?: string;
+}
+export interface DriftRecord {
+    member: string;
+    engine: DriftEngine;
+    /** The engine's own address, at instance level: `aws_eip.pool[0]`, a Pulumi URN, a chant entity name. */
+    address: string;
+    /** The resource type, when the read reports one. Not `type`, which a stream line uses for its kind. */
+    resourceType?: string;
+    /**
+     * The graph node, by the change set's mapping rules (`graphNodeFor` in
+     * `./change-set-graph.ts`, {@link mapDriftToGraph}): for an instance of a
+     * `count` or `for_each` block the instance node, `<blockNode>[0]` or
+     * `<blockNode>["a"]`, and the block node otherwise. Null when the graph
+     * holds none. A Pulumi URN's node is `<member>/<key>` by the URN rule
+     * (#4456), and a plunge URN's by the same rule (#4453).
+     */
+    node: string | null;
+    /** On a record whose `node` is an instance node (#4454): the block node it is an instance of, the rollup. */
+    instanceOf?: string;
+    /** RFC 3339. Per record, because a stream's rows finish at different times. */
+    observedAt: string;
+    read: DriftRead;
+    /**
+     * The read that was asked for and failed, when this one answered instead:
+     * what `RootRead.depth` holds (`"plan"`, `"live+plan"`) on a root whose
+     * `RootRead.fellBackTo` is set (`./observation.ts`).
+     */
+    fellBackFrom?: string;
+    status: DriftStatus;
+    /** Set exactly when `status` is `not-observed`. */
+    unobserved?: DriftUnobserved;
+    /** What differs. Only on `drifted`. */
+    attributes?: DriftAttribute[];
+    /**
+     * Presence is known and the attributes are not: a deep read that failed
+     * for an entity the thin read found. On `in-sync` and `drifted` only.
+     */
+    attributesUnobserved?: DriftUnobserved;
+    ownership?: DriftOwnership;
+    evidence: DriftEvidence;
+}
+/** Counts per status, every status present. */
+export type DriftCounts = Record<DriftStatus, number>;
+export interface DriftDocument {
+    $schema: typeof DRIFT_SCHEMA_ID;
+    drift: typeof DRIFT_VERSION;
+    /** The chant that wrote it, when known. */
+    chant?: string;
+    /** Sorted by member, address and read. One per `(member, address, read)`. */
+    records: DriftRecord[];
+    counts: DriftCounts;
+}
+/** Which rule a refused record broke. */
+export type DriftRecordRule = "shape" | "state-read-status" | "unobserved-reason" | "unobserved-on-observed" | "attributes-status" | "attributes-unobserved-status";
+/** A record {@link driftRecord} refused, naming the record and the rule. */
+export declare class DriftRecordError extends Error {
+    readonly rule: DriftRecordRule;
+    constructor(rule: DriftRecordRule, message: string);
+}
+/**
+ * The key segments of an attribute path, indexes left out:
+ * `spec.env[0]["db_password"]` is `spec`, `env`, `db_password`. A keyed
+ * element (`Tags[#api-token-owner].Value`, the deep read's address for an
+ * array it can key) is a key too: it names the element the way a map key
+ * does, so an environment list keyed by `DB_PASSWORD` redacts like a map's.
+ */
+export declare function attributePathKeys(path: string): string[];
+/**
+ * One attribute, redacted: the planner's mark first, then any key segment
+ * {@link isSensitiveKey} names. A redacted attribute is `{ path, sensitive:
+ * true }` and nothing else.
+ */
+export declare function redactDriftAttribute(attribute: DriftAttribute): DriftAttribute;
+/**
+ * Build one record, or refuse it. Every adapter and every reader goes
+ * through here, so these hold for every record that exists:
+ *
+ * - a `state` read's status is `recorded`, `pending` or `not-observed`;
+ * - `not-observed` carries `unobserved` with a legal reason, and no other
+ *   status carries it;
+ * - `attributes` appear only on `drifted`, sorted by path, one per path,
+ *   and redacted ({@link redactDriftAttribute});
+ * - `attributesUnobserved` appears only on `in-sync` or `drifted`.
+ *
+ * A refusal is a {@link DriftRecordError} naming the member, the address,
+ * the read and the status.
+ */
+export declare function driftRecord(input: DriftRecord): DriftRecord;
+/** Read one record from parsed JSON. The same checks as {@link driftRecord}. */
+export declare function parseDriftRecord(value: unknown): DriftRecord;
+/** Counts per status, zero included. */
+export declare function countDriftStatuses(records: Iterable<Pick<DriftRecord, "status">>): DriftCounts;
+export interface DriftDocumentOptions {
+    /** The chant version to record in `chant`. */
+    chant?: string;
+}
+/**
+ * Join records into one document. A later record for the same `(member,
+ * address, read)` replaces the earlier one, as a stream's later line does.
+ * Records are sorted by member, address and read. Every record is checked
+ * with {@link driftRecord}.
+ */
+export declare function driftDocument(records: Iterable<DriftRecord>, options?: DriftDocumentOptions): DriftDocument;
+/** Read a document from parsed JSON, checking every record. Counts are recomputed. */
+export declare function parseDriftDocument(value: unknown): DriftDocument;
+/**
+ * The document's digest, for a WatchOp that keeps its document as evidence
+ * in its own run ledger: `computePlanDigest("drift-document", …)` over the
+ * records sorted as {@link driftDocument} sorts them, without `observedAt`
+ * and `evidence`, which change on every read. No gate binds it.
+ */
+export declare function driftDocumentDigest(doc: Pick<DriftDocument, "records">): string;
+/**
+ * The precedence a block's instance records roll up in, most significant
+ * first, for core's one rollup (`rollupInstances` in `./instance-nodes.ts`,
+ * #4454). Partial knowledge is not knowledge, so one not-observed instance
+ * makes the block not-observed, as `TERRAFORM_INSTANCE_ROLLUP` puts
+ * `unobserved` first. A difference outranks an absence, an absence
+ * outranks agreement, and `runtime` is last because a controller's children
+ * never decide a block.
+ */
+export declare const DRIFT_INSTANCE_ROLLUP: readonly DriftStatus[];
+/** One block node's rolled-up status and the records it came from. */
+export interface DriftBlockRollup {
+    /** The block node: the records' `instanceOf`, or their `node` when they are on the block itself. */
+    node: string;
+    status: DriftStatus;
+    /** Every read that answered for the block's records, sorted. */
+    reads: DriftRead[];
+    records: DriftRecord[];
+}
+/**
+ * Records grouped by block node (`instanceOf`, else `node`) and rolled up
+ * with `rollupInstances` over {@link DRIFT_INSTANCE_ROLLUP}. A record with a
+ * null `node` is on no block and is left out. Sorted by node.
+ */
+export declare function rollupDriftByBlock(records: Iterable<DriftRecord>): DriftBlockRollup[];
+/**
+ * The document with each record's `node` and `instanceOf` set from `graph`
+ * by `graphNodeFor` (`./change-set-graph.ts`), the rule a change-set entry
+ * uses, so a drift row and a change-set entry for one instance name the
+ * same node: an instance of a `count` or `for_each` block is on
+ * `<blockNode>[0]` with `instanceOf` the block node, and an instance under
+ * an expanded module call is on `<root>/module.app[0]/<block>[1]` with the
+ * same `instanceOf` (#4486). A Pulumi URN is on
+ * `<member>/<key>` by the URN rule (`./pulumi-urn.ts`, #4456), through the
+ * `pulumi` planner's case, and so is a plunge URN ({@link driftPlanner}).
+ * A null `graph` gives every record `node: null`.
+ */
+export declare function mapDriftToGraph(doc: DriftDocument, graph: ChangeSetGraphNodes | null): DriftDocument;
+/**
+ * The NDJSON stream, one JSON object per line, built like the run-event
+ * stream and in the layout choudoufu's `live-plan -resource` writes
+ * (choudoufu `internal/command/views/live_drift.go`): every line has a
+ * `type`, `drift-start`, `drift-record` or `drift-settle`, and a record
+ * line is the record itself with `type` beside its fields.
+ */
+/** One address a stream expects to hear about, with the node and type a not-reached record should carry. */
+export interface DriftExpected {
+    address: string;
+    node?: string | null;
+    instanceOf?: string;
+    resourceType?: string;
+}
+/** Opens a member's read: which member, engine and read, and every address it expects. */
+export interface DriftStartLine {
+    type: "drift-start";
+    drift: typeof DRIFT_VERSION;
+    member: string;
+    engine: DriftEngine;
+    read: DriftRead;
+    /** The one address the read was asked about, on a single-resource read (`live-plan -resource`). */
+    resource?: string;
+    fellBackFrom?: string;
+    /** RFC 3339, when the writer gives it. */
+    at?: string;
+    /** Bare addresses, or addresses with the node and type a not-reached record is given. */
+    expected: Array<string | DriftExpected>;
+    /** The evidence a not-reached record is given. Default `{ tool: <engine> }`. */
+    evidence?: DriftEvidence;
+}
+/** One record, as its read finishes: the record's own fields beside `type`. A later line for the same `(member, address, read)` replaces it. */
+export type DriftRecordLine = DriftRecord & {
+    type: "drift-record";
+};
+/** Closes a member's read. */
+export interface DriftSettleLine {
+    type: "drift-settle";
+    drift: typeof DRIFT_VERSION;
+    member: string;
+    engine: DriftEngine;
+    read: DriftRead;
+    /** Records per status. A writer may leave out a status it has none of. */
+    counts: Partial<DriftCounts>;
+    /** The engine's own account of what the read cost (choudoufu: `recordsRead`, `sweepCalls`, ...). Carried, never interpreted. */
+    reads?: Record<string, unknown>;
+    /** RFC 3339, when the writer gives it: every not-reached record's `observedAt`. */
+    at?: string;
+    /**
+     * Expected addresses with no record line, when the writer lists them. A
+     * reader treats every expected address with no record as not-reached
+     * whether or not this is given; a writer that emits its own not-reached
+     * records (choudoufu does) leaves it out.
+     */
+    notReached?: string[];
+}
+export type DriftLine = DriftStartLine | DriftRecordLine | DriftSettleLine;
+/** A start line's expected entries, bare addresses made objects. */
+export declare function driftExpected(start: Pick<DriftStartLine, "expected">): DriftExpected[];
+/** A record as its stream line. */
+export declare function driftRecordLine(record: DriftRecord): DriftRecordLine;
+/** One line of the stream, newline-terminated. */
+export declare function encodeDriftLine(line: DriftLine): string;
+/** The whole stream for one or more reads, in order. */
+export declare function encodeDriftLines(lines: Iterable<DriftLine>): string;
+/** Read one line, checking it. A record line goes through {@link driftRecord}. Unknown fields are dropped. */
+export declare function decodeDriftLine(text: string): DriftLine;
+/** Every non-blank line of an NDJSON stream, decoded. */
+export declare function decodeDriftLines(text: string): DriftLine[];
+/** Open a read: the start line for a member's expected addresses, each once. */
+export declare function driftStart(input: Omit<DriftStartLine, "type" | "drift">): DriftStartLine;
+/**
+ * Close a read. `records` are the records sent since `start`, in order; a
+ * later one for an address and read replaces an earlier one, and records
+ * for another member are ignored. A record for an expected address answers
+ * it whatever its read, since one read can answer an address with another
+ * (a plan stream's unclaimed row is an `ownership` record). Every expected
+ * address with no record becomes `not-observed / not-reached` at `at`.
+ * Returns the settle line, which lists them in `notReached`, and the
+ * member's final records.
+ */
+export declare function driftSettle(start: DriftStartLine, records: Iterable<DriftRecord>, at: string): {
+    line: DriftSettleLine;
+    records: DriftRecord[];
+};
+/** An address a started read expects and has not reported yet. Not a status: a settle always resolves it. */
+export interface DriftReading {
+    member: string;
+    read: DriftRead;
+    address: string;
+    node: string | null;
+}
+/**
+ * Fold a stream into a document. Record lines replace earlier ones for the
+ * same `(member, address, read)`. At a settle line, every address its start
+ * expected that no record answered (by member and address, whatever the
+ * read) becomes `not-observed / not-reached`, with the node and type the
+ * start gave, at the settle's `at`, else the start's, else the latest
+ * record's `observedAt` in the stream; `notReached` addresses the start did
+ * not list are added the same way. A start with no settle yet leaves its
+ * unanswered addresses in `reading`, which a renderer shows as "reading"
+ * and nothing else.
+ */
+export declare function foldDriftLines(lines: Iterable<DriftLine>, options?: DriftDocumentOptions): {
+    document: DriftDocument;
+    reading: DriftReading[];
+};
+/** What every adapter takes beside its source document. */
+export interface DriftAdapterBase {
+    member: string;
+    /** RFC 3339, given to every record. */
+    observedAt: string;
+    /**
+     * The member's graph, to place each record with `graphNodeFor` as it is
+     * made. Omit to leave `node` null, for {@link mapDriftToGraph} to fill.
+     */
+    graph?: ChangeSetGraphNodes | null;
+    /** The read that was asked for and failed, when this one answered instead. */
+    fellBackFrom?: string;
+    /** The chant or engine version, for `evidence.version`. */
+    version?: string;
+}
+/**
+ * Where an adapter's record for `address` sits: `graphNodeFor` on the
+ * input's graph, plunge's by the `pulumi` rule ({@link driftPlanner}). Exported
+ * for the lexicons' adapters.
+ */
+export declare function placeDriftRecord(input: Pick<DriftAdapterBase, "member" | "graph">, engine: DriftEngine, address: string): {
+    node: string | null;
+    instanceOf?: string;
+};
+export interface LiveDiffDriftInput extends DriftAdapterBase {
+    /** `chant lifecycle diff --live --json`, parsed. */
+    diff: LiveDiffResult;
+    /** Entity types by name, for the records whose diff row carries none. */
+    types?: Record<string, string>;
+}
+/**
+ * A chant member's records, from `lifecycle diff --live`: `unchanged` and
+ * `newlyObserved` are in-sync, `driftedSinceSnapshot` drifted (before is the
+ * snapshot, after the read), `missing` pending, `disappeared` missing,
+ * `orphan` undeclared, `runtimeChildren` runtime, `unobserved` not-observed.
+ * An entity in both `missing` and `disappeared` was deployed and is gone,
+ * so it is missing.
+ */
+export declare function liveDiffDriftRecords(input: LiveDiffDriftInput): DriftRecord[];
+export interface DeepDiffDriftInput extends DriftAdapterBase {
+    /** `chant lifecycle diff --live --deep --json`'s deep result, parsed. */
+    diff: DeepDiffResult;
+    /**
+     * The command for `evidence.command`, when the deep result came from
+     * somewhere other than a live read: `chant lifecycle diff --index <ref>`
+     * (#4526) diffs against an index version. Default
+     * `chant lifecycle diff --live --deep`.
+     */
+    command?: string;
+}
+/**
+ * A chant member's records from the deep diff alone: `drifted` with paths
+ * (before is the declared value, after the live one; an `absent` path has
+ * no after), `unchanged` in-sync, `unobserved` not-observed and
+ * `undeclaredEntities` undeclared. Accepted and held paths are not drift and
+ * are left out. To lay these over the thin read's records, so a deep hole
+ * stays on the attribute surface, use {@link mergeDeepDrift}.
+ */
+export declare function deepDiffDriftRecords(input: DeepDiffDriftInput): DriftRecord[];
+/**
+ * The thin read's records with the deep read laid over them, by member and
+ * address. A thin in-sync record the deep read found drifted becomes
+ * drifted with the deep paths. A deep not-observed record never changes the
+ * thin status: presence is known, so it becomes `attributesUnobserved` on an
+ * in-sync or drifted record and is dropped elsewhere. Deep records with no
+ * thin record are added as they are.
+ */
+export declare function mergeDeepDrift(thin: Iterable<DriftRecord>, deep: Iterable<DriftRecord>): DriftRecord[];
+export interface ComponentStatusDriftInput extends DriftAdapterBase {
+    /** `chant components status [env] --json`'s rows. */
+    rows: readonly ComponentStatusRow[];
+}
+/**
+ * A member's records from component status, one per component, addressed
+ * by component name: `reconciled` in-sync, `drifted` drifted, `stale`
+ * missing (recorded and no longer observed live), `unknown` not-observed
+ * with the row's reason, or `not-reached` when live status was never asked
+ * for. `unrecorded` is drifted when the component is live, since something
+ * runs that no release accounts for, pending when nothing is, and
+ * not-observed when live status was not asked for.
+ */
+export declare function componentStatusDriftRecords(input: ComponentStatusDriftInput): DriftRecord[];
+/**
+ * What `chant lifecycle drift` asks a lexicon for (`LexiconPlugin.readDrift`,
+ * behold#995). `chant workspace drift` runs that command in a member's reader
+ * project, so a lexicon that reads members of a package kind (the terraform
+ * lexicon's `terraform` and `choudoufu` kinds) answers with its own engine,
+ * and chant core never imports the lexicon.
+ */
+export interface ReadDriftOptions {
+    /** The workspace member the records are for. Every line the lexicon returns names it. */
+    member: string;
+    /** The directory holding the project's `chant.config.*`. */
+    projectRoot: string;
+    /** The project's resolved config, for the lexicon's own namespace. */
+    config: Record<string, unknown>;
+    /** The read asked for. Unset, the lexicon's default read for what it finds. */
+    read?: DriftRead;
+    /** One address to read, on an engine that can read one resource on its own. */
+    resource?: string;
+    /** RFC 3339, the `observedAt` of every record the lexicon builds itself. */
+    observedAt: string;
+}
+/** Why a lexicon will not answer a drift read, in a code a caller can branch on. */
+export type ReadDriftRefusalCode = "read-unsupported" | "resource-unsupported" | "no-drift-read";
+/**
+ * A lexicon's answer: the stream lines of each read it ran, in order (a
+ * `drift-start`, its records, a `drift-settle`, per root), or a refusal. A
+ * read that ran and failed is not a refusal: its addresses are records
+ * with status `not-observed`.
+ */
+export type ReadDriftResult = {
+    lines: DriftLine[];
+} | {
+    refused: {
+        code: ReadDriftRefusalCode;
+        message: string;
+    };
+};
+//# sourceMappingURL=drift-record.d.ts.map

package/dist/drift-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-record.d.ts","sourceRoot":"","sources":["../src/drift-record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAG1E,sDAAsD;AACtD,eAAO,MAAM,eAAe,4EAA4E,CAAC;AAEzG,8BAA8B;AAC9B,eAAO,MAAM,aAAa,OAAO,CAAC;AAElC;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEtD,sGAAsG;AACtG,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CAElE;AAaD,wDAAwD;AACxD,eAAO,MAAM,aAAa,EAAwC,SAAS,WAAW,EAAE,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAC;AAIjF,sDAAsD;AACtD,eAAO,MAAM,WAAW,EAAsC,SAAS,SAAS,EAAE,CAAC;AAEnF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,SAAS,GACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,YAAY,GACZ,SAAS,GACT,UAAU,GACV,cAAc,CAAC;AAcnB,wDAAwD;AACxD,eAAO,MAAM,cAAc,EAAwC,SAAS,WAAW,EAAE,CAAC;AAE1F,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,EAAE,SAAS,WAAW,EAA4C,CAAC;AAEnG,oDAAoD;AACpD,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAIlF,+BAA+B;AAC/B,eAAO,MAAM,wBAAwB,EAA6C,SAAS,qBAAqB,EAAE,CAAC;AAEnH,2CAA2C;AAC3C,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAI7F,6BAA6B;AAC7B,eAAO,MAAM,kBAAkB,EAAwC,SAAS,gBAAgB,EAAE,CAAC;AAEnG;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sGAAsG;IACtG,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,EAAE,CAAC,EAAE,gBAAgB,CAAC;IACtB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,gCAAgC;AAChC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8GAA8G;IAC9G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,yGAAyG;IACzG,OAAO,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,6GAA6G;IAC7G,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,mDAAmD;IACnD,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,uCAAuC;IACvC,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,eAAe,CAAC;IACvC,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,+CAA+C;AAC/C,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,KAAK,EAAE,OAAO,aAAa,CAAC;IAC5B,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,yCAAyC;AACzC,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,mBAAmB,GACnB,mBAAmB,GACnB,wBAAwB,GACxB,mBAAmB,GACnB,8BAA8B,CAAC;AAEnC,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,YAAY,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAIjD;CACF;AASD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmCxD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,cAAc,GAAG,cAAc,CAS9E;AAiCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CA4F3D;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAG5D;AAMD,wCAAwC;AACxC,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,GAAG,WAAW,CAI9F;AAED,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAc/G;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAKhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,GAAG,MAAM,CAK/E;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,WAAW,EAUvD,CAAC;AAEF,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,oGAAoG;IACpG,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,gEAAgE;IAChE,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,gBAAgB,EAAE,CAiBrF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,GAAG,aAAa,CASpG;AAID;;;;;;GAMG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,EAAE,OAAO,aAAa,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,QAAQ,EAAE,KAAK,CAAC,MAAM,GAAG,aAAa,CAAC,CAAC;IACxC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED,gJAAgJ;AAChJ,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC;AAErE,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,OAAO,aAAa,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,0EAA0E;IAC1E,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,gIAAgI;IAChI,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,mFAAmF;IACnF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,eAAe,GAAG,eAAe,CAAC;AAE3E,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,CAAC,GAAG,aAAa,EAAE,CAEtF;AAED,mCAAmC;AACnC,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAEpE;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEvD;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,MAAM,CAInE;AAUD,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAsEvD;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,CAM1D;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,cAAc,CAOxF;AAqBD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,CA8BhJ;AAED,6GAA6G;AAC7G,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAE,oBAAyB,GAAG;IAAE,QAAQ,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,CAsCnJ;AAID,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,CAAC,gBAAgB,EAAE,QAAQ,GAAG,OAAO,CAAC,EACjD,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAI9C;AAkBD,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,oDAAoD;IACpD,IAAI,EAAE,cAAc,CAAC;IACrB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,WAAW,EAAE,CA2B7E;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,yEAAyE;IACzE,IAAI,EAAE,cAAc,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,WAAW,EAAE,CA4B7E;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,WAAW,EAAE,CAiBtG;AAED,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,qDAAqD;IACrD,IAAI,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,yBAAyB,GAAG,WAAW,EAAE,CA4B3F;AAID;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+EAA+E;IAC/E,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GAAG,sBAAsB,GAAG,eAAe,CAAC;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,SAAS,EAAE,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE;QAAE,IAAI,EAAE,oBAAoB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC"}