domainkit 0.12.2 → 0.14.0

package/dist/types/Server.d.ts

@@ -30,9 +30,27 @@ import * as Reason from "./Reason.ts";
 import * as Receipt from "./Receipt.ts";
 import * as Storage from "./Storage.ts";
 import * as Verify from "./Verify.ts";
+/**
+ * What DomainKit already knows about the request when it asks the host who is making it. Only
+ * `/callback/:provider` passes one, because it is the only route that points at a flow DomainKit
+ * recorded earlier; every other route calls `principal` with the request alone.
+ */
+export interface IdentityContext {
+    /** The route being served. */
+    readonly endpoint: EndpointName;
+    /** The flow this callback claims to finish, as DomainKit recorded it when the flow started. */
+    readonly continuation: Storage.ContinuationHeader;
+}
 /** The only service a host must implement for the server. */
 export interface IdentityService {
-    readonly principal: (request: HttpServerRequest.HttpServerRequest) => Effect.Effect<Principal.Interface, Errors.DomainKitError>;
+    /**
+     * `context` is present only on the callback, where a host that keeps per-request tenancy can use
+     * `context.continuation.ownerId` to pick the right tenant out of a session that holds several.
+     * Ignoring it is safe everywhere: DomainKit checks the principal against the recorded flow on
+     * that route regardless, so a host that answers with the wrong one is refused rather than
+     * trusted.
+     */
+    readonly principal: (request: HttpServerRequest.HttpServerRequest, context?: IdentityContext) => Effect.Effect<Principal.Interface, Errors.DomainKitError>;
     /**
      * Which routes this principal may reach, checked after `principal` on every request. Fail with
      * reason `Forbidden` for the 403 a UI expects. Without it every authenticated principal reaches
@@ -324,6 +342,8 @@ export declare const Readiness: Schema.Struct<{
     readonly attachmentId: Schema.NullOr<Schema.String>;
     readonly overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
     readonly requirements: Schema.$Array<Schema.Struct<{
+        /** `Verify.requirementKey(record)`, so a client pairs rows by content, not by position. */
+        readonly key: Schema.String;
         readonly operationId: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/OperationId">>;
         readonly record: Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>;
         readonly status: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
@@ -4490,6 +4510,8 @@ export declare const group: HttpApiGroup.HttpApiGroup<"domainkit", HttpApiEndpoi
     readonly attachmentId: Schema.NullOr<Schema.String>;
     readonly overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
     readonly requirements: Schema.$Array<Schema.Struct<{
+        /** `Verify.requirementKey(record)`, so a client pairs rows by content, not by position. */
+        readonly key: Schema.String;
         readonly operationId: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/OperationId">>;
         readonly record: Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>;
         readonly status: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
@@ -5326,6 +5348,431 @@ export declare const group: HttpApiGroup.HttpApiGroup<"domainkit", HttpApiEndpoi
     };
 }>, Schema.TaggedStruct<"DomainKitError", {
     readonly reason: Schema.suspend<Schema.Union<readonly [typeof Reason.InvalidInput, typeof Reason.Unauthenticated, typeof Reason.Forbidden, typeof Reason.NotFound, typeof Reason.Conflict, typeof Reason.Stale, typeof Reason.Expired, typeof Reason.Busy, typeof Reason.ProviderRejected, typeof Reason.ProviderUnavailable, typeof Reason.ProviderConflict, typeof Reason.Unsupported, typeof Reason.Reconnect, typeof Reason.StorageFailed, typeof Reason.CryptoFailed, typeof Reason.ResolverFailed]>>;
+}>, never, never>>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"readiness", "GET", "/domains/:domain/readiness", Schema.toCodecStringTree<Schema.Struct<{
+    domain: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.NullOr<Schema.Struct<{
+    readonly domain: Schema.String;
+    readonly attachmentId: Schema.NullOr<Schema.String>;
+    readonly overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
+    readonly requirements: Schema.$Array<Schema.Struct<{
+        /** `Verify.requirementKey(record)`, so a client pairs rows by content, not by position. */
+        readonly key: Schema.String;
+        readonly operationId: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/OperationId">>;
+        readonly record: Schema.Union<readonly [typeof DnsRecord.A, typeof DnsRecord.AAAA, typeof DnsRecord.CNAME, typeof DnsRecord.TXT, typeof DnsRecord.MX, typeof DnsRecord.CAA, typeof DnsRecord.NS, typeof DnsRecord.SRV]>;
+        readonly status: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
+        readonly evidence: Schema.$Array<Schema.Union<readonly [typeof Verify.ProviderEvidence, typeof Verify.PublicDnsEvidence, typeof Verify.HostEvidence]>>;
+    }>>;
+    readonly host: Schema.$Array<typeof Verify.HostEvidence>;
+    readonly checkedAt: Schema.DateTimeUtcFromString;
+    readonly nextCheckAt: Schema.NullOr<Schema.DateTimeUtcFromString>;
+}>>>, Schema.toCodecJson<Schema.decodeTo<Schema.declareConstructor<Errors.DomainKitError, {
+    readonly _tag: "DomainKitError";
+    readonly reason: {
+        readonly _tag: "InvalidInput";
+        readonly message: string;
+        readonly field?: string;
+    } | {
+        readonly _tag: "Unauthenticated";
+        readonly message: string;
+    } | {
+        readonly _tag: "Forbidden";
+        readonly message: string;
+    } | {
+        readonly _tag: "NotFound";
+        readonly entity: "approval" | "attachment" | "authorization" | "connection" | "continuation" | "plan" | "provider" | "receipt" | "record" | "zone";
+        readonly id: string;
+    } | {
+        readonly _tag: "Conflict";
+        readonly planId: string;
+        readonly operations: readonly {
+            readonly _tag: "Conflict";
+            readonly id: string;
+            readonly record: {
+                readonly _tag: "A";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "AAAA";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "CNAME";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string;
+            } | {
+                readonly _tag: "TXT";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "MX";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly exchange: string;
+                readonly priority: number;
+            } | {
+                readonly _tag: "CAA";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly flags: number;
+                readonly tag: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "NS";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly nameserver: string;
+            } | {
+                readonly _tag: "SRV";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string;
+                readonly port: number;
+                readonly priority: number;
+                readonly weight: number;
+            };
+            readonly existing: readonly ({
+                readonly _tag: "A";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "AAAA";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "CNAME";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string;
+            } | {
+                readonly _tag: "TXT";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "MX";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly exchange: string;
+                readonly priority: number;
+            } | {
+                readonly _tag: "CAA";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly flags: number;
+                readonly tag: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "NS";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly nameserver: string;
+            } | {
+                readonly _tag: "SRV";
+                readonly name: string;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string;
+                readonly port: number;
+                readonly priority: number;
+                readonly weight: number;
+            } | {
+                readonly _tag: "Opaque";
+                readonly name: string;
+                readonly type: string;
+                readonly raw: unknown;
+            })[];
+            readonly reason: "cname-collision" | "exclusive-name" | "missing" | "opaque" | "value-mismatch";
+        }[];
+    } | {
+        readonly _tag: "Stale";
+        readonly planId: string;
+        readonly digest: string;
+    } | {
+        readonly _tag: "Expired";
+        readonly entity: "approval" | "continuation" | "credential" | "plan";
+        readonly id: string;
+    } | {
+        readonly _tag: "Busy";
+        readonly key: string;
+    } | {
+        readonly _tag: "ProviderRejected";
+        readonly provider: string;
+        readonly code?: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "ProviderUnavailable";
+        readonly provider: string;
+        readonly retryAfterMs?: number;
+        readonly message: string;
+    } | {
+        readonly _tag: "ProviderConflict";
+        readonly provider: string;
+        readonly code?: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "Unsupported";
+        readonly provider: string;
+        readonly operation: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "Reconnect";
+        readonly provider: string;
+        readonly connectionId: string;
+    } | {
+        readonly _tag: "StorageFailed";
+        readonly operation: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "CryptoFailed";
+        readonly operation: "digest" | "open" | "seal";
+    } | {
+        readonly _tag: "ResolverFailed";
+        readonly resolver: string;
+        readonly message: string;
+    };
+}, readonly [Schema.TaggedStruct<"DomainKitError", {
+    readonly reason: Schema.suspend<Schema.Union<readonly [typeof Reason.InvalidInput, typeof Reason.Unauthenticated, typeof Reason.Forbidden, typeof Reason.NotFound, typeof Reason.Conflict, typeof Reason.Stale, typeof Reason.Expired, typeof Reason.Busy, typeof Reason.ProviderRejected, typeof Reason.ProviderUnavailable, typeof Reason.ProviderConflict, typeof Reason.Unsupported, typeof Reason.Reconnect, typeof Reason.StorageFailed, typeof Reason.CryptoFailed, typeof Reason.ResolverFailed]>>;
+}>], {
+    readonly _tag: "DomainKitError";
+    readonly reason: {
+        readonly _tag: "InvalidInput";
+        readonly message: string;
+        readonly field?: string;
+    } | {
+        readonly _tag: "Unauthenticated";
+        readonly message: string;
+    } | {
+        readonly _tag: "Forbidden";
+        readonly message: string;
+    } | {
+        readonly _tag: "NotFound";
+        readonly entity: "approval" | "attachment" | "authorization" | "connection" | "continuation" | "plan" | "provider" | "receipt" | "record" | "zone";
+        readonly id: string;
+    } | {
+        readonly _tag: "Conflict";
+        readonly planId: string & import("effect/Brand").Brand<"@domainkit/PlanId">;
+        readonly operations: readonly {
+            readonly _tag: "Conflict";
+            readonly id: string & import("effect/Brand").Brand<"@domainkit/OperationId">;
+            readonly record: {
+                readonly _tag: "A";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "AAAA";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "CNAME";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+            } | {
+                readonly _tag: "TXT";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "MX";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly exchange: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly priority: number;
+            } | {
+                readonly _tag: "CAA";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly flags: number;
+                readonly tag: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "NS";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly nameserver: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+            } | {
+                readonly _tag: "SRV";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly port: number;
+                readonly priority: number;
+                readonly weight: number;
+            };
+            readonly existing: readonly ({
+                readonly _tag: "A";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "AAAA";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly address: string;
+            } | {
+                readonly _tag: "CNAME";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+            } | {
+                readonly _tag: "TXT";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "MX";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly exchange: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly priority: number;
+            } | {
+                readonly _tag: "CAA";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly flags: number;
+                readonly tag: string;
+                readonly value: string;
+            } | {
+                readonly _tag: "NS";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly nameserver: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+            } | {
+                readonly _tag: "SRV";
+                readonly name: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly ttl: number | null;
+                readonly policy: "append" | "exclusive";
+                readonly purpose?: string;
+                readonly target: string & import("effect/Brand").Brand<"@domainkit/DomainName">;
+                readonly port: number;
+                readonly priority: number;
+                readonly weight: number;
+            } | {
+                readonly _tag: "Opaque";
+                readonly name: string;
+                readonly type: string;
+                readonly raw: unknown;
+            })[];
+            readonly reason: "cname-collision" | "exclusive-name" | "missing" | "opaque" | "value-mismatch";
+        }[];
+    } | {
+        readonly _tag: "Stale";
+        readonly planId: string & import("effect/Brand").Brand<"@domainkit/PlanId">;
+        readonly digest: string & import("effect/Brand").Brand<"@domainkit/Digest">;
+    } | {
+        readonly _tag: "Expired";
+        readonly entity: "approval" | "continuation" | "credential" | "plan";
+        readonly id: string;
+    } | {
+        readonly _tag: "Busy";
+        readonly key: string;
+    } | {
+        readonly _tag: "ProviderRejected";
+        readonly provider: string;
+        readonly code?: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "ProviderUnavailable";
+        readonly provider: string;
+        readonly retryAfterMs?: number;
+        readonly message: string;
+    } | {
+        readonly _tag: "ProviderConflict";
+        readonly provider: string;
+        readonly code?: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "Unsupported";
+        readonly provider: string;
+        readonly operation: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "Reconnect";
+        readonly provider: string;
+        readonly connectionId: string;
+    } | {
+        readonly _tag: "StorageFailed";
+        readonly operation: string;
+        readonly message: string;
+    } | {
+        readonly _tag: "CryptoFailed";
+        readonly operation: "digest" | "open" | "seal";
+    } | {
+        readonly _tag: "ResolverFailed";
+        readonly resolver: string;
+        readonly message: string;
+    };
+}>, Schema.TaggedStruct<"DomainKitError", {
+    readonly reason: Schema.suspend<Schema.Union<readonly [typeof Reason.InvalidInput, typeof Reason.Unauthenticated, typeof Reason.Forbidden, typeof Reason.NotFound, typeof Reason.Conflict, typeof Reason.Stale, typeof Reason.Expired, typeof Reason.Busy, typeof Reason.ProviderRejected, typeof Reason.ProviderUnavailable, typeof Reason.ProviderConflict, typeof Reason.Unsupported, typeof Reason.Reconnect, typeof Reason.StorageFailed, typeof Reason.CryptoFailed, typeof Reason.ResolverFailed]>>;
 }>, never, never>>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"receipt", "GET", "/receipts/:receiptId", Schema.toCodecStringTree<Schema.Struct<{
     receiptId: Schema.brand<Schema.String, "@domainkit/ReceiptId">;
 }>>, never, never, never, Schema.toCodecJson<typeof Receipt.Model>, Schema.toCodecJson<Schema.decodeTo<Schema.declareConstructor<Errors.DomainKitError, {

package/dist/types/Storage.d.ts

@@ -80,6 +80,18 @@ declare const Continuation_base: Schema.Class<Continuation, Schema.Struct<{
 /** Interactive-flow state between `Connect.start` and `Connect.complete`. */
 export declare class Continuation extends Continuation_base {
 }
+declare const ContinuationHeader_base: Schema.Class<ContinuationHeader, Schema.Struct<{
+    readonly ownerId: Schema.String;
+    readonly actorId: Schema.String;
+    readonly provider: Schema.String;
+    readonly expiresAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/**
+ * Who a continuation belongs to, without the continuation itself. `payload` has no place here: it
+ * carries the PKCE `codeVerifier`, which only the owner-scoped read may reach.
+ */
+export declare class ContinuationHeader extends ContinuationHeader_base {
+}
 export declare const AttemptStatus: Schema.Literals<readonly ["planned", "approved", "applying", "complete", "partial", "failed", "expired", "rejected"]>;
 export type AttemptStatus = typeof AttemptStatus.Type;
 /** Who declined the plan, why, and when. Terminal: the domain needs a new plan. */
@@ -192,6 +204,16 @@ export interface Interface {
         readonly put: (continuation: Continuation) => Fx<void>;
         /** Read without spending; a late read fails `Expired`. */
         readonly get: (id: string) => Fx<Continuation>;
+        /**
+         * The flow's owner, actor, provider, and expiry, without a principal and without spending the
+         * row. The one read in this interface that is not tenant-scoped, because `domainkit/server`
+         * has to learn whose flow a provider callback finishes before it can resolve the principal to
+         * scope by; the callback carries a continuation id and a session cookie and nothing else.
+         *
+         * A missing row fails `NotFound` and a stale one fails `Expired`, exactly as `get` does, so an
+         * expired id never reaches a host. `payload` is out of reach here by construction.
+         */
+        readonly header: (id: string) => Effect.Effect<ContinuationHeader, Errors.DomainKitError>;
         /** Exactly-once: the second consume of the same id fails `NotFound`; a late one fails `Expired`. */
         readonly consume: (id: string) => Fx<Continuation>;
     };
@@ -287,6 +309,8 @@ export interface AsyncInterface {
     readonly continuations: {
         readonly put: (principal: Principal.Interface, continuation: Continuation) => Promise<void>;
         readonly get: (principal: Principal.Interface, id: string) => Promise<Continuation>;
+        /** Takes no principal: see `Interface.continuations.header`. Never returns `payload`. */
+        readonly header: (id: string) => Promise<ContinuationHeader>;
         readonly consume: (principal: Principal.Interface, id: string) => Promise<Continuation>;
     };
     readonly attempts: {

package/dist/types/Transport.d.ts

@@ -95,6 +95,8 @@ export interface VerificationGroup {
     readonly observe: (domain: string, options?: {
         readonly requirements?: ReadonlyArray<DnsRecord.Model>;
     }) => Fx<Readiness>;
+    /** The stored readiness, without observing. `null` until the domain has been observed once. */
+    readonly latest: (domain: string) => Fx<Readiness | null>;
 }
 export interface CleanupGroup {
     readonly plan: (receiptId: Receipt.ReceiptId) => Fx<Plan.Model>;

package/dist/types/Verify.d.ts

@@ -42,6 +42,8 @@ export declare class HostEvidence extends HostEvidence_base {
 export declare const Evidence: Schema.Union<readonly [typeof ProviderEvidence, typeof PublicDnsEvidence, typeof HostEvidence]>;
 export type Evidence = typeof Evidence.Type;
 export interface Requirement {
+    /** `requirementKey(record)`: what a host pairs its own row against, by content. */
+    readonly key: string;
     readonly operationId: Plan.OperationId | null;
     readonly record: DnsRecord.Model;
     readonly status: Storage.RequirementStatus;
@@ -81,6 +83,32 @@ export interface Interface {
 declare const Service_base: Context.ServiceClass<Service, "@domainkit/Verify", Interface>;
 export declare class Service extends Service_base {
 }
+/**
+ * A requirement's identity: the record's type, name, and data, and nothing else. It is what a host
+ * pairs its own rows against readiness by, instead of trusting the order of the array.
+ * `@domainkit/react`'s `Records.identity` is this function.
+ */
+export declare const requirementKey: (record: DnsRecord.Model) => string;
+/** Counts across a readiness's requirements. `observed` is false when there is no readiness yet. */
+export interface Summary {
+    readonly observed: boolean;
+    readonly total: number;
+    readonly satisfied: number;
+    readonly missing: number;
+    readonly mismatch: number;
+    readonly unknown: number;
+}
+/** The least a value has to carry to be summarised: core `Readiness` and the wire shape both do. */
+export interface Summarisable {
+    readonly requirements: ReadonlyArray<{
+        readonly status: Storage.RequirementStatus;
+    }>;
+}
+/**
+ * How a readiness stands, as counts. Pure and total: a host renders "3 of 4 found" from the stored
+ * fact without deciding what an absent readiness means, because `observed` says so.
+ */
+export declare const summary: (readiness: Summarisable | null) => Summary;
 export interface PolicyShape {
     /** Delay before the next check, given time since the first pending observation. Default ladder: 15s, 1m, 5m, 30m. */
     readonly backoff: (pendingForMs: number) => number;
@@ -93,6 +121,40 @@ export declare const defaults: PolicyShape;
 declare const Policy_base: Context.Reference<PolicyShape>;
 export declare class Policy extends Policy_base {
 }
+/** Why readiness was written: a DNS observation, or host evidence merged into the stored row. */
+export type Cause = "observe" | "evidence";
+export interface ReadinessChanged {
+    readonly domain: string;
+    readonly readiness: Readiness;
+    readonly cause: Cause;
+}
+export interface ObserverShape {
+    /**
+     * Called once per stored readiness, after the write. A host that projects readiness onto its own
+     * rows, wakes a durable job at `nextCheckAt`, or notifies a customer hangs it here instead of
+     * mirroring the fact at every call site.
+     *
+     * Events for one domain are not ordered against each other: two observations that overlap both
+     * store, last write wins in `Storage`, and their callbacks can finish in either order. A
+     * projection compares `readiness.checkedAt`, which is the moment the row was written, and keeps
+     * the later one; `latest` remains the authority.
+     */
+    readonly readinessChanged: (event: ReadinessChanged) => Effect.Effect<void, unknown>;
+}
+declare const Observer_base: Context.Reference<ObserverShape>;
+/**
+ * The host seam for "DomainKit wrote readiness". The default does nothing; provide one with
+ * `Effect.provideService(Verify.Observer, ...)` or `Layer.succeed(Verify.Observer, ...)` over
+ * `DomainKit.layer`, the same way `Policy` is overridden.
+ *
+ * It runs after `storage.readiness.put` returns, outside any transaction, because `Storage`
+ * exposes none. A failure or defect in the observer is logged and swallowed: the observation is
+ * already durable, and losing it because a projection failed would make the stored fact depend on
+ * the host's side effects. A host that needs the projection to be reliable enqueues durable work
+ * here rather than doing the work inline.
+ */
+export declare class Observer extends Observer_base {
+}
 /** A requirement is satisfied by an exact match; an exclusive one is contradicted by any same-set record. */
 export declare const statusAgainst: (record: DnsRecord.Model, observed: ReadonlyArray<DnsRecord.Observed>) => Storage.RequirementStatus;
 export declare const make: Effect.Effect<Interface, never, Storage.Service | Connect.Service | Resolver.Service>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domainkit",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Build reviewable DNS plans for custom domains in TypeScript",
   "keywords": [
     "custom-domains",