@listen-fire/movement-lang 0.12.0-rc.2 → 0.12.0-rc.6

package/dist/{checker/catalog.d.ts → catalog/types.d.ts}

@@ -1,8 +1,5 @@
-import type { EdgeCapability, EdgeSequencing, Expression, FieldCapability } from '@listen-fire/shared/expression/types';
-import { type LanguageVersion } from '../language_version';
-import type { CallArg, NamedArg, PluginCall, Program, Span, TypeDeclaration } from '../parser/ast';
-import type { DeclaredEffectRow } from './effects';
-import { type PositionTypeRef } from './typing';
+import type { LanguageVersion } from '../language_version';
+import type { EdgeCapability, EdgeSequencing, Expression, FieldCapability } from '../expression/types';
 /**
  * One argument in an adapter's construction signature. The list is the full
  * signature: the credential (when the adapter needs one) is just an entry with
@@ -97,7 +94,7 @@ export interface AdapterSpec {
     /**
      * Per-key value FORMATS the checker validates statically. `'cron'`
      * validates the value as a five-field cron expression; `'timezone'`
-     * validates it as an IANA time-zone id (@listen-fire/shared/cron — the same
+     * validates it as an IANA time-zone id (movement-lang/cron — the same
      * parser the platform scheduler runs, so check time and fire time can
      * never disagree).
      *
@@ -153,6 +150,9 @@ export interface AdapterSpec {
      * reads it.
      */
     schemaShape?: 'static' | 'introspected';
+    /** What the adapter says it is (its manifest's `description`). The checker
+     *  never reads it; the language service's hover leads with it. */
+    description?: string;
 }
 /**
  * The credential arg in a construction signature, if the adapter needs one.
@@ -179,51 +179,6 @@ export declare function credentialArgOf(spec: Pick<AdapterSpec, 'constructionArg
  * `''` means the meta position (the node you get when you pin nothing).
  */
 export declare function entryPositionKeyOf(spec: Pick<AdapterSpec, 'constructionArgs'>, args: Record<string, string> | undefined): string;
-/** One adapter-declared interactive connect action — the declaration half
- *  of the generalised "+" connect affordance. `kind` names an app-shipped
- *  client handler; `label` is the suggestion text. The language stays pure:
- *  it carries the declaration and never interprets `kind`. */
-export interface ConnectAction {
-    kind: string;
-    label: string;
-}
-/**
- * The one UNIVERSAL listen-config key — valid on every listener regardless of
- * adapter, like `dry_run` is the universal construction arg. It is NOT a loop
- * detector: it's a declarative 2-WAY-SYNC semantic. When an author builds an
- * A↔B sync (a movement that both reads and writes the same system) they set
- * `suppress_self: true` to mean "ignore my own writes echoing back into this
- * system," so the sync doesn't self-trigger.
- *
- * DEFAULT OFF (absent / false). Off matters: a user legitimately wants to react
- * to Listen-Fire's own writes (Movement 1 writes a company to Attio → Movement 2
- * posts new Attio companies to Slack). A default-on suppression would nuke that.
- *
- * Boolean-literal only. Validated centrally in `checkListen` (so every adapter
- * accepts it without each declaring it), then carried into
- * the persisted trigger config; the dispatch boundary capability-gates it on
- * the adapter answering "did WE author this change?". An adapter that can't
- * answer makes it a clearly-logged no-op.
- */
-export declare const SUPPRESS_SELF_KEY = "suppress_self";
-/**
- * The event node's change-kind field — the ONE protocol name (like
- * `suppress_self` or the `events:` listen key) for "which kind of event this
- * occurrence is". An adapter with a change-kind axis declares an ordinary
- * enum field of this name on its event node, its options exactly the
- * listen's `events:` vocabulary; a listen's selection then pins it in the
- * derived event address, and a signature narrows with
- * `` WHERE `action` == "record.created" ``. Adapters with no such axis
- * (cron's tick, a messaging Message Received) simply declare no such field.
- *
- */
-export declare const EVENT_ACTION_FIELD = "action";
-/** The `events:` value that means "the record no longer exists" — the pin
- *  under which `requiresLiveRecord` edges are dropped from a narrowed event
- *  position (the one real behaviour the retired delete VARIANT carried,
- *  keyed on the pin rather than on a synthesized name). The `record.*`
- *  vocabulary is deliberately uniform across adapters (attio, airtable). */
-export declare const RECORD_DELETED_ACTION = "record.deleted";
 export interface CredentialSpec {
     /** The adapters this credential can authenticate — `slack(credentials: <attio cred>)`
      *  is a type error unless 'slack' is in this set. A credential *type* may serve
@@ -335,6 +290,14 @@ export interface PluginSpec {
     /** The package tag it is a member of (`@lf/web`), matched exactly
      *  (`packageMembers`); absent when it is in none. */
     package?: string;
+    /**
+     * The name a program spells it (`fetch_url`), when the catalog's key is not
+     * that: a plugin in a package is keyed by package AND name (`pluginKey`), so
+     * two packages can each serve a `render`. Absent: the key is the name.
+     */
+    name?: string;
+    /** What it does, in its author's words (its signature's `description`). */
+    description?: string;
 }
 /** One `fedArgs` entry: the argument's name, and whether a PLAIN call must
  *  write it (a stage never does either way). */
