@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAY7C,MAAM,MAAM,GAAG;IACb,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;IACxB,KAAK,EAAE;QACL,WAAW,EAAE;YACX,IAAI,EAAE;gBACJ,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE;oBACJ,WAAW,EACT,iJAAiJ;iBACpJ;aACF;YACD,MAAM,CAAC,OAAgB;gBACrB,OAAO;oBACL,OAAO,CAAC,OAAgB;wBACtB,KAAK,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;4BACvF,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;wBAC7D,CAAC;oBACH,CAAC;iBACF,CAAC;YACJ,CAAC;SACF;KACF;CACF,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/policy.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { type ApprovalState, Approver, type Principal } from "./define.ts";
+import type { Effect, Op } from "./op.ts";
+/** An operation as a policy sees it: plain data, without its schemas. */
+export type PolicyOp = Pick<Op, "id" | "vendor" | "resource" | "name" | "effect">;
+/**
+ * An operation as a policy sees it, for a `PolicyCall`: what the runtime passes, so a policy
+ * test can build a call from the connector, `{ op: policyOpOf(shop.order.refund), ... }`.
+ */
+export declare const policyOpOf: ({ id, vendor, resource, name, effect }: Op) => PolicyOp;
+/** What a policy sees for each operation a run calls. Plain data, so a test can build one by hand. */
+export interface PolicyCall {
+    op: PolicyOp;
+    /** The same as `op.effect`. */
+    effect: Effect;
+    /** The resource instance the call acts on, from the operation's `target`, when it declares one. */
+    target?: string;
+    /** The operation's input, already checked against its schema. */
+    input: unknown;
+    /** Who started the run. */
+    actor: Principal;
+    /**
+     * The run so far: a copy of its approvals, including those the policy asked for earlier.
+     * A policy request has `requestedBy: "policy"` and the `op` it held.
+     */
+    run: {
+        id: string;
+        workflow: string;
+        approvals: readonly ApprovalState[];
+    };
+}
+/**
+ * A policy's answer. `reasons` say why, for whoever reads the ledger; they change nothing
+ * about what happens to the call.
+ */
+export type Decision = {
+    kind: "allow";
+    reasons?: string[];
+} | {
+    kind: "deny";
+    reason: string;
+    reasons?: string[];
+} | ApproveDecision;
+/**
+ * Hold the call until the approver decides: a person's id, or `{ group }` for anyone in it.
+ * The approval covers the held operation, and `covers` adds others, so a policy can let their
+ * later calls through once it is approved.
+ */
+interface ApproveDecision {
+    kind: "approve";
+    approver: Approver;
+    title?: string;
+    covers?: Op[];
+}
+/**
+ * Checks a policy's answer. Parsing also copies it, so nothing else the policy returned is kept,
+ * and turns `covers` into op ids.
+ */
+export declare const DecisionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"allow">;
+    reasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"deny">;
+    reason: z.ZodString;
+    reasons: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"approve">;
+    approver: z.ZodType<Approver, unknown, z.core.$ZodTypeInternals<Approver, unknown>>;
+    title: z.ZodOptional<z.ZodString>;
+    covers: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodTransform<string, {
+        id: string;
+    }>>>>;
+}, z.core.$strip>], "kind">;
+/**
+ * A decision as checked and as the ledger records it: `covers` by op id, and the `version` of
+ * the policy that made it, when it has one.
+ */
+export type RecordedDecision = z.output<typeof DecisionSchema> & {
+    policyVersion?: string;
+};
+export declare const allow: (reasons?: string[]) => Decision;
+export declare const deny: (reason: string, reasons?: string[]) => Decision;
+/** Holds the call for `approver`. `covers` lists other operations the approval also stands for. */
+export declare function approve(approver: Approver, { title, covers }?: {
+    title?: string;
+    covers?: Op[];
+}): Decision;
+/**
+ * Decides whether a run may make an operation call: allow it, deny it (the run fails),
+ * or hold it until someone approves. Runs are replayed after a restart, so a policy must
+ * decide the same way every time from the call alone: no clock, randomness or network.
+ * `lintWorkflow` checks a policy file for these too. Each decision is recorded once made,
+ * and a replay reuses it, but a call interrupted before that is decided again. A policy
+ * must not have side effects.
+ */
+export type Policy = ((call: PolicyCall) => Decision | Promise<Decision>) & {
+    /** Names this version of the policy, from `definePolicy(fn, { version })`. */
+    readonly version?: string;
+};
+/** A policy, optionally named with a version so a reader can tell which rules decided a call. */
+export declare function definePolicy(policy: (call: PolicyCall) => Decision | Promise<Decision>, options?: {
+    version?: string;
+}): Policy;
+/** Allows every operation call. A config says so explicitly: `policy: allowAll`. */
+export declare const allowAll: Policy;
+/**
+ * True when an approval in the run was approved, covers the operation, and was addressed to
+ * `approver`. Check all three: a workflow can request an approval covering any operation from
+ * anyone it names, so an approval's `covers` alone does not say the right person approved.
+ */
+export declare function approvedFor(approvals: readonly ApprovalState[], opId: string, approver: Approver): boolean;
+export {};

