domainkit 0.8.0 → 0.9.0

package/dist/types/Storage.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Everything DomainKit persists, behind one service the host installs once. Every method requires
+ * `Principal` and is scoped by it. `@domainkit/capsuledb` ships the Postgres implementation;
+ * `domainkit/testing` ships the memory one; both pass `Testing.conformance.storage`.
+ *
+ * Storage never sees plaintext credentials: `Connect` seals secrets through `Custody` before
+ * writing a `Credential` row and opens them after reading one.
+ *
+ * Grouped by noun so the 25-odd methods stay navigable. Implementations must satisfy the
+ * invariants documented per group; the conformance suite checks them.
+ */
+import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
+import * as Approval from "./Approval.ts";
+import * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+import { makeMemory } from "./internal/storage-memory.ts";
+import * as Plan from "./Plan.ts";
+import * as Principal from "./Principal.ts";
+import * as Receipt from "./Receipt.ts";
+export type Fx<A> = Effect.Effect<A, Errors.DomainKitError, Principal.Service>;
+export declare const Capability: Schema.Literals<readonly ["dns:read", "dns:write"]>;
+export type Capability = typeof Capability.Type;
+export declare const AuthMethod: Schema.Literals<readonly ["token", "oauth", "integration"]>;
+export type AuthMethod = typeof AuthMethod.Type;
+declare const Credential_base: Schema.Class<Credential, Schema.Struct<{
+    readonly ciphertext: Schema.String;
+    readonly expiresAt: Schema.NullOr<Schema.DateTimeUtcFromString>;
+    readonly rotatedAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** Sealed provider credential plus the metadata needed without unsealing it. */
+export declare class Credential extends Credential_base {
+}
+declare const Authorization_base: Schema.Class<Authorization, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly provider: Schema.String;
+    readonly method: Schema.Literals<readonly ["token", "oauth", "integration"]>;
+    readonly capabilities: Schema.$Array<Schema.Literals<readonly ["dns:read", "dns:write"]>>;
+    /** Provider-specific account context (account id, team id, ...) decoded by the provider's `context` schema. */
+    readonly context: Schema.Unknown;
+    readonly revocation: Schema.Literals<readonly ["active", "pending", "revoked"]>;
+    readonly createdBy: Schema.String;
+    readonly createdAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** One provider authorization (an OAuth grant or a token) owned by a principal. */
+export declare class Authorization extends Authorization_base {
+}
+declare const Connection_base: Schema.Class<Connection, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly authorizationId: Schema.String;
+    readonly createdAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** A connection is the principal-facing handle over an authorization; one authorization, many domains. */
+export declare class Connection extends Connection_base {
+}
+declare const Attachment_base: Schema.Class<Attachment, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly connectionId: Schema.String;
+    readonly domain: Schema.String;
+    readonly zone: Schema.String;
+    /** Provider zone identity (zone id, account id) decoded by the provider's `context` schema. */
+    readonly target: Schema.Unknown;
+    readonly createdAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+export declare class Attachment extends Attachment_base {
+}
+declare const Continuation_base: Schema.Class<Continuation, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly actorId: Schema.String;
+    readonly provider: Schema.String;
+    readonly payload: Schema.Unknown;
+    readonly returnTo: Schema.NullOr<Schema.String>;
+    readonly expiresAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** Interactive-flow state between `Connect.start` and `Connect.complete`. */
+export declare class Continuation extends Continuation_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. */
+export declare const Rejection: Schema.Struct<{
+    readonly actorId: Schema.String;
+    readonly reason: Schema.NullOr<Schema.String>;
+    readonly at: Schema.DateTimeUtcFromString;
+}>;
+export type Rejection = typeof Rejection.Type;
+declare const Attempt_base: Schema.Class<Attempt, Schema.Struct<{
+    readonly id: Schema.brand<Schema.String, "@domainkit/PlanId">;
+    readonly ownerId: Schema.String;
+    readonly attachmentId: Schema.String;
+    readonly kind: Schema.Literals<readonly ["provisioning", "cleanup"]>;
+    readonly status: Schema.Literals<readonly ["planned", "approved", "applying", "complete", "partial", "failed", "expired", "rejected"]>;
+    readonly plan: typeof Plan.Model;
+    readonly approval: Schema.NullOr<typeof Approval.Model>;
+    readonly receipt: Schema.NullOr<typeof Receipt.Model>;
+    readonly rejection: Schema.NullOr<Schema.Struct<{
+        readonly actorId: Schema.String;
+        readonly reason: Schema.NullOr<Schema.String>;
+        readonly at: Schema.DateTimeUtcFromString;
+    }>>;
+    /** Cleanup attempts point at the provisioning receipt they undo. */
+    readonly sourceReceiptId: Schema.NullOr<Schema.brand<Schema.String, "@domainkit/ReceiptId">>;
+    readonly leaseExpiresAt: Schema.NullOr<Schema.DateTimeUtcFromString>;
+    /** Why the last apply stopped before any write; cleared on the next claim. */
+    readonly failure: Schema.NullOr<Schema.String>;
+    readonly updatedAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** One durable plan -> approval -> receipt lifecycle. */
+export declare class Attempt extends Attempt_base {
+}
+export declare const RequirementStatus: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
+export type RequirementStatus = typeof RequirementStatus.Type;
+export declare const Overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
+export type Overall = typeof Overall.Type;
+declare const Readiness_base: Schema.Class<Readiness, Schema.Struct<{
+    readonly domain: Schema.String;
+    readonly attachmentId: Schema.NullOr<Schema.String>;
+    readonly ownerId: Schema.String;
+    readonly overall: Schema.Literals<readonly ["ready", "pending", "failed"]>;
+    readonly requirements: Schema.$Array<Schema.Struct<{
+        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"]>;
+        /** Encoded `Verify.Evidence` values. */
+        readonly evidence: Schema.$Array<Schema.Unknown>;
+    }>>;
+    /** Encoded `Verify.HostEvidence` values, keyed by `source` on merge. */
+    readonly host: Schema.$Array<Schema.Unknown>;
+    /** When the current pending streak began; drives the backoff ladder. */
+    readonly pendingSince: Schema.NullOr<Schema.DateTimeUtcFromString>;
+    readonly checkedAt: Schema.DateTimeUtcFromString;
+    readonly nextCheckAt: Schema.NullOr<Schema.DateTimeUtcFromString>;
+}>, {}>;
+/**
+ * Latest observed readiness for one domain, written by `Verify.observe`. Keyed by domain so
+ * observe-only hosts (no attachment, public DNS alone) get the same row; `attachmentId` links the
+ * attachment when one exists.
+ */
+export declare class Readiness extends Readiness_base {
+}
+export interface Interface {
+    readonly authorizations: {
+        /**
+         * Insert, or CAS-replace when `expectedId` is set: the row must exist under this owner with an
+         * active revocation state, else `NotFound` / `Busy`.
+         */
+        readonly upsert: (input: {
+            readonly authorization: Authorization;
+            readonly credential: Credential;
+            readonly expectedId?: string;
+        }) => Fx<Authorization>;
+        readonly get: (id: string) => Fx<Authorization>;
+        readonly credential: (id: string) => Fx<Credential>;
+        readonly rotate: (id: string, credential: Credential) => Fx<void>;
+        readonly promoteCapabilities: (id: string, capabilities: ReadonlyArray<Capability>) => Fx<void>;
+        /**
+         * Two-phase: mark `pending`, run `revoke` outside any transaction, then delete. A failed
+         * `revoke` leaves the row pending; `recoverRevocations` finishes it later.
+         */
+        readonly revoke: <E, R>(id: string, revoke: Effect.Effect<void, E, R>) => Effect.Effect<void, Errors.DomainKitError | E, Principal.Service | R>;
+        readonly recoverRevocations: <E, R>(revoke: (authorization: Authorization) => Effect.Effect<void, E, R>) => Effect.Effect<number, Errors.DomainKitError | E, Principal.Service | R>;
+    };
+    readonly connections: {
+        readonly create: (authorizationId: string) => Fx<Connection>;
+        readonly get: (id: string) => Fx<Connection>;
+        readonly list: (filter?: {
+            readonly provider?: string;
+        }) => Fx<ReadonlyArray<Connection>>;
+        /** Fails `InvalidInput` while attachments still reference the connection. */
+        readonly remove: (id: string) => Fx<void>;
+    };
+    readonly attachments: {
+        /** One attachment per (owner, domain); a duplicate fails `InvalidInput`. */
+        readonly create: (input: {
+            readonly connectionId: string;
+            readonly domain: string;
+            readonly zone: string;
+            readonly target: unknown;
+        }) => Fx<Attachment>;
+        readonly get: (id: string) => Fx<Attachment>;
+        readonly byDomain: (domain: string) => Fx<Option.Option<Attachment>>;
+        readonly list: (connectionId: string) => Fx<ReadonlyArray<Attachment>>;
+        readonly remove: (id: string) => Fx<void>;
+    };
+    readonly continuations: {
+        readonly put: (continuation: Continuation) => Fx<void>;
+        /** Read without spending; a late read fails `Expired`. */
+        readonly get: (id: string) => Fx<Continuation>;
+        /** Exactly-once: the second consume of the same id fails `NotFound`; a late one fails `Expired`. */
+        readonly consume: (id: string) => Fx<Continuation>;
+    };
+    readonly attempts: {
+        readonly create: (attempt: Attempt) => Fx<Attempt>;
+        readonly get: (id: Plan.PlanId) => Fx<Attempt>;
+        readonly byApproval: (id: Approval.ApprovalId) => Fx<Attempt>;
+        readonly byReceipt: (id: Receipt.ReceiptId) => Fx<Attempt>;
+        readonly latest: (attachmentId: string, kind: Plan.Kind) => Fx<Option.Option<Attempt>>;
+        /** `planned` -> `approved`; approving again with the same approval id is a no-op, anything else fails `Stale`. */
+        readonly approve: (id: Plan.PlanId, approval: Approval.Model) => Fx<Attempt>;
+        /**
+         * `planned` -> `rejected` (terminal). Rejecting again returns the row unchanged; any other
+         * status fails `Stale`, `expired` fails `Expired`, and a digest mismatch fails `Stale`.
+         */
+        readonly reject: (id: Plan.PlanId, input: {
+            readonly digest: Plan.Digest;
+            readonly actorId: string;
+            readonly reason: string | null;
+        }) => Fx<Attempt>;
+        /**
+         * Atomic transition to `applying` with a lease from `approved`, `failed`, or an expired
+         * `applying`; fails `Busy` while a lease is live and `Stale` from any other status.
+         */
+        readonly claim: (id: Plan.PlanId, lease: DateTime.Utc) => Fx<Attempt>;
+        readonly complete: (id: Plan.PlanId, receipt: Receipt.Model) => Fx<Attempt>;
+        readonly fail: (id: Plan.PlanId, message: string) => Fx<Attempt>;
+    };
+    readonly readiness: {
+        /** One row per (owner, domain); `attachmentId`, when set, must exist for the owner. */
+        readonly put: (readiness: Readiness) => Fx<void>;
+        readonly get: (domain: string) => Fx<Option.Option<Readiness>>;
+    };
+    /** Single-flight guard keyed by string (credential refresh, apply). Fails `Busy` rather than waiting. */
+    readonly withLock: <A, E, R>(key: string, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | Errors.DomainKitError, R | Principal.Service>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Storage", Interface>;
+export declare class Service extends Service_base {
+}
+export interface MemoryOptions {
+    /** Fault injection: runs before every mutation commits; failing here leaves state untouched. */
+    readonly beforeCommit?: (operation: string) => Effect.Effect<void, Errors.DomainKitError>;
+}
+/** In-memory implementation for tests and local development. Not for production. */
+export declare const layerMemory: Layer.Layer<Service>;
+/** `layerMemory` with fault injection for storage-failure tests. */
+export declare const layerMemoryWith: (options: MemoryOptions) => Layer.Layer<Service>;
+export { makeMemory };
+/**
+ * A Promise-shaped implementation for hosts that persist without Effect. Every method takes the
+ * principal explicitly. Rejections become `StorageFailed`; reject with a `DomainKit.Error` to keep
+ * a typed reason. Two-phase revocation and locking are split into plain steps so no callback has
+ * to run an Effect.
+ */
+export interface AsyncInterface {
+    readonly authorizations: {
+        readonly upsert: (principal: Principal.Interface, input: {
+            readonly authorization: Authorization;
+            readonly credential: Credential;
+            readonly expectedId?: string;
+        }) => Promise<Authorization>;
+        readonly get: (principal: Principal.Interface, id: string) => Promise<Authorization>;
+        readonly credential: (principal: Principal.Interface, id: string) => Promise<Credential>;
+        readonly rotate: (principal: Principal.Interface, id: string, credential: Credential) => Promise<void>;
+        readonly promoteCapabilities: (principal: Principal.Interface, id: string, capabilities: ReadonlyArray<Capability>) => Promise<void>;
+        /** Mark `pending` durably; must be idempotent. */
+        readonly prepareRevocation: (principal: Principal.Interface, id: string) => Promise<Authorization>;
+        /** Delete the authorization after the provider confirmed revocation. */
+        readonly completeRevocation: (principal: Principal.Interface, id: string) => Promise<void>;
+        readonly pendingRevocations: (principal: Principal.Interface) => Promise<ReadonlyArray<Authorization>>;
+    };
+    readonly connections: {
+        readonly create: (principal: Principal.Interface, authorizationId: string) => Promise<Connection>;
+        readonly get: (principal: Principal.Interface, id: string) => Promise<Connection>;
+        readonly list: (principal: Principal.Interface, filter?: {
+            readonly provider?: string;
+        }) => Promise<ReadonlyArray<Connection>>;
+        readonly remove: (principal: Principal.Interface, id: string) => Promise<void>;
+    };
+    readonly attachments: {
+        readonly create: (principal: Principal.Interface, input: {
+            readonly connectionId: string;
+            readonly domain: string;
+            readonly zone: string;
+            readonly target: unknown;
+        }) => Promise<Attachment>;
+        readonly get: (principal: Principal.Interface, id: string) => Promise<Attachment>;
+        readonly byDomain: (principal: Principal.Interface, domain: string) => Promise<Attachment | null>;
+        readonly list: (principal: Principal.Interface, connectionId: string) => Promise<ReadonlyArray<Attachment>>;
+        readonly remove: (principal: Principal.Interface, id: string) => Promise<void>;
+    };
+    readonly continuations: {
+        readonly put: (principal: Principal.Interface, continuation: Continuation) => Promise<void>;
+        readonly get: (principal: Principal.Interface, id: string) => Promise<Continuation>;
+        readonly consume: (principal: Principal.Interface, id: string) => Promise<Continuation>;
+    };
+    readonly attempts: {
+        readonly create: (principal: Principal.Interface, attempt: Attempt) => Promise<Attempt>;
+        readonly get: (principal: Principal.Interface, id: Plan.PlanId) => Promise<Attempt>;
+        readonly byApproval: (principal: Principal.Interface, id: Approval.ApprovalId) => Promise<Attempt>;
+        readonly byReceipt: (principal: Principal.Interface, id: Receipt.ReceiptId) => Promise<Attempt>;
+        readonly latest: (principal: Principal.Interface, attachmentId: string, kind: Plan.Kind) => Promise<Attempt | null>;
+        readonly approve: (principal: Principal.Interface, id: Plan.PlanId, approval: Approval.Model) => Promise<Attempt>;
+        readonly reject: (principal: Principal.Interface, id: Plan.PlanId, input: {
+            readonly digest: Plan.Digest;
+            readonly actorId: string;
+            readonly reason: string | null;
+        }) => Promise<Attempt>;
+        readonly claim: (principal: Principal.Interface, id: Plan.PlanId, lease: DateTime.Utc) => Promise<Attempt>;
+        readonly complete: (principal: Principal.Interface, id: Plan.PlanId, receipt: Receipt.Model) => Promise<Attempt>;
+        readonly fail: (principal: Principal.Interface, id: Plan.PlanId, message: string) => Promise<Attempt>;
+    };
+    readonly readiness: {
+        readonly put: (principal: Principal.Interface, readiness: Readiness) => Promise<void>;
+        readonly get: (principal: Principal.Interface, domain: string) => Promise<Readiness | null>;
+    };
+    /** Return `false` when another holder has the key. */
+    readonly acquireLock: (principal: Principal.Interface, key: string) => Promise<boolean>;
+    readonly releaseLock: (principal: Principal.Interface, key: string) => Promise<void>;
+}
+/** Wraps a Promise-shaped implementation. Rejections become `StorageFailed`. */
+export declare const fromAsync: (service: AsyncInterface) => Interface;
+export declare const layerFromAsync: (service: AsyncInterface) => Layer.Layer<Service>;

package/dist/types/Testing.d.ts

@@ -0,0 +1,84 @@
+/**
+ * domainkit/testing — fakes and conformance runners so hosts test against the seam instead of
+ * stubbing global fetch.
+ */
+import { Layer, Schema } from "effect";
+import * as DnsRecord from "./DnsRecord.ts";
+import { provider as providerCases } from "./internal/conformance/provider.ts";
+import { storage as storageCases } from "./internal/conformance/storage.ts";
+import * as Principal from "./Principal.ts";
+import * as Provider from "./Provider.ts";
+import * as Resolver from "./Resolver.ts";
+import * as Storage from "./Storage.ts";
+import * as Transport from "./Transport.ts";
+/** In-memory Storage. Same as `Storage.layerMemory`; re-exported for discoverability. */
+export declare const storage: Layer.Layer<Storage.Service>;
+export declare const principal: Principal.Interface;
+export interface FakeProviderOptions {
+    readonly id?: string;
+    /** Zones the fake credential can reach. Default: `example.com`. */
+    readonly zones?: ReadonlyArray<string>;
+    /** Pre-existing records, to produce `Noop` and `Conflict` operations. */
+    readonly records?: ReadonlyArray<{
+        readonly zone: string;
+        readonly record: DnsRecord.Observed;
+    }>;
+    /** Offer OAuth in addition to tokens; the fake redirects to `callbackUrl` immediately. */
+    readonly oauth?: boolean;
+    /** Fail the write at this zero-based index, to exercise partial receipts. */
+    readonly failWrite?: (index: number) => boolean;
+    /** Nameservers per zone; default `ns1.<zone>`, `ns2.<zone>`. `resolver()` answers NS queries from them. */
+    readonly nameservers?: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+export interface FakeProvider extends Provider.Definition<FakeContext> {
+    readonly records: (zone: string) => ReadonlyArray<DnsRecord.Observed>;
+    /** Every credential the fake issued, oldest first. */
+    readonly issued: () => ReadonlyArray<string>;
+    /** How many credentials were revoked at the fake. */
+    readonly revoked: () => number;
+}
+/** Account context carries `account`; target context carries `zone`. One schema covers both. */
+declare const Context: Schema.Struct<{
+    readonly account: Schema.optionalKey<Schema.String>;
+    readonly zone: Schema.optionalKey<Schema.String>;
+}>;
+type FakeContext = typeof Context.Type;
+/** A provider definition with a token method (and optional OAuth) over in-memory zones. */
+export declare const provider: (options?: FakeProviderOptions) => FakeProvider;
+/** Records every fake provider currently holds for `name`, across all fake zones. */
+export declare const fakeRecords: (name: string) => ReadonlyArray<DnsRecord.Observed>;
+/**
+ * A resolver answering from the fake providers' zones, or from an explicit table. Every answer
+ * is attributed to the resolver named `fake`.
+ */
+export declare const resolver: (answers?: ReadonlyArray<{
+    readonly name: string;
+    readonly records: ReadonlyArray<DnsRecord.Observed>;
+}>) => Layer.Layer<Resolver.Service>;
+export interface TransportOptions {
+    /** Which groups the fake server exposes, so a UI can be tested against a partial host. */
+    readonly capabilities?: ReadonlyArray<Transport.Capability>;
+    readonly provider?: FakeProviderOptions;
+}
+export interface RecordedCall {
+    /** `connection.inspect`, `provisioning.approve`, ... */
+    readonly method: string;
+    /** The call's only argument, or the argument list when the method takes more than one. */
+    readonly input: unknown;
+}
+export interface RecordingTransport extends Transport.Interface {
+    readonly calls: ReadonlyArray<RecordedCall>;
+}
+/**
+ * A transport over an in-memory `domainkit/server` and memory Storage, recording every call. What
+ * `@domainkit/react` tests render against, instead of stubbing global `fetch`.
+ */
+export declare const transport: (options?: TransportOptions) => RecordingTransport;
+export type { Case as ProviderCase } from "./internal/conformance/provider.ts";
+export type { Case as StorageCase } from "./internal/conformance/storage.ts";
+export declare const conformance: {
+    /** Runs every Storage invariant (tenant isolation, leases, exactly-once continuations, revocation recovery). */
+    storage: typeof storageCases;
+    /** Runs create/readback/cleanup, exact-noop, conflict, stale-plan, partial-apply against a real provider definition. */
+    provider: typeof providerCases;
+};

package/dist/types/Transport.d.ts

@@ -0,0 +1,124 @@
+/**
+ * domainkit/client — the browser-side transport `@domainkit/react` consumes. Capability groups are
+ * optional: a host that only exposes connection routes declares just `connection`, and the parts
+ * of the UI that plan or clean up do not render.
+ *
+ *   const transport = Transport.fromFetch("/api/domainkit")
+ *
+ * Every method decodes the same wire schemas `domainkit/server` encodes, so a failure arrives as
+ * the `DomainKit.Error` the lifecycle raised, reason intact.
+ */
+import { Effect } from "effect";
+import * as Approval from "./Approval.ts";
+import type * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+import * as Http from "./internal/http.ts";
+import * as Plan from "./Plan.ts";
+import * as Receipt from "./Receipt.ts";
+import * as Server from "./Server.ts";
+type Fx<A> = Effect.Effect<A, Errors.DomainKitError>;
+export type Snapshot = Server.Snapshot;
+export type Started = Server.Started;
+export type Readiness = Server.Readiness;
+export type Attempt = Server.Attempt;
+export type Candidate = Server.Candidate;
+export type Discovery = Server.Discovery;
+export type Field = Server.Field;
+export type MethodDescriptor = Server.MethodDescriptor;
+export type Method = Server.Method;
+/** How a client asks to connect. Mirrors `Connect.Method`, over the wire. */
+export declare const Method: {
+    /** A lone string for the common one-field provider, or the values its descriptor names. */
+    readonly token: (values: string | Readonly<Record<string, string>>) => Method;
+    readonly oauth: (options?: {
+        readonly returnTo?: string;
+    }) => Method;
+    readonly integration: (options?: {
+        readonly returnTo?: string;
+    }) => Method;
+};
+export interface ConnectionGroup {
+    readonly inspect: (domain: string) => Fx<Snapshot>;
+    /** Which of this owner's existing connections already reaches the domain. */
+    readonly discover: (domain: string) => Fx<Discovery>;
+    readonly start: (input: {
+        readonly domain: string;
+        readonly provider: string;
+        readonly method: Method;
+    }) => Fx<Started>;
+    readonly attach: (input: {
+        readonly connectionId: string;
+        readonly domain: string;
+        readonly zone?: string;
+    }) => Fx<Started>;
+    readonly detach: (attachmentId: string) => Fx<void>;
+    readonly disconnect: (connectionId: string) => Fx<void>;
+}
+export interface ProvisioningGroup {
+    readonly plan: (input: {
+        readonly domain: string;
+        readonly requirements: ReadonlyArray<DnsRecord.Model>;
+    }) => Fx<Plan.Model>;
+    readonly approve: (input: {
+        readonly planId: Plan.PlanId;
+        readonly operationIds?: ReadonlyArray<Plan.OperationId>;
+    }) => Fx<Approval.Model>;
+    /** Decline the plan; terminal, and approving it afterwards fails `Stale`. */
+    readonly reject: (input: {
+        readonly planId: Plan.PlanId;
+        readonly reason?: string;
+    }) => Fx<Attempt>;
+    readonly apply: (approvalId: Approval.ApprovalId) => Fx<Receipt.Model>;
+    /** The stored plan with its status, approval, receipt, and rejection. */
+    readonly attempt: (planId: Plan.PlanId) => Fx<Attempt>;
+}
+export interface VerificationGroup {
+    /**
+     * Observe the domain's provisioning receipt, or `options.requirements` when supplied (required
+     * for a domain with no attachment).
+     */
+    readonly observe: (domain: string, options?: {
+        readonly requirements?: ReadonlyArray<DnsRecord.Model>;
+    }) => Fx<Readiness>;
+}
+export interface CleanupGroup {
+    readonly plan: (receiptId: Receipt.ReceiptId) => Fx<Plan.Model>;
+    readonly approve: (input: {
+        readonly planId: Plan.PlanId;
+        readonly operationIds?: ReadonlyArray<Plan.OperationId>;
+    }) => Fx<Approval.Model>;
+    readonly reject: (input: {
+        readonly planId: Plan.PlanId;
+        readonly reason?: string;
+    }) => Fx<Attempt>;
+    readonly apply: (approvalId: Approval.ApprovalId) => Fx<Receipt.Model>;
+}
+export interface Interface {
+    readonly connection?: ConnectionGroup;
+    readonly provisioning?: ProvisioningGroup;
+    readonly verification?: VerificationGroup;
+    readonly cleanup?: CleanupGroup;
+}
+export type Capability = keyof Interface;
+export declare const allCapabilities: ReadonlyArray<Capability>;
+/** Which groups this transport actually carries, in declaration order. */
+export declare const capabilities: (transport: Interface) => ReadonlyArray<Capability>;
+export interface FetchOptions {
+    readonly fetch?: Http.Fetch;
+    readonly headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** Which groups the server exposes. Default: all. */
+    readonly capabilities?: ReadonlyArray<Capability>;
+}
+/** A transport over `domainkit/server` routes mounted at `baseUrl`. */
+export declare const fromFetch: (baseUrl: string, options?: FetchOptions) => Interface;
+/** The same transport in Promises, for hosts and tests that do not run Effect. */
+export type AsyncTransport = {
+    readonly [K in keyof Interface]?: {
+        readonly [M in keyof NonNullable<Interface[K]>]: NonNullable<Interface[K]>[M] extends (...args: infer A) => Effect.Effect<infer R, Errors.DomainKitError> ? (...args: A) => Promise<R> : never;
+    };
+};
+/** Adapt a Promise-shaped transport; a rejection that is not a `DomainKit.Error` becomes one. */
+export declare const fromAsync: (transport: AsyncTransport) => Interface;
+/** Adapt to Promises; every rejection is the `DomainKit.Error` the lifecycle raised. */
+export declare const toAsync: (transport: Interface) => AsyncTransport;
+export {};

package/dist/types/Vercel.d.ts

@@ -0,0 +1,25 @@
+/** Vercel: personal tokens and marketplace integrations. */
+import { type Config, Redacted, Schema } from "effect";
+import type { Fetch } from "./internal/http.ts";
+import * as Provider from "./Provider.ts";
+/** `teamId` is `null` for a personal account; targets carry the team that owns the zone. */
+export declare const TeamContext: Schema.Struct<{
+    readonly teamId: Schema.NullOr<Schema.String>;
+}>;
+export type TeamContext = typeof TeamContext.Type;
+/** Token-method input: the access token, and a team id to scope the connection to one team. */
+export declare const TokenFields: Schema.Struct<{
+    readonly token: Schema.RedactedFromValue<Schema.String>;
+    readonly teamId: Schema.optionalKey<Schema.String>;
+}>;
+export interface Options {
+    /** Omit to offer tokens only. */
+    readonly integration?: {
+        readonly clientId: string | Config.Config<string>;
+        readonly clientSecret: Redacted.Redacted<string> | Config.Config<Redacted.Redacted<string>>;
+        readonly slug: string;
+    };
+    readonly fetch?: Fetch;
+    readonly baseUrl?: string;
+}
+export declare const provider: (options?: Options) => Provider.Definition<TeamContext>;

package/dist/types/Verify.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Observe provider and public DNS for an attachment, persist per-requirement readiness, and say
+ * when to look again. The host keeps its own state machine (and any provider-side verification
+ * such as SES) and feeds that in as `HostEvidence`.
+ */
+import { Context, DateTime, Effect, Layer, Schema } from "effect";
+import * as Connect from "./Connect.ts";
+import * as DnsRecord from "./DnsRecord.ts";
+import * as Errors from "./internal/error.ts";
+import type * as Plan from "./Plan.ts";
+import * as Principal from "./Principal.ts";
+import * as Resolver from "./Resolver.ts";
+import * as Storage from "./Storage.ts";
+declare const ProviderEvidence_base: Schema.Class<ProviderEvidence, Schema.TaggedStruct<"Provider", {
+    readonly provider: Schema.String;
+    readonly status: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
+    readonly values: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
+    readonly detail: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+    readonly observedAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+export declare class ProviderEvidence extends ProviderEvidence_base {
+}
+declare const PublicDnsEvidence_base: Schema.Class<PublicDnsEvidence, Schema.TaggedStruct<"PublicDns", {
+    readonly resolver: Schema.String;
+    readonly status: Schema.Literals<readonly ["satisfied", "missing", "mismatch", "unknown"]>;
+    readonly values: Schema.withDecodingDefaultKey<Schema.$Array<Schema.String>, never>;
+    readonly detail: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+    readonly observedAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+export declare class PublicDnsEvidence extends PublicDnsEvidence_base {
+}
+declare const HostEvidence_base: Schema.Class<HostEvidence, Schema.TaggedStruct<"Host", {
+    readonly source: Schema.String;
+    readonly status: Schema.Literals<readonly ["ok", "pending", "failed"]>;
+    readonly label: Schema.String;
+    readonly detail: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+    readonly observedAt: Schema.DateTimeUtcFromString;
+}>, {}>;
+/** Anything the host knows that DomainKit cannot observe: SES identity status, a CDN cert, ... */
+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 {
+    readonly operationId: Plan.OperationId | null;
+    readonly record: DnsRecord.Model;
+    readonly status: Storage.RequirementStatus;
+    readonly evidence: ReadonlyArray<Evidence>;
+}
+export interface Readiness {
+    readonly domain: string;
+    /** `null` for observe-only domains that have no attachment. */
+    readonly attachmentId: string | null;
+    readonly overall: Storage.Overall;
+    readonly requirements: ReadonlyArray<Requirement>;
+    readonly host: ReadonlyArray<HostEvidence>;
+    readonly checkedAt: DateTime.Utc;
+    readonly nextCheckAt: DateTime.Utc | null;
+}
+type Fx<A> = Effect.Effect<A, Errors.DomainKitError, Principal.Service>;
+export interface Interface {
+    /**
+     * What to observe, in order of precedence: `requirements` when supplied (an attached domain
+     * without a provisioning receipt, or a domain with no attachment whose records the customer
+     * applies by hand), else the latest provisioning receipt of the domain's attachment (records it
+     * applied or found in place). Neither is `InvalidInput`. Provider evidence is added when the
+     * attachment's session can be built; public DNS is always observed, and readiness is stored
+     * per domain either way.
+     */
+    readonly observe: (input: {
+        readonly domain: string;
+        readonly requirements?: ReadonlyArray<DnsRecord.Model>;
+    }) => Fx<Readiness>;
+    /** Merge host evidence into stored readiness without re-observing DNS. */
+    readonly attachEvidence: (input: {
+        readonly domain: string;
+        readonly evidence: ReadonlyArray<HostEvidence>;
+    }) => Fx<Readiness>;
+    readonly latest: (domain: string) => Fx<Readiness | null>;
+}
+declare const Service_base: Context.ServiceClass<Service, "@domainkit/Verify", Interface>;
+export declare class Service extends Service_base {
+}
+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;
+    /** Which resolvers must agree for `satisfied`: default `any`. */
+    readonly quorum: "any" | "all" | {
+        readonly minimum: number;
+    };
+}
+export declare const defaults: PolicyShape;
+declare const Policy_base: Context.Reference<PolicyShape>;
+export declare class Policy extends Policy_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>;
+export declare const layer: Layer.Layer<Service, never, Storage.Service | Connect.Service | Resolver.Service>;
+export declare const observe: (input: {
+    readonly domain: string;
+    readonly requirements?: ReadonlyArray<DnsRecord.Model>;
+}) => Effect.Effect<Readiness, Errors.DomainKitError, Principal.Service | Service>;
+export declare const attachEvidence: (input: {
+    readonly domain: string;
+    readonly evidence: ReadonlyArray<HostEvidence>;
+}) => Effect.Effect<Readiness, Errors.DomainKitError, Principal.Service | Service>;
+export declare const latest: (domain: string) => Effect.Effect<Readiness | null, Errors.DomainKitError, Principal.Service | Service>;
+export {};

package/dist/types/entry/client.d.ts

@@ -0,0 +1,2 @@
+/** domainkit/client */
+export * as Transport from "../Transport.ts";