@@ -342,88 +305,24 @@ export interface PluginFedArg {
     name: string;
     required?: true;
 }
-/** One plugin of a package: the name it is called by after the package's
- *  local name and a dot, and the catalog's key it invokes. */
-export interface PackageMember {
-    name: string;
-    key: string;
-}
-/** The plugins whose spec declares `tag` as its package, in catalog order;
- *  none when no spec does, which is how a package import is told from an
- *  import of one plugin. */
-export declare function packageMembers(catalog: Pick<Catalog, 'plugin' | 'pluginNames'>, tag: string): PackageMember[];
-/** The local name a package's member is bound to: `web.fetchUrl`. */
-export declare function memberLocal(packageLocal: string, member: string): string;
-/** The program with each package import read as the imports of its members
- *  (`` `@lf/web` as web `` → `fetch_url as web.fetchUrl`, …), which is what an
- *  engine binds. An import that names no package is left as written. The
- *  checker does not read this: it binds the same names itself, keeping the
- *  package to name in a diagnostic. */
-export declare function expandPackageImports(program: Program, catalog: Pick<Catalog, 'plugin' | 'pluginNames'>, languageVersion: LanguageVersion): Program;
-/** The parameter a plain call hands a plugin fed only by an extraction (from
- *  language version 5): the record it runs on, which a `through [ … ]` stage
- *  fed it implicitly. */
-export declare const EXTRACTED_RECORD_PARAM = "record";
-/**
- * A plugin as a plain call sees it under `languageVersion`. From version 5 a
- * plugin is a function, so one fed only by an extraction is no longer a
- * stage: what the stage fed it implicitly — the record it enriched — becomes
- * its one required input, written by position like any fed argument and
- * taking structured data. Versions 1–4 read the spec as it is, and refuse the
- * call. The Rust twin is `PluginSpec::under` (crates/movement-parser/src/catalog/plugin_args.rs).
- */
-export declare function pluginSpecUnder(spec: PluginSpec, languageVersion: LanguageVersion): PluginSpec;
-/** Where a plugin is called: a plain call writes the arguments a stage is
- *  fed, a `through [ … ]` stage never does. */
-export type PluginCallSite = 'plain' | 'stage';
-/** A positional call that does not fit the plugin's parameters. */
-export type PluginArgMisfit = 
-/** An argument past the positional parameters that is not the settings record. */
-{
-    kind: 'extra';
-    span: Span;
-}
-/** A settings key that names a parameter taken by position. */
- | {
-    kind: 'settingIsPositional';
-    name: string;
-    span: Span;
-}
-/** A settings record member that is not `name: value`. */
- | {
-    kind: 'settingNotNamed';
-    span: Span;
-};
-/** A call's arguments, bound to the plugin's parameters by name. */
-export interface PluginArgBinding {
-    args: CallArg[];
-    misfits: PluginArgMisfit[];
-}
-/** The parameters a call fills by position, in the manifest's declared
- *  order. The spec keeps the fed parameters apart from the author's, and
- *  every plugin declares its fed one first, so fed-then-author is that order. */
-export declare function pluginPositionalParams(spec: PluginSpec, site: PluginCallSite): string[];
-/** What is wrong, in the words both checkers report (MOV_THROUGH_BAD_ARG). */
-export declare function pluginArgMisfitMessage(misfit: PluginArgMisfit, callee: string, positional: readonly string[]): string;
-/** Positional arguments named by `pluginPositionalParams`; the argument
- *  after those, written as a record literal, is the settings, each entry a
- *  named argument whose value is its own slot; any further one is a misfit.
- *  A named argument stays as written. */
-export declare function bindPluginArgs(spec: PluginSpec, site: PluginCallSite, args: readonly CallArg[], options: {
-    languageVersion: LanguageVersion;
-}): PluginArgBinding;
-/** A `through [ … ]` stage's arguments, bound to the plugin's parameters by name. */
-export interface StageArgBinding {
-    args: NamedArg[];
-    misfits: PluginArgMisfit[];
-}
-/** A stage's positional arguments bound as a call's are, with the stage's
- *  positional parameters (never a fed one). */
-export declare function bindStageArgs(spec: PluginSpec, stage: PluginCall, options: {
-    languageVersion: LanguageVersion;
-}): StageArgBinding;
-/** Where an argument is written, whatever form it takes. */
-export declare function callArgSpan(arg: CallArg): Span;
+/** The catalog key of a package's plugin: module and name together, so two
+ *  packages can each serve a plugin of the same name. Compared, never parsed
+ *  (a spec carries its own `name`). The Rust twin is `plugin_key`. */
+export declare function pluginKey(packageTag: string, name: string): string;
+/** A plugin as a program writes it: its key's own name unless the spec says. */
+export declare function pluginProgramNameOf(key: string, spec: PluginSpec): string;
+/** What a written plugin name stands for among `plugins`: the entry keyed by
+ *  exactly that (a package member's key), else the one entry whose name it is
+ *  (a bare import, as versions 1 to 4 write it); several such are `ambiguous`,
+ *  listing the packages that serve it. The Rust twin is `find_plugin`. */
+export declare function findPlugin(plugins: Readonly<Record<string, PluginSpec>>, name: string): {
+    found: {
+        key: string;
+        spec: PluginSpec;
+    };
+} | {
+    ambiguous: string[];
+} | undefined;
 /**
  * What a plugin's plain call evaluates to, on whichever PLANE it lives — the
  * same two planes every other bound value has, and no third type language:
@@ -449,290 +348,6 @@ export type PluginOutput = {
     kind: 'records';
     fields: Record<string, SchemaFieldType>;
 };
-/** What a plain call to `spec`'s plugin hands back to a program pinned to
- *  `languageVersion` — its current output, or an older shape it kept for
- *  programs pinned before the change (`PluginSpec.earlierOutputs`). */
-export declare function pluginOutputUnder(spec: PluginSpec, languageVersion: LanguageVersion): PluginOutput | undefined;
-/**
- * The value type of a field/property. Deliberately small: enough to catch
- * shape mistakes (text into a number field, a string into a file slot)
- * without reproducing every adapter's type system.
- */
-export type FieldType = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'file'
-/**
- * A structured value — the DATA top type, TypeScript's `unknown` for the
- * data plane. Every data shape is assignable TO it (text, number, boolean,
- * date/datetime, a list of data, an object literal, json itself); `file` is
- * not, because a file is a HANDLE, not data. Nothing is assignable FROM it:
- * a json value has no known shape, so operating on one (arithmetic,
- * comparison, text concatenation) is an error and the author passes it
- * through unchanged. Narrowing constructs are deliberately absent — an
- * adapter field declared `json` mirrors the target API verbatim, which is
- * the point (plans/slack-blocks-json-fields-2026-07-30).
- */
- | 'json'
-/**
- * The type of the `null` LITERAL, and of nothing else — TypeScript's `null`
- * under strictNullChecks. It is the one value every `T | absent` may turn out
- * to be, which is what makes `x == null` a legal comparison at any `T` and a
- * meaningful one only where absence is possible. No adapter surface declares
- * it (a field is `T` or `maybeAbsent(T)`, never this), so it reaches nothing
- * outside the checker's own expression typing.
- */
- | 'absent'
-/**
- * The type of a value that never arrives — `fail("…")` written inside an
- * expression (language version 5) — TypeScript's `never`. It fits every
- * type, and a union with it is the union's other members.
- */
- | 'never'
-/**
- * A collection of values. `unordered` is the ORDER discipline's value-plane
- * half: the list's members are there, but the sequence they are in means
- * nothing, so an order-sensitive fold over it is refused. A list is a
- * sequence by construction (a literal, a source's own multi-value field, a
- * tuple), so the flag is the exception, set only where the order genuinely
- * came from nowhere — a block bound over an unordered traversal, a `COLLECT`
- * of one. The position plane carries the same fact differently (a walk's
- * last hop is sequenced, or it isn't), exactly as absence does.
- */
- | {
-    kind: 'list';
-    of: FieldType;
-    unordered?: true;
-}
-/**
- * `<[T, U]>` — a heterogeneous list whose slots were written down: a list
- * literal (`[m.Body, file]` is `[text, file]`, from language version 3;
- * earlier versions type a literal as the list it reads as) and the receipt of a
- * combinator written with literal arms (`await parallel([f, g])`). Every slot
- * is its own type, so a literal-index read (`AT(r, 0)`) types exactly; every
- * other operation reads a tuple as the list it widens to — TypeScript's
- * tuple-to-array assignability.
- *
- * A slot is `null` where the value could not be typed — "we could not see",
- * spelled with the one nothing-value JSON can carry, since this type crosses
- * the wire verbatim. `'absent'` is the other answer and means the opposite:
- * this arm hands nothing back, so the slot's VALUE is always null at run
- * time.
- *
- * `rest` makes the tuple VARIADIC — TypeScript's `[T, ...U[]]`: a run of
- * any length (zero included) of `rest.of`, sitting just before slot
- * `rest.at` (`at === of.length` puts it last). A spread of a list into a
- * literal is what writes one: `[m.Body, ...files]` is `[text, ...file[]]`.
- * There is at most one run — a second spread folds everything from the
- * first run onward into it, as TypeScript does.
- */
- | {
-    kind: 'tuple';
-    of: Array<FieldType | null>;
-    rest?: TupleRest;
-}
-/**
- * `{ k: v, … }` — a collection keyed by TEXT. Keys are strings and nothing
- * else: a dict is JSON-object-shaped, which is the whole value world's one
- * story (snapshots, `json` interop, the wire), and JSON has no other key. A
- * key that arrives as some other type is a save error demanding the author
- * write the coercion down, never a silent stringification.
- *
- * `of` is what a key nobody wrote down may hold: the value type every key
- * shares, or `json` when they disagree — json is the data type every value
- * flows into. (A value union exists, but only as what a tuple widens to.)
- *
- * `shape` is the TypeScript object literal's type: a dict WRITTEN as a
- * literal knows its keys, so a lookup by a literal key reads that key's own
- * type, present, and a literal key it does not have is refused. A key is
- * `null` where its value could not be typed — "we could not see", as a
- * tuple's slot is. Absent on every dict whose keys are data rather than
- * program text: `GROUPBY`/`KEYBY`'s answers, and every adapter surface.
- *
- * There is no order: a dict is looked up, never folded, so the set/list
- * discipline has nothing to say about one. What `GROUPBY` puts INSIDE it —
- * a list per key — carries the source's ordering as any other list does.
- */
- | {
-    kind: 'dict';
-    of: FieldType;
-    shape?: Record<string, FieldType | null>;
-}
-/** `open` marks a KNOWN-VALUES field, not a closed enum: the options are
- *  what the adapter could enumerate live (Slack channels, select options),
- *  but other values remain legal — ids matching `allowPattern`, runtime
- *  expressions, values the listing couldn't see. Literal membership misses
- *  are WARNINGS with a did-you-mean, never errors. */
- | {
-    kind: 'enum';
-    options: string[];
-    open?: {
-        allowPattern?: string;
-    };
-}
-/**
- * `T | absent` — a value that MAY not be there (asks-as-adapter P20/F13). Read
- * from a PARTIAL context (a race receipt property bound in only some branches,
- * F18) or a maybe-empty node's field (an awaited landing off a `resolvesEmpty`
- * edge, F19/F20). It PROPAGATES silently through expressions; the checker
- * errors only where a NON-ABSENT value is REQUIRED (a plain write field, an
- * ordered comparison), never at the read — the TS `T | undefined` model.
- * Discharged by a `?:` (fill) write field, a traversal-as-gate, or an `==`
- * guard (equality tolerates absence and narrows). Produced ONLY by
- * the checker's typing layer; it never appears in an adapter/schema surface, so
- * runtime data (the engine, trpc) never carries it. `of` is never itself
- * `maybeAbsent` — construct via the `maybeAbsent()` helper, which flattens. */
- | {
-    kind: 'maybeAbsent';
-    of: FieldType;
-}
-/**
- * `T | U` — a value that is one of several types, TypeScript's union. It
- * arises where a tuple is READ as a list: `[text, number]` widens to a list
- * of `text | number`, as TypeScript widens `[string, number]` to
- * `(string | number)[]` (language version 3; earlier versions read such a
- * tuple as a list nobody can type).
- *
- * A union IS its member set, as a record-position union is: build one only
- * through `valueUnion`, which keeps the set canonical — flattened (no member
- * is a union), de-duplicated, sorted by display, at least two members (one
- * member is that member), absence hoisted out (`maybeAbsent` wraps the
- * union, never sits inside it), a member another member already accepts
- * absorbed (`json` takes every data shape, `text` every enum). Members are
- * VALUES: records and values have no union (a list of both is
- * `MOV_LIST_MIXED`), and records of different positions are already one
- * record type.
- *
- * Produced only by the checker's typing layer; no adapter surface declares
- * one.
- */
- | {
-    kind: 'union';
-    of: FieldType[];
-}
-/**
- * A RECORD held as a value — a traversed record, a write handle, a
- * synthesised node, an extraction result. One type universe: a record is
- * what `MAP` hands back when its function returns one, what a list literal
- * of them holds, and what a map's key can carry, so lists and dicts nest
- * over records exactly as they nest over text.
- *
- * It is a value TYPE, not a value shape: nothing reads it as data. A record
- * written into a field, interpolated into text, added up or compared to a
- * scalar is refused where it is written; what it CAN do is be walked from
- * (a block head), read by field (the dot plane), and held in a collection.
- *
- * `position` is which record, where the checker can say — the same
- * `PositionTypeRef` the arrow plane uses, never a parallel one. ABSENT means
- * "a record, and nobody can name which": members of a list that disagree,
- * an extraction result, a synthesised node. The distinction is load-bearing
- * and is the same one `LocalEdge.target` draws — a walk off a record whose
- * position is unknown stays silent and runs, and one off a named position is
- * checked.
- */
- | {
-    kind: 'record';
-    position?: PositionTypeRef;
-};
-/** A variadic tuple's run: any number of `of`, just before slot `at`. `of` is
- *  `null` where the run's members could not be typed. */
-export interface TupleRest {
-    at: number;
-    of: FieldType | null;
-}
-/**
- * What an adapter SURFACE can declare — every field type except a record,
- * nested collections included.
- *
- * A record is a place in a graph, and no adapter field is one: a record type
- * arises only where the checker types an EXPRESSION. Saying so here is what
- * keeps a schema clear of the position model — and a schema crosses the wire
- * (`InstanceSchema` is a tRPC response), where a field type that reached into
- * positions would reach back into schemas again, a cycle no serialiser's type
- * can follow.
- *
- * The collections are spelled a second time because TypeScript cannot subtract
- * a member from a RECURSIVE union — `Exclude` removes the record at the top
- * and leaves `list of record` behind, which is the same cycle. The scalars and
- * every rule about them live on `FieldType` above; this is that union with one
- * member gone, and every `SchemaFieldType` IS a `FieldType`, so nothing that
- * reads a schema needs to know which it was handed.
- */
-export type SchemaFieldType = Exclude<FieldType, {
-    kind: string;
-}> | {
-    kind: 'list';
-    of: SchemaFieldType;
-    unordered?: true;
-} | {
-    kind: 'tuple';
-    of: Array<SchemaFieldType | null>;
-} | {
-    kind: 'dict';
-    of: SchemaFieldType;
-} | {
-    kind: 'enum';
-    options: string[];
-    open?: {
-        allowPattern?: string;
-    };
-} | {
-    kind: 'maybeAbsent';
-    of: SchemaFieldType;
-};
-/**
- * A field type spelled as ONE tagged variant — the scalars given the `kind`
- * the collections already carry.
- *
- * `FieldType` is half bare names and half objects, so a `switch` could never
- * see it whole: every branch over it was a `typeof === 'object'` if-chain, the
- * compiler enumerated nothing, and a new variant silently took whichever
- * fallthrough happened to come last. Both halves here are DERIVED from the
- * type parameter, so this is not a second list to keep in step — add a variant
- * to `FieldType` and every `switch` over a variant stops compiling at once.
- *
- * Generic in the type it normalises so a `SchemaFieldType` stays one: its
- * `list` still holds a `SchemaFieldType`, and its switch still has no `record`
- * case to answer.
- */
-export type FieldTypeVariant<T extends FieldType = FieldType> = {
-    kind: Extract<T, string>;
-} | Extract<T, {
-    kind: string;
-}>;
-/**
- * Normalise a field type for an exhaustive `switch (variantOf(t).kind)`.
- *
- * The one assertion is the boundary the whole scheme rests on: `typeof` cannot
- * prove to TypeScript that a GENERIC `T`'s string half is `Extract<T, string>`,
- * though it is, by construction of the union.
- */
-export declare function variantOf<T extends FieldType>(type: T): FieldTypeVariant<T>;
-/** Maps a surface type name (shape declarations, extract annotations) to a SchemaFieldType. */
-/**
- * The type a `type Thesis = <"A" | "B">` declaration names — a CLOSED enum,
- * identical in shape to an option set borrowed from a live field, so nothing
- * downstream (extraction prompt, literal check, did-you-mean) can tell a
- * written refinement from a fetched one.
- */
-export declare function declaredTypeOf(decl: TypeDeclaration): SchemaFieldType;
-/**
- * Every refinement a program declares, by name. A `type` is a FILE-level
- * declaration, so this flat map and the checker's scope resolution answer the
- * same question — the engine, which has no scopes, asks it this way.
- */
-export declare function declaredTypesIn(program: Program): Map<string, SchemaFieldType>;
-export declare function parseFieldTypeName(name: string | undefined): SchemaFieldType | undefined;
-/** The dotted segments of a borrowed-type annotation, or undefined for a
- *  plain (primitive) type name. */
-export declare function borrowedTypeSegments(name: string | undefined): string[] | undefined;
-/**
- * The borrowable fields of one root/position of a schema: the writable
- * root's fields unioned with the position's properties. Writable fields
- * win per-name — enums (select options) live on the write surface.
- * Undefined when the schema has no root or position of that name.
- */
-export declare function borrowableFieldsOf(schema: InstanceSchema, rootName: string): Record<string, SchemaFieldType> | undefined;
-/** Resolve `<root>.<field>` of a borrowed path against a schema. */
-export declare function resolveBorrowedField(schema: InstanceSchema, rootName: string, fieldName: string): SchemaFieldType | undefined;
-export declare function describeFieldType(type: FieldType): string;
 /** A reference (edge) declared by a position type. */
 export interface EdgeSchema {
     /** The position type (or union) the edge points at. */
@@ -909,6 +524,9 @@ export interface EdgeSchema {
      * only: nothing resolves `_resources` to it.
      */
     resources?: true;
+    /** What the adapter says the edge is (a reference's `description`). The
+     *  checker never reads it; the language service's hover leads with it. */
+    description?: string;
 }
 /** A readable position type: its properties and outgoing references. */
 export interface PositionSchema {
@@ -1049,22 +667,14 @@ export interface PositionSchema {
      * undescribed or pending position says nothing, so nothing is refused).
      */
     deletable?: boolean;
+    /** What the adapter says a record of this type is, in its own words (its
+     *  describe's or entry point's `description`). The checker never reads it;
+     *  the language service's hover leads with it. */
+    description?: string;
+    /** What the adapter says each field is, by name — every field it described,
+     *  readable or write-only. */
+    fieldDocs?: Record<string, string>;
 }
-/**
- * May a check state that this position's surface LACKS something?
- *
- * No, on any of the three facts above: an OPEN position says its surface is
- * wider than what's enumerated, an UNDESCRIBED one says nothing at all, and a
- * PENDING one has not been asked yet — none licenses "it has no field X".
- *
- * They stay separate fields because they answer a DIFFERENT question
- * differently: may the author touch the handle? An open position, yes (it is a
- * positive claim); an undescribed one, no (`MOV_UNDESCRIBED_POSITION`); a
- * pending one, yes-for-now — silently, because the answer is still coming and
- * the author has done nothing wrong. This helper is only for the first
- * question, and exists so no call site has to remember to ask about all three.
- */
-export declare function surfaceNotEnumerated(schema: PositionSchema | undefined): boolean;
 /**
  * A DISCRIMINATED write shape — the write-side dual of read narrowing. On the
  * read side a WHERE's literal selects a variant type (`-[:Base WHERE `Name` ==
@@ -1428,25 +1038,6 @@ export interface InstanceSchema {
      */
     eventNarrowingValues?: Record<string, Record<string, string[]>>;
 }