package/dist/policy.js

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { Approver, Covers, sameApprover } from "./define.js";
+/**
+ * An operation as a policy sees it, for a `PolicyCall`: what the runtime passes, so a policy
+ * test can build a call from the connector, `{ op: policyOpOf(shop.order.refund), ... }`.
+ */
+export const policyOpOf = ({ id, vendor, resource, name, effect }) => ({
+    id,
+    vendor,
+    resource,
+    name,
+    effect,
+});
+const ReasonList = z.array(z.string(), { error: "reasons must be a list of strings" }).optional();
+/**
+ * Checks a policy's answer. Parsing also copies it, so nothing else the policy returned is kept,
+ * and turns `covers` into op ids.
+ */
+export const DecisionSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("allow"), reasons: ReasonList }),
+    z.object({ kind: z.literal("deny"), reason: z.string({ error: "deny needs a reason" }), reasons: ReasonList }),
+    z.object({
+        kind: z.literal("approve"),
+        approver: Approver,
+        title: z.string({ error: "the title must be a string" }).optional(),
+        covers: Covers,
+    }),
+], { error: "not a decision" });
+export const allow = (reasons) => reasons === undefined ? { kind: "allow" } : { kind: "allow", reasons };
+export const deny = (reason, reasons) => reasons === undefined ? { kind: "deny", reason } : { kind: "deny", reason, reasons };
+/** Holds the call for `approver`. `covers` lists other operations the approval also stands for. */
+export function approve(approver, { title, covers } = {}) {
+    return {
+        kind: "approve",
+        approver,
+        ...(title === undefined ? {} : { title }),
+        ...(covers === undefined ? {} : { covers }),
+    };
+}
+/** A policy, optionally named with a version so a reader can tell which rules decided a call. */
+export function definePolicy(policy, options = {}) {
+    if (typeof policy !== "function")
+        throw new Error("definePolicy expects a function of the call");
+    if (options.version !== undefined && (typeof options.version !== "string" || !options.version.trim())) {
+        throw new Error("definePolicy: `version` must be a non-empty string");
+    }
+    const defined = (call) => policy(call);
+    return Object.freeze(options.version === undefined ? defined : Object.assign(defined, { version: options.version }));
+}
+/** Allows every operation call. A config says so explicitly: `policy: allowAll`. */
+export const allowAll = definePolicy(() => allow());
+/**
+ * True when an approval in the run was approved, covers the operation, and was addressed to
+ * `approver`. Check all three: a workflow can request an approval covering any operation from
+ * anyone it names, so an approval's `covers` alone does not say the right person approved.
+ */
+export function approvedFor(approvals, opId, approver) {
+    return approvals.some((a) => a.status === "approved" && a.covers.includes(opId) && sameApprover(a.approver, approver));
+}
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/resource.d.ts