-/** Whether a write may land on this edge. The two promises default OPPOSITE
- *  ways — `readable` absent means readable, `writable` absent means read-only
- *  (layer 13) — which is exactly the asymmetry a second reader gets wrong. So
- *  everyone who asks asks HERE: the checker's gate, the diagnostics that list
- *  the writable spellings, and the agent-facing describe surface. They cannot
- *  answer differently if there is only one answer. */
-export declare function edgeIsWritable(edge: EdgeSchema): boolean;
-/** Whether a read traversal may walk this edge — the other half of the pair
- *  above, and the one that defaults TRUE (only `readable: false` withdraws it,
- *  marking a write-only edge). */
-export declare function edgeIsReadable(edge: EdgeSchema): boolean;
-/** Every WRITABLE edge an instance offers, for diagnostics: the spellings a
- *  write can land on (`channel-[:messages]->`, `message-[:replies]->`). Keys
- *  off the one explicit `writable` promise (layer 13). */
-export declare function writableEdgesOf(schema: InstanceSchema): Array<{
-    parent: string;
-    edge: string;
-    target: string;
-}>;
 /**
  * Canonical key into `InstanceSchema.refinements`: the hop's target type plus
  * the WHERE that selects the position. Shared by the checker (looking
@@ -1559,3 +1150,94 @@ export declare function mockCatalog(spec: {
     constructionArgOptions?: Catalog['constructionArgOptions'];
     models?: readonly string[];
 }): Catalog;
+/**
+ * A row a DECLARATION states, for a function whose body the checker cannot
+ * walk — a plugin, an adapter's field function, a remote callee. The inferred
+ * row's twin: same five facts, written down instead of derived, and folded into
+ * a caller by exactly the same `absorb`.
+ *
+ * `reads`/`writes` name synthetic sources in the words an author would read
+ * ("the web"). They are not instances: a declaration is written once, in the
+ * registry, and cannot know which graphs the movement that calls it constructed.
+ *
+ * There is no `partial` here. A declaration is a CLAIM — it says what the
+ * function does, completely. Not declaring one at all is the lower bound, and
+ * that is the absence of this object, not a field inside it.
+ */
+export interface DeclaredEffectRow {
+    readonly reads?: readonly string[];
+    readonly writes?: readonly string[];
+    readonly ai?: boolean;
+    readonly now?: boolean;
+    readonly suspend?: boolean;
+}
+/** The prefix that marks an edge the ENGINE makes rather than one a system
+ *  declares. Reserved in every version: the host leaves an adapter edge so
+ *  named out of its projection, with a note, so the two can never collide. */
+export declare const ARTIFICIAL_EDGE_PREFIX = "@";
+export declare function isArtificialEdge(edge: string): boolean;
+/**
+ * The EVENT NAME a key was minted from — the inverse of `eventAddressKey`'s
+ * event half, and it lives HERE so the key stays opaque to everyone else. Its
+ * consumers only ever compare it; the moment one of them pulled the name out
+ * itself, the key would be a magic string that is PARSED rather than compared.
+ *
+ * This exists because the engine stamps an event position's `recordType` with
+ * the key, and any name resolution scoped by type then has to ask which type
+ * that is. An UNPINNED key already IS the event name, which is why adapters
+ * whose events pin nothing (Granola, an unnarrowed Attio event) resolve
+ * correctly by COINCIDENCE — and why Airtable, which always pins base and
+ * table, never did.
+ *
+ * A string this module did not mint is returned unchanged: it is an ordinary
+ * type name, and saying so is the honest answer.
+ */
+export declare function eventAddressEventName(key: string): string;
+/**
+ * What an adapter SURFACE can declare — every field type except a record,
+ * nested collections included.
+ *
+ * A record is a place in a graph, and no adapter field is one: a record type
+ * arises only where the checker types an EXPRESSION. Saying so here is what
+ * keeps a schema clear of the position model — and a schema crosses the wire
+ * (`InstanceSchema` is a tRPC response), where a field type that reached into
+ * positions would reach back into schemas again, a cycle no serialiser's type
+ * can follow.
+ *
+ * The collections are spelled a second time because TypeScript cannot subtract
+ * a member from a RECURSIVE union — `Exclude` removes the record at the top
+ * and leaves `list of record` behind, which is the same cycle. The scalars and
+ * every rule about them live on `FieldType` above; this is that union with one
+ * member gone, and every `SchemaFieldType` IS a `FieldType`, so nothing that
+ * reads a schema needs to know which it was handed.
+ */
+export type SchemaFieldType = 'text' | 'number' | 'boolean' | 'date' | 'datetime' | 'file' | 'json' | 'absent' | 'never' | {
+    kind: 'list';
+    of: SchemaFieldType;
+    unordered?: true;
+} | {
+    kind: 'tuple';
+    of: Array<SchemaFieldType | null>;
+} | {
+    kind: 'dict';
+    of: SchemaFieldType;
+} | {
+    kind: 'enum';
+    options: string[];
+    open?: {
+        allowPattern?: string;
+    };
+} | {
+    kind: 'maybeAbsent';
+    of: SchemaFieldType;
+};
+/** `T | absent` over a surface type; a surface type in is a surface type out. */
+export declare function maybeAbsent(type: SchemaFieldType | undefined): SchemaFieldType | undefined;
+/** One adapter-declared interactive connect action — the declaration half
+ *  of the generalised "+" connect affordance. `kind` names an app-shipped
+ *  client handler; `label` is the suggestion text. The language stays pure:
+ *  it carries the declaration and never interprets `kind`. */
+export interface ConnectAction {
+    kind: string;
+    label: string;
+}