@@ -0,0 +1,378 @@
+import { z } from "zod";
+import { type HostSpec } from "./host.ts";
+import { type Connector, type OpSpec, RESOURCE } from "./op.ts";
+import { type Secret } from "./secret.ts";
+/** Which fields of a resource are flagged, by dotted path (`pages.html_url`; a list's items have no index). */
+export interface ResourceFields {
+    /** Changing it replaces the object. */
+    readonly immutable: readonly string[];
+    /** Set by the vendor only: never drift, and a data file may not declare it. */
+    readonly vendorOwned: readonly string[];
+    /** Sensitive or write-only: never read back, never compared, never in an operation's output. */
+    readonly writeOnly: readonly string[];
+    /** Lists whose order is the vendor's (a set): compared as multisets, in no order. */
+    readonly unordered?: readonly string[];
+    /**
+     * Fields that name another declared resource, by dotted path: the `<vendor>.<type>` it is, and
+     * how the vendor spells it (`by`): `{ repository_id: { type: "github.repository", by: ["name",
+     * "node_id"] } }`. A data file gives that resource there (`repository_id: site`), which stands
+     * for its `name`; anywhere else a resource is refused.
+     */
+    readonly references?: References;
+}
+/** Where a field names another declared resource: see `ResourceFields.references`. */
+export interface FieldReference {
+    /** The `<vendor>.<type>` of the resource it names. */
+    readonly type: string;
+    /**
+     * The fields of that resource's state the vendor may hold here instead of its `name`, such as
+     * GitHub's `node_id`: a drift check takes any of their values, read in the same run, as the
+     * declared one. Without it, the field holds the resource's `name`, and is compared as it is.
+     */
+    readonly by?: readonly string[];
+}
+/** A resource type's `fields.references`: by dotted path, the resource each names. */
+export type References = {
+    readonly [path: string]: FieldReference;
+};
+type State = Record<string, unknown>;
+/** A resource type, as its connector declares it with `defineResource`. */
+export interface ResourceSpec<S extends z.ZodObject = z.ZodObject> {
+    /** The connector's vendor id, such as `github`; `defineConnector` refuses a type of another vendor. */
+    vendor: string;
+    /** The type's name within the vendor, such as `repository`: its operations are `<vendor>.<type>.read` and `.import`. */
+    type: string;
+    /** What people call it, such as "Repository". */
+    title: string;
+    /**
+     * How `find` makes the import id, for people: `name`, `repository_id:pattern`. The fields it
+     * names stay declarable even when the vendor sets them. Absent with `find`: a type the vendor
+     * names alone (Stripe's) is found only by its binding.
+     */
+    identity?: string;
+    /** The resource's fields as a read returns them; a data file declares them, less the vendor-owned ones. */
+    schema: S;
+    fields: ResourceFields;
+    /**
+     * The import id that finds a declared resource before it is bound, from its declared fields:
+     * its identity. Absent when its fields cannot name it.
+     */
+    find?: (desired: z.input<S>) => string;
+    /**
+     * The id a binding keeps for an object, from its state: stable for the object's life (GitHub's
+     * `node_id`, not its name), and one `import` accepts. Default: `String(state.id)`.
+     */
+    bindingId?: (state: State) => string;
+    /**
+     * The part of a state that a drift check compares, given what was declared. The check
+     * compares `normalize(actual, desired)` with `normalize(desired, desired)`. Default:
+     * `compareDeclared`, which keeps the declared fields only.
+     */
+    normalize?: (state: State, desired: z.input<S>) => State;
+    /**
+     * True when apply may change its objects: the type then has the change operations `plan`,
+     * `create`, `update` and `delete` besides `read` and `import`. Default false.
+     */
+    writable?: boolean;
+    /** Set when the type meets the `Host` contract: it runs the company. Such a type is `writable` and `stateless`. */
+    host?: HostSpec;
+    /**
+     * True when its objects hold no data, so one gone at the vendor is created again by apply
+     * without asking (a host running the company's code); otherwise apply asks first, as a
+     * recreated database looks fine and has lost its data. Default: true for a host, else false.
+     */
+    stateless?: boolean;
+    /**
+     * Operations apply calls, in order, right after it creates one of its objects and binds it: a
+     * Supabase project's health, until it is healthy, then its database URL stored.
+     */
+    afterCreate?: readonly AfterCreate[];
+}
+/** One operation apply calls after a create (`ResourceSpec.afterCreate`). */
+export interface AfterCreate {
+    /** The operation's id, among the config's: `supabase.database.storeUrl`. */
+    op: string;
+    /** Its input, from the new object's binding id and the data file's export that declares it. */
+    input: (made: {
+        id: string;
+        export: string;
+    }) => unknown;
+    /**
+     * Called again, every few seconds, until its output passes this, for up to 10 minutes; a call
+     * that fails meanwhile is one that did not pass, its output `undefined`.
+     */
+    until?: (output: any) => boolean;
+}
+/**
+ * Where a declared resource keeps its brand, its type's `<vendor>.<type>`: a symbol, so a field
+ * holding a resource is told from data; a registered one (`Symbol.for`), so a copy of this
+ * package reads what another copy declared, as `VENDOR`.
+ */
+export declare const DECLARED: unique symbol;
+/** A resource a data file declares: `github.repository({ name: "sanoma" })`. */
+export interface Declared<Id extends string = string, T = State> {
+    readonly [DECLARED]: Id;
+    readonly vendor: string;
+    readonly type: string;
+    /** Its identity, the import id that finds it unbound: what `find` made of `desired`; absent without `find`. */
+    readonly name?: string;
+    /**
+     * Its fields, each resource it names replaced by that resource's `name`: what its type
+     * checked, and what a drift check compares.
+     */
+    readonly desired: T;
+    /**
+     * Where it names another resource: the field's dotted path (a list item's with its index,
+     * `teams.0`) to that resource's `<vendor>.<type>:<name>`.
+     */
+    readonly refs: Readonly<Record<string, string>>;
+}
+/**
+ * What a resource type's constructor takes: its fields, where `R` (its `fields.references`)
+ * names a path, a declared resource of that type instead of a value (`repository_id: site`), and
+ * where a string goes, a secret (`secret("NAME")`), which the constructor allows at a write-only
+ * field only.
+ */
+export type Declaring<T, R extends References = {}> = [keyof R] extends [never] ? WithSecrets<T> : DeclaringAt<T, R, "">;
+type WithSecrets<V> = V extends string ? V | Secret : V extends readonly (infer I)[] ? WithSecrets<I>[] : V extends object ? {
+    [K in keyof V]: WithSecrets<V[K]>;
+} : V;
+type DeclaringAt<T, R extends References, P extends string> = T extends readonly (infer I)[] ? DeclaringAt<I, R, P>[] : T extends object ? {
+    [K in keyof T]: K extends string ? DeclaringField<T[K], R, P extends "" ? K : `${P}.${K}`> : T[K];
+} : WithSecrets<T>;
+type DeclaringField<V, R extends References, P extends string> = P extends keyof R ? WithSecrets<V> | DeclaredOf<R[P]["type"]> : [Extract<keyof R, `${P}.${string}`>] extends [never] ? WithSecrets<V> : DeclaringAt<V, R, P>;
+type DeclaredOf<Id> = Id extends string ? Declared<Id> : never;
+/** What a plan of a change says will happen, as `PlanResponse.Action` names it. */
+export declare const PLAN_ACTIONS: readonly ["none", "create", "update", "replace", "delete"];
+export type PlanAction = (typeof PLAN_ACTIONS)[number];
+/** The operations of a writable type that change its objects: only the apply workflow calls them (`isChangeOp`). */
+export declare const CHANGE_OPS: readonly ["create", "update", "delete"];
+declare const opsOf: <S extends z.ZodObject>(schema: S) => {
+    import: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            gone: z.ZodBoolean;
+            state: z.ZodOptional<S>;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    read: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            gone: z.ZodBoolean;
+            state: z.ZodOptional<S>;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    plan: {
+        input: z.ZodObject<{
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            desired: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            action: z.ZodEnum<{
+                create: "create";
+                delete: "delete";
+                none: "none";
+                replace: "replace";
+                update: "update";
+            }>;
+            planned: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            unknown: z.ZodArray<z.ZodString>;
+            replace: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    create: {
+        input: z.ZodObject<{
+            desired: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            state: S;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    update: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+            desired: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            expect: z.ZodOptional<z.ZodObject<{
+                action: z.ZodEnum<{
+                    create: "create";
+                    delete: "delete";
+                    none: "none";
+                    replace: "replace";
+                    update: "update";
+                }>;
+                replace: z.ZodArray<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            state: S;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    };
+    delete: {
+        input: z.ZodObject<{
+            id: z.ZodString;
+            state: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            handle: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        output: z.ZodObject<{
+            id: z.ZodString;
+            gone: z.ZodLiteral<true>;
+        }, z.core.$strip>;
+    };
+};
+type OpsOf<S extends z.ZodObject> = ReturnType<typeof opsOf<S>>;
+type Specs<S extends z.ZodObject, N extends keyof OpsOf<S>> = {
+    [K in N]: OpSpec<OpsOf<S>[K]["input"], OpsOf<S>[K]["output"]>;
+};
+/**
+ * A resource type's operation specs: `read` and `import`, and for a writable type (`W`) the
+ * change operations `plan`, `create`, `update` and `delete`.
+ */
+export type ResourceOps<S extends z.ZodObject, W extends boolean = false> = Specs<S, "read" | "import"> & ([W] extends [true] ? Specs<S, "plan" | (typeof CHANGE_OPS)[number]> : {});
+/**
+ * True for an operation that changes a writable type's objects (`CHANGE_OPS`), which only the
+ * apply workflow may call: by its vendor, resource and name, so a copy of a connector is told too.
+ */
+export declare function isChangeOp(op: {
+    readonly vendor: string;
+    readonly resource: string;
+    readonly name: string;
+}, types: ReadonlyMap<string, Pick<Resource, "writable">>): boolean;
+/**
+ * A resource type: call it to declare a resource in a data file, and give it to
+ * `defineConnector` as a group, under its `type`: `defineConnector("github", { repository })`.
+ */
+export interface Resource<S extends z.ZodObject = z.ZodObject, Id extends string = string, R extends References = {}, W extends boolean = boolean> extends Readonly<Required<Omit<ResourceSpec<S>, "identity" | "find" | "writable" | "host" | "stateless" | "afterCreate">>>, Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "afterCreate">> {
+    (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
+    /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
+    readonly ops: ResourceOps<S, W>;
+    /** True when apply may change its objects: it has the change operations. */
+    readonly writable: W;
+    /** True when apply may recreate or replace its objects as routine: they keep no data. */
+    readonly stateless: boolean;
+    readonly [RESOURCE]: true;
+}
+/** True for a plain object: not null, not a list. */
+export declare const isObject: (v: unknown) => v is State;
+/** `path.name`, or `name` at the top: a field's dotted path. */
+export declare const joinPath: (path: string, name: string) => string;
+/**
+ * The fields of `state` that `desired` declares, minus vendor-owned and write-only ones: only
+ * declared fields are compared, as CloudFormation does. An object is picked field by field, a
+ * list item by item against the declared item at its index, and an `unordered` list (a set)
+ * item by item against what its declared items declare, then sorted, so its order never
+ * drifts. Anything else is kept whole.
+ *
+ * So a field the data file leaves out is never drift, whatever the vendor holds. That covers
+ * attributes the provider marks `computed` and `optional`: they are the user's to set, not
+ * vendor-owned, but the vendor fills them when nobody does (GitHub's `etag`, `topics`,
+ * `visibility`), so they are compared only when declared.
+ */
+export declare function compareDeclared(fields: ResourceFields, state: State, desired: State): State;
+/** A declared field the vendor holds another value in. */
+export interface DriftField {
+    /** Its dotted path, a list item's with its index: `required_pull_request_reviews.0.dismiss_stale_reviews`. */
+    path: string;
+    /** What the data file declares. */
+    desired: unknown;
+    /** What the vendor holds, `null` for nothing. */
+    actual: unknown;
+}
+/**
+ * Where `state` differs from what `desired` declares: the type's `normalize` of each (by default
+ * `compareDeclared`: declared fields only, never vendor-owned or write-only ones, `unordered`
+ * lists as sets), then leaf by leaf: objects field by field, lists of one length item by item,
+ * and anything else (a list whose length changed, an `unordered` one) whole.
+ *
+ * `accept` is, by a reference's path as `refs` has it (`repository_id`, `teams.0`), the values
+ * the vendor may hold there for the resource it names (its `node_id`, say: see
+ * `FieldReference.by`): any of them counts as the declared value.
+ */
+export declare function diffDeclared(resource: {
+    readonly fields: ResourceFields;
+    readonly normalize: (state: State, desired: any) => State;
+}, state: State, desired: State, accept?: Readonly<Record<string, readonly unknown[]>>): DriftField[];
+/** The object or list holding the value at a dotted path (a list item's by its index), and its key there. */
+export declare function holderOf(value: unknown, path: string): {
+    holder: State;
+    key: string;
+} | undefined;
+/** A field's dotted path as `fields` names it, without a list item's index: `teams.0` is `teams`. */
+export declare const fieldPathOf: (at: string) => string;
+/** The value at a dotted path, a list item's by its index. */
+export declare const valueAt: (value: unknown, path: string) => unknown;
+/**
+ * `desired` without the values at the fields the type marks write-only (a webhook's `secret`):
+ * what a run may record of a declaration. A list's items lose them too. A secret marker
+ * (`secret("NAME")`) stays, there or inside a write-only map (a host's `secrets`): it names a
+ * stored secret and holds none, and the driver resolves it.
+ */
+export declare function withoutWriteOnly(fields: ResourceFields, desired: State): State;
+/**
+ * Declares a resource type: its schema, flagged fields, identity and how it is compared, and
+ * derives its operations, `<vendor>.<type>.read` and `<vendor>.<type>.import`, both effect
+ * `read` and idempotent, with the import id as the policy's `target`:
+ *
+ * - `import` takes `{ id }`, an identity (what `find` makes) or a binding id (what `bindingId`
+ *   makes), and returns `{ gone: false, state }`, the object's
+ *   state (with the driver's opaque `handle` when it keeps one), or `{ gone: true }` when the
+ *   vendor has no such object.
+ * - `read` takes `{ id, state?, handle? }`, a state from an earlier `import` or `read`, and
+ *   returns the same: `{ gone: true }` when the object no longer exists, else its fresh
+ *   `state`. A driver may import first when it is given no state.
+ *
+ * A `writable` type has the change operations too, which only the apply workflow may call
+ * (`isChangeOp`): `create`, `update` and `delete` effect `write` (`delete` idempotent), and `plan`:
+ *
+ * - `plan` (`read`, idempotent) takes `{ id?, state?, handle?, desired? }`, no `desired` for a
+ *   delete and no `id` for a create, and returns `{ action, planned?, unknown, replace }`:
+ *   what apply would do, the new state without write-only fields, the paths known only after
+ *   apply, and those whose change replaces the object.
+ * - `create` (`target` `new:<vendor>.<type>`) takes `{ desired }` and returns `{ id, state,
+ *   handle? }`, `id` its binding id.
+ * - `update` takes `{ id, state?, handle?, desired, expect? }` and returns the same; given
+ *   `expect` (a plan's `action` and `replace`), it refuses a fresh plan that differs
+ *   (`DriverError`, `vendorCode` `plan_changed`).
+ * - `delete` takes `{ id, state?, handle? }` and returns `{ id, gone: true }`.
+ *
+ * `desired` may hold secret markers at write-only fields, which the driver resolves; no output
+ * holds a write-only value.
+ *
+ * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
+ *
+ * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
+ * is a `Declared`, `{ vendor, type, name: "sanoma", desired, refs: {} }`. It refuses fields the
+ * schema does not have, fields the vendor owns (unless the identity names them), values the
+ * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
+ * another declared resource of that type (`repository_id: site`): `desired` holds, and the
+ * schema and `find` read, that resource's `name`, and `refs` says where it was named. A type
+ * without `find` declares resources without a `name`, found only by their bindings.
+ */
+export declare function defineResource<S extends z.ZodObject, const V extends string, const T extends string, const R extends References = {}, const W extends boolean = false>(spec: ResourceSpec<S> & {
+    vendor: V;
+    type: T;
+    fields: {
+        references?: R;
+    };
+    writable?: W;
+}): Resource<S, `${V}.${T}`, R, W>;
+/** Every resource type the connectors declare, by `<vendor>.<type>`. */
+export declare function resourceTypesOf(connectors: readonly Connector<any, any>[]): Map<string, Resource>;
+export {};