@onlyworlds/sdk 3.0.0 → 4.0.0-alpha.0

package/dist/index.d.ts

@@ -1,909 +1,428 @@
-/**
- * Modern branded types for type-safe element relationships
- * Provides compile-time safety while maintaining zero runtime overhead
- */
-declare const __brand: unique symbol;
-type Brand<B> = {
-    [__brand]: B;
-};
-/**
- * Branded type for element IDs - ensures type safety for relationships
- * @template T The element type this ID references
- */
-type ElementId<T extends ElementType$1> = string & Brand<T>;
-/**
- * Branded type for arrays of element IDs
- * @template T The element type these IDs reference
- */
-type ElementIds<T extends ElementType$1> = ElementId<T>[];
-/**
- * Special type for IDs that can reference ANY element type
- * Used in cases like Pin.element_type where the target can be any OnlyWorlds element
- */
-type AnyElementId = ElementId<ElementType$1>;
-/**
- * Base fields shared by all OnlyWorlds elements
- */
-interface BaseElement {
-    id?: string;
+/** Every element carries these. The extension index signature admits namespaced
+ *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server. */
+interface OwElementBase {
+    /** Element type slug (server-managed, read-only). */
+    type: string;
+    /** Unique identifier, uuidv7 format. */
+    id: string;
+    /** Name of the element. */
     name: string;
+    /** Any kind of details about the element. */
     description?: string;
-    image_url?: string;
+    /** The top level category to which the element belongs. */
     supertype?: string;
+    /** The sub level category through which the element is further classified. */
     subtype?: string;
-    world?: string;
-    created_at?: string;
-    updated_at?: string;
-}
-/**
- * World element type
- */
-interface World {
-    id?: string;
-    api_key: string;
-    name: string;
-    description?: string;
-    version?: string;
+    /** URL to an image representing the element. */
     image_url?: string;
-    time_format_equivalents?: any[];
-    time_format_names?: any[];
-    time_basic_unit?: string;
-    time_range_min?: number;
-    time_range_max?: number;
-    time_current?: number;
-    user?: string;
+    /** Creation timestamp (server-managed, read-only). */
     created_at?: string;
+    /** Last-update timestamp (server-managed, read-only). */
     updated_at?: string;
+    /** Per-world change cursor, stamped on every write (server-managed, read-only). */
+    change_seq?: number;
+    /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
+    [ext: string]: unknown;
 }
-/**
- * World input type for creation/updates
- */
-interface WorldInput {
+type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
+declare const ELEMENT_TYPES: ElementType[];
+/** The four semantic families (colour carries the family; ELEMENT_ICONS carries the type). */
+type ElementFamily = 'agents' | 'world' | 'abstract' | 'temporal';
+/** Per-type semantic family. Source: keel's PRESENTATION-WRAPPER schema key `family:`
+ *  (first-party rendering metadata, keel-only — NOT part of the council-governed
+ *  OnlyWorlds standard; see keel/schema-pipeline.md "The wrapper layer"). */
+declare const ELEMENT_FAMILIES: Record<ElementType, ElementFamily>;
+/** Material Symbols icon name per type. Source: keel's PRESENTATION-WRAPPER key `icon:` (keel 56c124a). */
+declare const ELEMENT_ICONS: Record<ElementType, string>;
+/** Field grouping for display. DERIVED from the canonical schema's own document
+ *  structure (top-level property groups, document order = display order). */
+interface SectionInfo {
     name: string;
-    description?: string;
-    version?: string;
-    image_url?: string;
-    time_format_equivalents?: any[];
-    time_format_names?: any[];
-    time_basic_unit?: string;
-    time_range_min?: number;
-    time_range_max?: number;
-    time_current?: number;
-}
-/**
- * Ability element type
- * Fields organized by sections: Mechanics, World
- */
-interface Ability extends BaseElement {
-    activation?: string;
-    duration?: number;
-    potency?: number;
-    range?: number;
-    effects?: ElementIds<ElementType$1.Phenomenon>;
-    challenges?: string;
-    talents?: ElementIds<ElementType$1.Trait>;
-    requisites?: ElementIds<ElementType$1.Construct>;
-    prevalence?: string;
-    tradition?: ElementId<ElementType$1.Construct>;
-    source?: ElementId<ElementType$1.Phenomenon>;
-    locus?: ElementId<ElementType$1.Location>;
-    instruments?: ElementIds<ElementType$1.Object>;
-    systems?: ElementIds<ElementType$1.Construct>;
-}
-/**
- * Object element type
- * Fields organized by sections: Form, Function, World
- */
-interface Object$1 extends BaseElement {
-    aesthetics?: string;
-    weight?: number;
-    amount?: number;
-    parent_object?: ElementId<ElementType$1.Object>;
-    materials?: ElementIds<ElementType$1.Construct>;
-    technology?: ElementIds<ElementType$1.Construct>;
-    utility?: string;
-    effects?: ElementIds<ElementType$1.Phenomenon>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    consumes?: ElementIds<ElementType$1.Construct>;
-    origins?: string;
-    location?: ElementId<ElementType$1.Location>;
-    language?: ElementId<ElementType$1.Language>;
-    affinities?: ElementIds<ElementType$1.Trait>;
-}
-/**
- * Character element type
- * Fields organized by sections: Constitution, Origins, World, Personality, Social, TTRPG
- */
-interface Character extends BaseElement {
-    physicality?: string;
-    mentality?: string;
-    height?: number;
-    weight?: number;
-    species?: ElementIds<ElementType$1.Species>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    background?: string;
-    motivations?: string;
-    birth_date?: number;
-    birthplace?: ElementId<ElementType$1.Location>;
-    languages?: ElementIds<ElementType$1.Language>;
-    reputation?: string;
-    location?: ElementId<ElementType$1.Location>;
-    objects?: ElementIds<ElementType$1.Object>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    charisma?: number;
-    coercion?: number;
-    competence?: number;
-    compassion?: number;
-    creativity?: number;
-    courage?: number;
-    family?: ElementIds<ElementType$1.Family>;
-    friends?: ElementIds<ElementType$1.Character>;
-    rivals?: ElementIds<ElementType$1.Character>;
-    level?: number;
-    hit_points?: number;
-    STR?: number;
-    DEX?: number;
-    CON?: number;
-    INT?: number;
-    WIS?: number;
-    CHA?: number;
-}
-/**
- * Collective element type
- * Fields organized by sections: Formation, Dynamics, World
- */
-interface Collective extends BaseElement {
-    composition?: string;
-    count?: number;
-    formation_date?: number;
-    operator?: ElementId<ElementType$1.Institution>;
-    equipment?: ElementIds<ElementType$1.Construct>;
-    activity?: string;
-    disposition?: string;
-    state?: string;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    symbolism?: ElementIds<ElementType$1.Construct>;
-    species?: ElementIds<ElementType$1.Species>;
-    characters?: ElementIds<ElementType$1.Character>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-}
-/**
- * Construct element type
- * Fields organized by sections: Nature, Involves
- */
-interface Construct extends BaseElement {
-    rationale?: string;
-    history?: string;
-    status?: string;
-    reach?: string;
-    start_date?: number;
-    end_date?: number;
-    founder?: ElementId<ElementType$1.Character>;
-    custodian?: ElementId<ElementType$1.Institution>;
-    characters?: ElementIds<ElementType$1.Character>;
-    objects?: ElementIds<ElementType$1.Object>;
-    locations?: ElementIds<ElementType$1.Location>;
-    species?: ElementIds<ElementType$1.Species>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    collectives?: ElementIds<ElementType$1.Collective>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    languages?: ElementIds<ElementType$1.Language>;
-    families?: ElementIds<ElementType$1.Family>;
-    relations?: ElementIds<ElementType$1.Relation>;
-    titles?: ElementIds<ElementType$1.Title>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-    events?: ElementIds<ElementType$1.Event>;
-    narratives?: ElementIds<ElementType$1.Narrative>;
-}
-/**
- * Creature element type
- * Fields organized by sections: Biology, Behaviour, World, TTRPG
- */
-interface Creature extends BaseElement {
-    appearance?: string;
-    weight?: number;
-    height?: number;
-    species?: ElementIds<ElementType$1.Species>;
-    habits?: string;
-    demeanor?: string;
-    traits?: ElementIds<ElementType$1.Trait>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    languages?: ElementIds<ElementType$1.Language>;
-    status?: string;
-    birth_date?: number;
-    location?: ElementId<ElementType$1.Location>;
-    zone?: ElementId<ElementType$1.Zone>;
-    challenge_rating?: number;
-    hit_points?: number;
-    armor_class?: number;
-    speed?: number;
-    actions?: ElementIds<ElementType$1.Ability>;
-}
-/**
- * Event element type
- * Fields organized by sections: Nature, Involves
- */
-interface Event extends BaseElement {
-    history?: string;
-    challenges?: string;
-    consequences?: string;
-    start_date?: number;
-    end_date?: number;
-    triggers?: ElementIds<ElementType$1.Event>;
-    characters?: ElementIds<ElementType$1.Character>;
-    objects?: ElementIds<ElementType$1.Object>;
-    locations?: ElementIds<ElementType$1.Location>;
-    species?: ElementIds<ElementType$1.Species>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    collectives?: ElementIds<ElementType$1.Collective>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    languages?: ElementIds<ElementType$1.Language>;
-    families?: ElementIds<ElementType$1.Family>;
-    relations?: ElementIds<ElementType$1.Relation>;
-    titles?: ElementIds<ElementType$1.Title>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-}
-/**
- * Family element type
- * Fields organized by sections: Identity, World
- */
-interface Family extends BaseElement {
-    spirit?: string;
-    history?: string;
-    traditions?: ElementIds<ElementType$1.Construct>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    languages?: ElementIds<ElementType$1.Language>;
-    ancestors?: ElementIds<ElementType$1.Character>;
-    reputation?: string;
-    estates?: ElementIds<ElementType$1.Location>;
-    governs?: ElementIds<ElementType$1.Institution>;
-    heirlooms?: ElementIds<ElementType$1.Object>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-}
-/**
- * Institution element type
- * Fields organized by sections: Foundation, Claims, World
- */
-interface Institution extends BaseElement {
-    doctrine?: string;
-    founding_date?: number;
-    parent_institution?: ElementId<ElementType$1.Institution>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    objects?: ElementIds<ElementType$1.Object>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    status?: string;
-    allies?: ElementIds<ElementType$1.Institution>;
-    adversaries?: ElementIds<ElementType$1.Institution>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-}
-/**
- * Language element type
- * Fields organized by sections: Structure, World
- */
-interface Language extends BaseElement {
-    phonology?: string;
-    grammar?: string;
-    lexicon?: string;
-    writing?: string;
-    classification?: ElementId<ElementType$1.Construct>;
-    status?: string;
-    spread?: ElementIds<ElementType$1.Location>;
-    dialects?: ElementIds<ElementType$1.Language>;
-}
-/**
- * Law element type
- * Fields organized by sections: Code, World
- */
-interface Law extends BaseElement {
-    declaration?: string;
-    purpose?: string;
-    date?: number;
-    parent_law?: ElementId<ElementType$1.Law>;
-    penalties?: ElementIds<ElementType$1.Construct>;
-    author?: ElementId<ElementType$1.Institution>;
-    locations?: ElementIds<ElementType$1.Location>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    prohibitions?: ElementIds<ElementType$1.Construct>;
-    adjudicators?: ElementIds<ElementType$1.Title>;
-    enforcers?: ElementIds<ElementType$1.Title>;
-}
-/**
- * Location element type
- * Fields organized by sections: Setting, Politics, World, Production, Commerce, Construction, Defense
- */
-interface Location extends BaseElement {
-    form?: string;
-    function?: string;
-    founding_date?: number;
-    parent_location?: ElementId<ElementType$1.Location>;
-    populations?: ElementIds<ElementType$1.Collective>;
-    political_climate?: string;
-    primary_power?: ElementId<ElementType$1.Institution>;
-    governing_title?: ElementId<ElementType$1.Title>;
-    secondary_powers?: ElementIds<ElementType$1.Institution>;
-    zone?: ElementId<ElementType$1.Zone>;
-    rival?: ElementId<ElementType$1.Location>;
-    partner?: ElementId<ElementType$1.Location>;
-    customs?: string;
-    founders?: ElementIds<ElementType$1.Character>;
-    cults?: ElementIds<ElementType$1.Construct>;
-    delicacies?: ElementIds<ElementType$1.Species>;
-    extraction_methods?: ElementIds<ElementType$1.Construct>;
-    extraction_goods?: ElementIds<ElementType$1.Construct>;
-    industry_methods?: ElementIds<ElementType$1.Construct>;
-    industry_goods?: ElementIds<ElementType$1.Construct>;
-    infrastructure?: string;
-    extraction_markets?: ElementIds<ElementType$1.Location>;
-    industry_markets?: ElementIds<ElementType$1.Location>;
-    currencies?: ElementIds<ElementType$1.Construct>;
-    architecture?: string;
-    buildings?: ElementIds<ElementType$1.Object>;
-    building_methods?: ElementIds<ElementType$1.Construct>;
-    defensibility?: string;
-    elevation?: number;
-    fighters?: ElementIds<ElementType$1.Construct>;
-    defensive_objects?: ElementIds<ElementType$1.Object>;
+    order: number;
+    fields: string[];
 }
+declare const ELEMENT_SECTIONS: Record<ElementType, SectionInfo[]>;
+
 /**
- * Phenomenon element type
- * Fields organized by sections: Mechanics, World
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
+ * (envelopes, pages, bulk, changes, config). Per-type element field typing is
+ * generated (types.generated.ts). One-shape principle: a field reads the way it
+ * writes -- links are UUID arrays (or UUID/null), same name both directions.
+ * No `_ids` suffix in v2.
  */
-interface Phenomenon extends BaseElement {
-    expression?: string;
-    effects?: string;
-    duration?: number;
-    catalysts?: ElementIds<ElementType$1.Object>;
-    empowerments?: ElementIds<ElementType$1.Ability>;
-    mythology?: string;
-    system?: ElementId<ElementType$1.Phenomenon>;
-    triggers?: ElementIds<ElementType$1.Construct>;
-    wielders?: ElementIds<ElementType$1.Character>;
-    environments?: ElementIds<ElementType$1.Location>;
+
+/** An element as read from / written to the v2 API. Loose base + extension keys. */
+type OwElement = OwElementBase;
+/** Spatial types live under spatial/ in the OW Folder Format. */
+declare const SPATIAL_TYPES: readonly ElementType[];
+interface OwWorldMeta {
+    id: string;
+    name: string;
+    updated_at?: string;
+    public_read?: boolean;
+    [field: string]: unknown;
 }
-/**
- * Relation element type
- * Fields organized by sections: Nature, Involves
- */
-interface Relation extends BaseElement {
-    background?: string;
-    start_date?: number;
-    end_date?: number;
-    intensity?: number;
-    actor?: ElementId<ElementType$1.Character>;
-    events?: ElementIds<ElementType$1.Event>;
-    characters?: ElementIds<ElementType$1.Character>;
-    objects?: ElementIds<ElementType$1.Object>;
-    locations?: ElementIds<ElementType$1.Location>;
-    species?: ElementIds<ElementType$1.Species>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    collectives?: ElementIds<ElementType$1.Collective>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    languages?: ElementIds<ElementType$1.Language>;
-    families?: ElementIds<ElementType$1.Family>;
-    titles?: ElementIds<ElementType$1.Title>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-    narratives?: ElementIds<ElementType$1.Narrative>;
+/** List envelope: cursor-paginated. */
+interface OwPage<T = OwElement> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
 }
+/** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
+type OwChange = {
+    op: 'upsert';
+    id: string;
+    type: string;
+    element: OwElement;
+    updated_at: string;
+    [k: string]: unknown;
+} | {
+    op: 'delete';
+    id: string;
+    type: string;
+    deleted_at: string;
+    [k: string]: unknown;
+};
 /**
- * Species element type
- * Fields organized by sections: Biology, Psychology, World
+ * /changes response. Wire shape verified in keel source (core/changes.py) and
+ * pinned here: {cursor, changes, has_more, head}.
  */
-interface Species extends BaseElement {
-    appearance?: string;
-    life_span?: number;
-    weight?: number;
-    nourishment?: ElementIds<ElementType$1.Species>;
-    reproduction?: ElementIds<ElementType$1.Construct>;
-    adaptations?: ElementIds<ElementType$1.Ability>;
-    instincts?: string;
-    sociality?: string;
-    temperament?: string;
-    communication?: string;
-    aggression?: number;
-    traits?: ElementIds<ElementType$1.Trait>;
-    role?: string;
-    parent_species?: ElementId<ElementType$1.Species>;
-    locations?: ElementIds<ElementType$1.Location>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    affinities?: ElementIds<ElementType$1.Phenomenon>;
+interface OwChangesPage {
+    /** Opaque compound cursor -- persist verbatim, never parse, never expires. */
+    cursor: string;
+    changes: OwChange[];
+    has_more: boolean;
+    /**
+     * World's current change_seq. If a persisted cursor is ever AHEAD of head,
+     * the server rewound (disaster restore) -- re-baseline from cursor zero
+     * instead of assuming caught-up.
+     */
+    head: number;
 }
-/**
- * Zone element type
- * Fields organized by sections: Scope, World
- */
-interface Zone extends BaseElement {
-    role?: string;
-    start_date?: number;
-    end_date?: number;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    linked_zones?: ElementIds<ElementType$1.Zone>;
-    context?: string;
-    populations?: ElementIds<ElementType$1.Collective>;
-    titles?: ElementIds<ElementType$1.Title>;
-    principles?: ElementIds<ElementType$1.Construct>;
+interface OwBulkItem {
+    type: ElementType | string;
+    element: OwElement | Record<string, unknown>;
 }
 /**
- * Title element type
- * Fields organized by sections: Mandate, World
+ * One slot of a /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): `status` is
+ * the NUMERIC HTTP status of that slot (201/400/...), success slots echo
+ * created_at/updated_at, error slots carry an OwErrorBody under `error`.
  */
-interface Title extends BaseElement {
-    authority?: string;
-    eligibility?: string;
-    grant_date?: number;
-    revoke_date?: number;
-    issuer?: ElementId<ElementType$1.Institution>;
-    body?: ElementId<ElementType$1.Institution>;
-    superior_title?: ElementId<ElementType$1.Title>;
-    holders?: ElementIds<ElementType$1.Character>;
-    symbols?: ElementIds<ElementType$1.Object>;
-    status?: string;
-    history?: string;
-    characters?: ElementIds<ElementType$1.Character>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    families?: ElementIds<ElementType$1.Family>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    locations?: ElementIds<ElementType$1.Location>;
-    objects?: ElementIds<ElementType$1.Object>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-    laws?: ElementIds<ElementType$1.Law>;
-    collectives?: ElementIds<ElementType$1.Collective>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    species?: ElementIds<ElementType$1.Species>;
-    languages?: ElementIds<ElementType$1.Language>;
+interface OwBulkItemResult {
+    status: number;
+    id?: string;
+    created_at?: string;
+    updated_at?: string;
+    error?: OwErrorBody;
 }
-/**
- * Trait element type
- * Fields organized by sections: Qualitative, Quantitative, World
- */
-interface Trait extends BaseElement {
-    social_effects?: string;
-    physical_effects?: string;
-    functional_effects?: string;
-    personality_effects?: string;
-    behaviour_effects?: string;
-    charisma?: number;
-    coercion?: number;
-    competence?: number;
-    compassion?: number;
-    creativity?: number;
-    courage?: number;
-    significance?: string;
-    anti_trait?: ElementId<ElementType$1.Trait>;
-    empowered_abilities?: ElementIds<ElementType$1.Ability>;
+/** The wire error envelope carried in error slots and thrown errors. */
+interface OwErrorBody {
+    type?: string;
+    code?: string;
+    message?: string;
+    param?: string | null;
+    doc_url?: string;
 }
 /**
- * Narrative element type
- * Fields organized by sections: Context, Involves
+ * /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): the array key is `items`,
+ * not `results`. `wasReplay` is populated by the client from the (lowercase on
+ * the wire) Idempotent-Replay response header (fixture P2b) -- not a wire field.
  */
-interface Narrative extends BaseElement {
-    story?: string;
-    consequences?: string;
-    start_date?: number;
-    end_date?: number;
-    order?: number;
-    parent_narrative?: ElementId<ElementType$1.Narrative>;
-    protagonist?: ElementId<ElementType$1.Character>;
-    antagonist?: ElementId<ElementType$1.Character>;
-    narrator?: ElementId<ElementType$1.Character>;
-    conservator?: ElementId<ElementType$1.Institution>;
-    events?: ElementIds<ElementType$1.Event>;
-    characters?: ElementIds<ElementType$1.Character>;
-    objects?: ElementIds<ElementType$1.Object>;
-    locations?: ElementIds<ElementType$1.Location>;
-    species?: ElementIds<ElementType$1.Species>;
-    creatures?: ElementIds<ElementType$1.Creature>;
-    institutions?: ElementIds<ElementType$1.Institution>;
-    traits?: ElementIds<ElementType$1.Trait>;
-    collectives?: ElementIds<ElementType$1.Collective>;
-    zones?: ElementIds<ElementType$1.Zone>;
-    abilities?: ElementIds<ElementType$1.Ability>;
-    phenomena?: ElementIds<ElementType$1.Phenomenon>;
-    languages?: ElementIds<ElementType$1.Language>;
-    families?: ElementIds<ElementType$1.Family>;
-    relations?: ElementIds<ElementType$1.Relation>;
-    titles?: ElementIds<ElementType$1.Title>;
-    constructs?: ElementIds<ElementType$1.Construct>;
-    laws?: ElementIds<ElementType$1.Law>;
+interface OwBulkResponse {
+    errors: boolean;
+    items: OwBulkItemResult[];
+    /** Client-derived: true when the server replayed a prior Idempotency-Key. */
+    wasReplay?: boolean;
+    [k: string]: unknown;
 }
-/**
- * Map element type
- * Fields organized by sections: Details
- */
-interface Map extends BaseElement {
-    background_color?: string;
-    hierarchy?: number;
-    width?: number;
-    height?: number;
-    depth?: number;
-    parent_map?: ElementId<ElementType$1.Map>;
-    location?: ElementId<ElementType$1.Location>;
+interface OwLinkEdit {
+    add?: string[];
+    remove?: string[];
 }
-/**
- * Marker element type
- * Fields organized by sections: Details
- */
-interface Marker extends BaseElement {
-    map?: ElementId<ElementType$1.Map>;
-    zone?: ElementId<ElementType$1.Zone>;
-    x?: number;
-    y?: number;
-    z?: number;
-    order?: number;
+interface ListParams {
+    limit?: number;
+    cursor?: string;
+    /** One-level stub expansion, e.g. ['friends', 'location']. */
+    expand?: string[];
+    /** Sparse include-set of field names. */
+    fields?: string[];
+    /**
+     * Blessed Django-style filters: __icontains, __in, __gte, __lte, __isnull,
+     * supertype/subtype equality. Unknown params 422 loudly server-side -- the
+     * client passes them through and lets the platform name the typo.
+     */
+    filter?: Record<string, string | number | boolean>;
 }
-/**
- * Pin element type
- * Fields organized by sections: Details
- */
-interface Pin extends BaseElement {
-    map?: ElementId<ElementType$1.Map>;
-    element_type?: ElementType$1;
-    element_id?: AnyElementId;
+interface OwClientConfig {
+    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 10-digit legacy key. */
+    apiKey: string;
     /**
-     * X coordinate on map (must be integer)
-     * The API requires integer values. Float coordinates from mouse events
-     * or calculations should be rounded: Math.round(x)
+     * Optional. Required for writes when the world has a PIN, and for legacy-key
+     * reads of private worlds. Prefixed keys read PIN-less. String, not number --
+     * '0123' !== 123.
      */
-    x?: number;
+    apiPin?: string;
+    /** Default: https://www.onlyworlds.com/api/v2 */
+    baseUrl?: string;
     /**
-     * Y coordinate on map (must be integer)
-     * The API requires integer values. Float coordinates from mouse events
-     * or calculations should be rounded: Math.round(y)
+     * Page size for element lists. Default 100 (server default; max 1000).
+     * Deliberately visible in config: page size is a citizenship property.
      */
-    y?: number;
+    pageSize?: number;
     /**
-     * Z coordinate for 3D positioning (must be integer)
-     * The API requires integer values. Float coordinates should be rounded: Math.round(z)
+     * Page size for /changes pulls. Default 100. Live precedents: Obsidian 100,
+     * Atlas 250, MCP 25. /changes is the platform's heaviest route -- be polite.
      */
-    z?: number;
+    changesPageSize?: number;
+    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
 }
+
 /**
- * Input types for API requests
- * Use field names without _id/_ids suffix - prepareRelations() handles conversion
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * keel error envelope handling. The error contract is part of the contract:
+ * envelopes carry a machine `code` and a `doc_url` fragment anchored at
+ * onlyworlds.github.io/api/errors -- surface both, always. The live wire
+ * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
+ * surfaced on the thrown error.
  */
-interface AbilityInput extends Omit<Ability, 'tradition' | 'source' | 'locus' | 'effects' | 'talents' | 'requisites' | 'instruments' | 'systems'> {
-    tradition?: string;
-    source?: string;
-    locus?: string;
-    effects?: string[];
-    talents?: string[];
-    requisites?: string[];
-    instruments?: string[];
-    systems?: string[];
-}
-interface ObjectInput extends Omit<Object$1, 'parent_object' | 'location' | 'language' | 'materials' | 'technology' | 'effects' | 'abilities' | 'consumes' | 'affinities'> {
-    parent_object?: string;
-    location?: string;
-    language?: string;
-    materials?: string[];
-    technology?: string[];
-    effects?: string[];
-    abilities?: string[];
-    consumes?: string[];
-    affinities?: string[];
-}
-interface CharacterInput extends Omit<Character, 'birthplace' | 'location' | 'species' | 'traits' | 'abilities' | 'languages' | 'objects' | 'institutions' | 'family' | 'friends' | 'rivals'> {
-    birthplace?: string;
-    location?: string;
-    species?: string[];
-    traits?: string[];
-    abilities?: string[];
-    languages?: string[];
-    objects?: string[];
-    institutions?: string[];
-    family?: string[];
-    friends?: string[];
-    rivals?: string[];
-}
-interface CollectiveInput extends Omit<Collective, 'operator' | 'equipment' | 'abilities' | 'symbolism' | 'species' | 'characters' | 'creatures' | 'phenomena'> {
-    operator?: string;
-    equipment?: string[];
-    abilities?: string[];
-    symbolism?: string[];
-    species?: string[];
-    characters?: string[];
-    creatures?: string[];
-    phenomena?: string[];
-}
-interface ConstructInput extends Omit<Construct, 'founder' | 'custodian' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs' | 'events' | 'narratives'> {
-    founder?: string;
-    custodian?: string;
-    characters?: string[];
-    objects?: string[];
-    locations?: string[];
-    species?: string[];
-    creatures?: string[];
-    institutions?: string[];
-    traits?: string[];
-    collectives?: string[];
-    zones?: string[];
-    abilities?: string[];
-    phenomena?: string[];
-    languages?: string[];
-    families?: string[];
-    relations?: string[];
-    titles?: string[];
-    constructs?: string[];
-    events?: string[];
-    narratives?: string[];
-}
-interface CreatureInput extends Omit<Creature, 'location' | 'zone' | 'species' | 'traits' | 'abilities' | 'languages' | 'actions'> {
-    location?: string;
-    zone?: string;
-    species?: string[];
-    traits?: string[];
-    abilities?: string[];
-    languages?: string[];
-    actions?: string[];
-}
-interface EventInput extends Omit<Event, 'triggers' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs'> {
-    triggers?: string[];
-    characters?: string[];
-    objects?: string[];
-    locations?: string[];
-    species?: string[];
-    creatures?: string[];
-    institutions?: string[];
-    traits?: string[];
-    collectives?: string[];
-    zones?: string[];
-    abilities?: string[];
-    phenomena?: string[];
-    languages?: string[];
-    families?: string[];
-    relations?: string[];
-    titles?: string[];
-    constructs?: string[];
-}
-interface FamilyInput extends Omit<Family, 'traditions' | 'traits' | 'abilities' | 'languages' | 'ancestors' | 'estates' | 'governs' | 'heirlooms' | 'creatures'> {
-    traditions?: string[];
-    traits?: string[];
-    abilities?: string[];
-    languages?: string[];
-    ancestors?: string[];
-    estates?: string[];
-    governs?: string[];
-    heirlooms?: string[];
-    creatures?: string[];
-}
-interface InstitutionInput extends Omit<Institution, 'parent_institution' | 'zones' | 'objects' | 'creatures' | 'allies' | 'adversaries' | 'constructs'> {
-    parent_institution?: string;
-    zones?: string[];
-    objects?: string[];
-    creatures?: string[];
-    allies?: string[];
-    adversaries?: string[];
-    constructs?: string[];
-}
-interface LanguageInput extends Omit<Language, 'classification' | 'spread' | 'dialects'> {
-    classification?: string;
-    spread?: string[];
-    dialects?: string[];
-}
-interface LawInput extends Omit<Law, 'parent_law' | 'author' | 'penalties' | 'locations' | 'zones' | 'prohibitions' | 'adjudicators' | 'enforcers'> {
-    parent_law?: string;
-    author?: string;
-    penalties?: string[];
-    locations?: string[];
-    zones?: string[];
-    prohibitions?: string[];
-    adjudicators?: string[];
-    enforcers?: string[];
-}
-interface LocationInput extends Omit<Location, 'parent_location' | 'primary_power' | 'governing_title' | 'zone' | 'rival' | 'partner' | 'populations' | 'secondary_powers' | 'founders' | 'cults' | 'delicacies' | 'extraction_methods' | 'extraction_goods' | 'industry_methods' | 'industry_goods' | 'extraction_markets' | 'industry_markets' | 'currencies' | 'buildings' | 'building_methods' | 'fighters' | 'defensive_objects'> {
-    parent_location?: string;
-    primary_power?: string;
-    governing_title?: string;
-    zone?: string;
-    rival?: string;
-    partner?: string;
-    populations?: string[];
-    secondary_powers?: string[];
-    founders?: string[];
-    cults?: string[];
-    delicacies?: string[];
-    extraction_methods?: string[];
-    extraction_goods?: string[];
-    industry_methods?: string[];
-    industry_goods?: string[];
-    extraction_markets?: string[];
-    industry_markets?: string[];
-    currencies?: string[];
-    buildings?: string[];
-    building_methods?: string[];
-    fighters?: string[];
-    defensive_objects?: string[];
-}
-interface PhenomenonInput extends Omit<Phenomenon, 'system' | 'catalysts' | 'empowerments' | 'triggers' | 'wielders' | 'environments'> {
-    system?: string;
-    catalysts?: string[];
-    empowerments?: string[];
-    triggers?: string[];
-    wielders?: string[];
-    environments?: string[];
-}
-interface RelationInput extends Omit<Relation, 'actor' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'titles' | 'constructs' | 'events' | 'narratives'> {
-    actor?: string;
-    characters?: string[];
-    objects?: string[];
-    locations?: string[];
-    species?: string[];
-    creatures?: string[];
-    institutions?: string[];
-    traits?: string[];
-    collectives?: string[];
-    zones?: string[];
-    abilities?: string[];
-    phenomena?: string[];
-    languages?: string[];
-    families?: string[];
-    titles?: string[];
-    constructs?: string[];
-    events?: string[];
-    narratives?: string[];
+/** Auth codes are distinguishable by design; client recovery UX differs per code. */
+type OwAuthErrorCode = 'invalid_credentials' | 'key_revoked' | 'world_gone';
+declare class OwApiError extends Error {
+    readonly status: number;
+    /** Machine error code from the keel envelope, e.g. 'invalid_credentials'. */
+    readonly code: string | null;
+    /** Error family from the envelope, e.g. 'invalid_request', 'not_found'. */
+    readonly type: string | null;
+    /** Offending field/param named by the envelope (422/400), else null. */
+    readonly param: string | null;
+    /** Documentation link from the envelope -- show it to users/logs verbatim. */
+    readonly docUrl: string | null;
+    /** Raw parsed envelope (or body text when the body wasn't JSON). */
+    readonly detail: unknown;
+    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null);
+    get isAuthError(): boolean;
+    /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
+    get isValidationError(): boolean;
+    /** Same Idempotency-Key replayed with a different payload. */
+    get isIdempotencyConflict(): boolean;
 }
-interface SpeciesInput extends Omit<Species, 'parent_species' | 'nourishment' | 'reproduction' | 'adaptations' | 'traits' | 'locations' | 'zones' | 'affinities'> {
-    parent_species?: string;
-    nourishment?: string[];
-    reproduction?: string[];
-    adaptations?: string[];
-    traits?: string[];
-    locations?: string[];
-    zones?: string[];
-    affinities?: string[];
-}
-interface ZoneInput extends Omit<Zone, 'phenomena' | 'linked_zones' | 'populations' | 'titles' | 'principles'> {
-    phenomena?: string[];
-    linked_zones?: string[];
-    populations?: string[];
-    titles?: string[];
-    principles?: string[];
-}
-interface TitleInput extends Omit<Title, 'issuer' | 'body' | 'superior_title' | 'holders' | 'symbols' | 'characters' | 'institutions' | 'families' | 'zones' | 'locations' | 'objects' | 'constructs' | 'laws' | 'collectives' | 'creatures' | 'phenomena' | 'species' | 'languages'> {
-    issuer?: string;
-    body?: string;
-    superior_title?: string;
-    holders?: string[];
-    symbols?: string[];
-    characters?: string[];
-    institutions?: string[];
-    families?: string[];
-    zones?: string[];
-    locations?: string[];
-    objects?: string[];
-    constructs?: string[];
-    laws?: string[];
-    collectives?: string[];
-    creatures?: string[];
-    phenomena?: string[];
-    species?: string[];
-    languages?: string[];
-}
-interface TraitInput extends Omit<Trait, 'anti_trait' | 'empowered_abilities'> {
-    anti_trait?: string;
-    empowered_abilities?: string[];
-}
-interface NarrativeInput extends Omit<Narrative, 'parent_narrative' | 'protagonist' | 'antagonist' | 'narrator' | 'conservator' | 'events' | 'characters' | 'objects' | 'locations' | 'species' | 'creatures' | 'institutions' | 'traits' | 'collectives' | 'zones' | 'abilities' | 'phenomena' | 'languages' | 'families' | 'relations' | 'titles' | 'constructs' | 'laws'> {
-    parent_narrative?: string;
-    protagonist?: string;
-    antagonist?: string;
-    narrator?: string;
-    conservator?: string;
-    events?: string[];
-    characters?: string[];
-    objects?: string[];
-    locations?: string[];
-    species?: string[];
-    creatures?: string[];
-    institutions?: string[];
-    traits?: string[];
-    collectives?: string[];
-    zones?: string[];
-    abilities?: string[];
-    phenomena?: string[];
-    languages?: string[];
-    families?: string[];
-    relations?: string[];
-    titles?: string[];
-    constructs?: string[];
-    laws?: string[];
-}
-interface MapInput extends Omit<Map, 'parent_map' | 'location'> {
-    parent_map?: string;
-    location?: string;
-}
-interface MarkerInput extends Omit<Marker, 'map' | 'zone'> {
-    map?: string;
-    zone?: string;
-}
-interface PinInput extends Omit<Pin, 'map' | 'element_id'> {
-    map?: string;
-    element_id?: string;
-}
-/**
- * All available element types in OnlyWorlds
- */
-declare enum ElementType$1 {
-    Ability = "ability",
-    Character = "character",
-    Collective = "collective",
-    Construct = "construct",
-    Creature = "creature",
-    Event = "event",
-    Family = "family",
-    Institution = "institution",
-    Language = "language",
-    Law = "law",
-    Location = "location",
-    Map = "map",
-    Marker = "marker",
-    Narrative = "narrative",
-    Object = "object",
-    Phenomenon = "phenomenon",
-    Pin = "pin",
-    Relation = "relation",
-    Species = "species",
-    Title = "title",
-    Trait = "trait",
-    Zone = "zone"
+/** Network-level failure (fetch rejected) -- no envelope to parse. */
+declare class OwNetworkError extends Error {
+    readonly cause2: unknown;
+    constructor(message: string, cause: unknown);
 }
+/** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
+declare function parseEnvelope(status: number, body: unknown): OwApiError;
+/** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
+declare function errorFromResponse(res: Response): Promise<OwApiError>;
+
 /**
- * UI labels for element types - provides proper plural forms
- * Useful for displaying element type names in user interfaces
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
+ * (Stripe/GitHub precedent) -- and tell a client what auth shape to expect.
  */
-declare const ELEMENT_LABELS: Record<ElementType$1, string>;
+type OwKeyKind = 
+/** ow_w_ -- world key, read + write. Writes need the world's PIN if it has one. */
+'write'
+/** ow_r_ -- world key, read-only, works bare (no PIN). The share-with-players primitive. */
+ | 'read'
+/** ow_a_ -- account Bearer token for /account/* routes; can mint world keys. */
+ | 'account'
+/** Grandfathered 10-digit key. Needs PIN to read private worlds. */
+ | 'legacy' | 'unknown';
+/** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
+declare function isDemoKey(key: string): boolean;
+declare function detectKeyKind(key: string): OwKeyKind;
+/** Can this key kind ever perform world writes? (PIN is a separate, per-world question.) */
+declare function kindCanWrite(kind: OwKeyKind): boolean;
 /**
- * Get the plural label for an element type
- * @param elementType The element type
- * @returns The plural label string
+ * Should a credential UI ask for a PIN with this key?
+ * Prefixed keys read PIN-less; legacy keys may need it; writes on pinned
+ * worlds always need it. 'optional' means: show the field, don't require it.
  */
-declare function getElementLabel(elementType: ElementType$1): string;
+declare function pinExpectation(kind: OwKeyKind): 'never' | 'optional' | 'required-for-private-reads';
+
 /**
- * Section metadata for OnlyWorlds elements
- * Source: sectioned_schema.json
+ * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
+ * wire-corrected against live staging fixtures 2026-07-18.
+ *
+ * OwV2Client -- thin typed fetch client for the keel v2 API.
+ *
+ * Deliberately thin: no caching, no sync state, no retry policy -- those belong
+ * to callers (sync engines, tools, games). What IS encoded here is the wire
+ * contract and its safety rails: payload read-only-field stripping, opaque
+ * cursors, idempotency headers, doc_url-bearing errors, polite page sizes, and
+ * client-side UUID minting so idempotent retries are structurally safe.
  */
-interface SectionInfo {
-    name: string;
-    order: number;
-    fields: string[];
+
+declare class OwV2Client {
+    readonly baseUrl: string;
+    readonly keyKind: OwKeyKind;
+    readonly pageSize: number;
+    readonly changesPageSize: number;
+    private readonly apiKey;
+    private readonly apiPin;
+    private readonly fetchImpl;
+    constructor(config: OwClientConfig);
+    /** GET /health -- unauthenticated liveness pulse. */
+    health(): Promise<unknown>;
+    /**
+     * GET /world -- world meta (name, calendar/time fields, public_read).
+     * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
+     * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
+     */
+    getWorld(): Promise<OwWorldMeta>;
+    /** PATCH /world -- partial world-meta update. */
+    patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
+    /** GET /{type}/ -- one cursor page. */
+    list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
+    /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
+    listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
+    /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
+    get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
+    /**
+     * POST /{type}/ -- create. Mints an RFC-4122 UUID for element.id when the
+     * caller omits one (design ruling D29d) so a retry carrying the same
+     * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
+     */
+    create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
+        idempotencyKey?: string;
+    }): Promise<OwElement>;
+    /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
+    upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
+    /**
+     * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
+     * replace wholesale, omitted fields stay untouched. For link arrays prefer
+     * editLinks() -- atomic server-side merge, no read-before-write.
+     */
+    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
+    /**
+     * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
+     * tombstone AND scrubs the id from every other element's links in the same
+     * transaction -- no client-side unlink pass needed, ever.
+     */
+    delete(type: ElementType | string, id: string): Promise<void>;
+    /**
+     * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
+     * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
+     * updated element (fixture P5). Use this for all relationship editing; it
+     * retires the read-merge-PATCH dance.
+     */
+    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
+    /**
+     * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
+     * always; inspect per-slot numeric `status` + top-level `errors` flag);
+     * atomic:true for all-or-nothing. Link validation runs against batch U
+     * database -- send in any order, cycles included; no client topo-sort.
+     * Success slots echo server-authoritative timestamps: set your sync baseline
+     * from this response alone. When an idempotencyKey is replayed, the returned
+     * response carries wasReplay:true (read from the Idempotent-Replay header).
+     */
+    bulk(items: OwBulkItem[], opts?: {
+        atomic?: boolean;
+        idempotencyKey?: string;
+    }): Promise<OwBulkResponse>;
+    /**
+     * GET /changes -- one page of the world's ordered change feed.
+     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
+     * Zero/absent cursor = full export (byte-aligned with the Folder Format).
+     * Rewind rule: if your persisted position is ahead of page.head, the server
+     * was restored -- re-baseline from cursor zero; do not assume caught-up.
+     * Citizenship: heaviest route on the platform; default page size is polite.
+     */
+    changes(opts?: {
+        since?: string;
+        limit?: number;
+    }): Promise<OwChangesPage>;
+    /**
+     * Walk the feed from `since` (or from zero = full export) to the current
+     * tail, yielding ops in order. Returns the final cursor via the generator's
+     * return value; persist it for the next incremental pull.
+     */
+    changesAll(since?: string): AsyncGenerator<OwChange, {
+        cursor: string;
+        head: number;
+    }>;
+    /**
+     * Raw authenticated request against this client's baseUrl. Public since 4.0
+     * so auxiliary resources can ride the same transport — it structurally
+     * satisfies `TokenTransport` (`new TokenResource(client)`). Prefer the typed
+     * methods for element CRUD; this is the escape hatch, and it does NOT apply
+     * sanitizePayload — callers own their body shape.
+     */
+    request<T = unknown>(method: string, path: string, opts?: {
+        query?: string;
+        body?: unknown;
+        idempotencyKey?: string;
+        auth?: boolean;
+        allowEmpty?: boolean;
+        replayAware?: boolean;
+    }): Promise<T>;
 }
+
 /**
- * Element section definitions - provides organized field groupings for each element type
- * Enables UI components to display fields in logical sections with proper ordering
+ * Canonical element colour palette — four semantic families.
+ *
+ * Ruled by Captain 2026-07-22 after Skeld's measurement pass (Orrery
+ * `product/schema/element-palette-measurements.md`): 22 mutually-separable
+ * hues is structurally impossible; four families is the ceiling that passes
+ * all-pairs CVD separation in both modes. **Colour carries the FAMILY; the
+ * icon (`ELEMENT_ICONS`) carries the TYPE.** Dark-mode pairs land in the 6–8
+ * CVD floor band, so secondary encoding (icon + label) is REQUIRED alongside
+ * colour, not optional.
+ *
+ * The type→family map is GENERATED: `ELEMENT_FAMILIES` is emitted by
+ * `codegen/generate_types.py` from the `family:` key in keel's schema YAML
+ * (added 2026-07-23, keel c69366b) — a keel PRESENTATION-WRAPPER key
+ * (first-party rendering metadata, not part of the council-governed
+ * OnlyWorlds standard). It cannot drift from the schema; membership and hex
+ * invariants stay test-gated in `test/palette.test.mjs`.
+ *
+ * The hexes below are design constants, hand-authored beside the generated
+ * map. Do not change any value without re-running the CVD validation (every
+ * brighter World green collides with Temporal amber for protan viewers — the
+ * green is pinned BY the accessibility budget).
+ *
+ * Provenance: first proven live in atlas (`src/core/element-colors.ts`) and
+ * council (`src/cosmos/element-families.ts`) — both become re-exports of this
+ * module.
  */
-declare const ELEMENT_SECTIONS: Record<ElementType$1, SectionInfo[]>;
+
 /**
- * Get sections for an element type
- * @param elementType The element type
- * @returns Array of section information for the element type
- */
-declare function getElementSections(elementType: ElementType$1): SectionInfo[];
+ * Family → validated hex per surface mode. `light` assumes near-white
+ * surfaces, `dark` assumes near-black (measured against #0a0a0a).
+ * World green is identical in both modes and sits at its low-contrast end
+ * deliberately — see module header before "fixing" it.
+ */
+declare const FAMILY_COLORS: Record<ElementFamily, {
+    light: string;
+    dark: string;
+}>;
+/** Semantic family for an element type slug. */
+declare function familyOf(type: ElementType): ElementFamily;
+/**
+ * The convenience most callers want: canonical colour for an element type.
+ * Name matches the live atlas/council implementations so their SDK swap is a
+ * re-export, not a rename. Defaults to `dark` (both current consumers are
+ * dark-surface).
+ */
+declare function elementColor(type: ElementType, mode?: 'light' | 'dark'): string;
+/** All four families, in ruling order (the order IS the CVD-safety mechanism of the source palette). */
+declare const FAMILY_ORDER: readonly ElementFamily[];
+
 /**
  * Current OnlyWorlds version
  * Synced with https://github.com/OnlyWorlds/OnlyWorlds/blob/main/VERSION
  */
 declare const ONLYWORLDS_VERSION: "00.30.00";
-/**
- * Material Design icons for element types
- * These are the uniform, monochrome icons used in the OnlyWorlds frontend
- * Compatible with Google Material Icons font
- */
-declare const ELEMENT_ICONS: Record<ElementType$1, string>;
 /**
  * Field type definitions for OnlyWorlds elements
  */
@@ -917,10 +436,7 @@ interface FieldInfo {
     max?: number;
     required?: boolean;
 }
-/**
- * Comprehensive field schema - provides complete metadata for all fields
- * Maps element types to their field definitions including types and cardinality
- */
+declare const ELEMENT_LABELS: Record<ElementType, string>;
 declare const FIELD_SCHEMA: {
     readonly ability: {
         readonly name: {
@@ -947,13 +463,13 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly duration: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly potency: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly range: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly effects: {
             readonly type: "multi_link";
@@ -1022,10 +538,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly height: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly weight: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly species: {
             readonly type: "multi_link";
@@ -1046,7 +562,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly birth_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly birthplace: {
             readonly type: "single_link";
@@ -1072,22 +588,22 @@ declare const FIELD_SCHEMA: {
             readonly target: "institution";
         };
         readonly charisma: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly coercion: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly competence: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly compassion: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly creativity: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly courage: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly family: {
             readonly type: "multi_link";
@@ -1102,28 +618,28 @@ declare const FIELD_SCHEMA: {
             readonly target: "character";
         };
         readonly level: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly hit_points: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly STR: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly DEX: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly CON: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly INT: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly WIS: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly CHA: {
-            readonly type: "number";
+            readonly type: "integer";
         };
     };
     readonly collective: {
@@ -1151,10 +667,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly count: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly formation_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly operator: {
             readonly type: "single_link";
@@ -1232,10 +748,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly start_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly end_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly founder: {
             readonly type: "single_link";
@@ -1343,10 +859,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly weight: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly height: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly species: {
             readonly type: "multi_link";
@@ -1374,7 +890,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly birth_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly location: {
             readonly type: "single_link";
@@ -1385,16 +901,16 @@ declare const FIELD_SCHEMA: {
             readonly target: "zone";
         };
         readonly challenge_rating: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly hit_points: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly armor_class: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly speed: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly actions: {
             readonly type: "multi_link";
@@ -1432,10 +948,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly start_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly end_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly triggers: {
             readonly type: "multi_link";
@@ -1598,7 +1114,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly founding_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_institution: {
             readonly type: "single_link";
@@ -1709,7 +1225,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_law: {
             readonly type: "single_link";
@@ -1772,7 +1288,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly founding_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_location: {
             readonly type: "single_link";
@@ -1870,7 +1386,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly elevation: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly fighters: {
             readonly type: "multi_link";
@@ -1906,16 +1422,16 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly hierarchy: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly width: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly height: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly depth: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_map: {
             readonly type: "single_link";
@@ -1958,18 +1474,18 @@ declare const FIELD_SCHEMA: {
             readonly required: true;
         };
         readonly x: {
-            readonly type: "number";
+            readonly type: "integer";
             readonly required: true;
         };
         readonly y: {
-            readonly type: "number";
+            readonly type: "integer";
             readonly required: true;
         };
         readonly z: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly order: {
-            readonly type: "number";
+            readonly type: "integer";
             readonly required: true;
         };
     };
@@ -2001,13 +1517,13 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly start_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly end_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly order: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_narrative: {
             readonly type: "single_link";
@@ -2127,10 +1643,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly weight: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly amount: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly parent_object: {
             readonly type: "single_link";
@@ -2203,7 +1719,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly duration: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly catalysts: {
             readonly type: "multi_link";
@@ -2269,15 +1785,15 @@ declare const FIELD_SCHEMA: {
             readonly required: true;
         };
         readonly x: {
-            readonly type: "number";
+            readonly type: "integer";
             readonly required: true;
         };
         readonly y: {
-            readonly type: "number";
+            readonly type: "integer";
             readonly required: true;
         };
         readonly z: {
-            readonly type: "number";
+            readonly type: "integer";
         };
     };
     readonly relation: {
@@ -2305,13 +1821,13 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly start_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly end_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly intensity: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly actor: {
             readonly type: "single_link";
@@ -2415,10 +1931,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly life_span: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly weight: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly nourishment: {
             readonly type: "multi_link";
@@ -2445,7 +1961,7 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly aggression: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly traits: {
             readonly type: "multi_link";
@@ -2499,10 +2015,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly grant_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly revoke_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly issuer: {
             readonly type: "single_link";
@@ -2620,22 +2136,22 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly charisma: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly coercion: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly competence: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly compassion: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly creativity: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly courage: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly significance: {
             readonly type: "text";
@@ -2674,10 +2190,10 @@ declare const FIELD_SCHEMA: {
             readonly type: "text";
         };
         readonly start_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly end_date: {
-            readonly type: "number";
+            readonly type: "integer";
         };
         readonly phenomena: {
             readonly type: "multi_link";
@@ -2705,23 +2221,15 @@ declare const FIELD_SCHEMA: {
     };
 };
 /**
- * Creates a typed element ID from a string
- * @param id The string ID to brand
- * @returns Branded ElementId
- */
-declare function createElementId<T extends ElementType$1>(id: string): ElementId<T>;
-/**
- * Creates typed element IDs array from string array
- * @param ids The string IDs to brand
- * @returns Branded ElementIds array
- */
-declare function createElementIds<T extends ElementType$1>(ids: string[]): ElementIds<T>;
-/**
- * Creates an AnyElementId that can reference any element type
- * @param id The string ID to brand
- * @returns AnyElementId
+ * Get Material Design icon name for an element type
+ * Accepts multiple formats: 'character', 'characters', 'Character', etc.
+ *
+ * @param type - Element type in any format (singular, plural, any case)
+ * @returns Material icon name (e.g., 'person', 'castle', 'thunderstorm')
  */
-declare function createAnyElementId(id: string): AnyElementId;
+declare function getElementIcon(type: string): string;
+/** Plural display label for an element type (e.g. phenomenon → "Phenomena"). */
+declare function getElementLabel(elementType: ElementType): string;
 
 /**
  * OnlyWorlds Token Management API Types
@@ -2843,6 +2351,17 @@ declare enum GameTier {
  * Provides access to the OnlyWorlds token rating system API.
  * Based on the working implementation in base-tool/src/llm/token-service.ts
  */
+/**
+ * Minimal transport the token resource needs — structurally satisfied by
+ * `OwV2Client` (its `request()` is public since 4.0): `new TokenResource(client)`.
+ * Wire ruling (Skeld 2026-07-23): keel keeps the /tokens/* economy long-term
+ * (Tangle ratings write it, Council voting reads it) — port, don't delete.
+ */
+interface TokenTransport {
+    request<T>(method: string, path: string, opts?: {
+        body?: unknown;
+    }): Promise<T>;
+}
 
 /**
  * Token Management Resource
@@ -2870,7 +2389,7 @@ declare enum GameTier {
  */
 declare class TokenResource {
     private client;
-    constructor(client: OnlyWorldsClient);
+    constructor(client: TokenTransport);
     /**
      * Get current token status for authenticated user
      *
@@ -2989,473 +2508,4 @@ declare class TokenResource {
     getEncryptionInfo(): Promise<EncryptionInfo>;
 }
 
-interface OnlyWorldsConfig {
-    apiKey: string;
-    apiPin: string;
-    baseUrl?: string;
-}
-interface ListOptions {
-    limit?: number;
-    offset?: number;
-    ordering?: string;
-    search?: string;
-    [key: string]: any;
-}
-interface ApiResponse<T> {
-    count: number;
-    next: string | null;
-    previous: string | null;
-    results: T[];
-}
-/**
- * Base resource class for CRUD operations
- */
-declare class Resource<T, TInput> {
-    private client;
-    private elementType;
-    constructor(client: OnlyWorldsClient, elementType: string);
-    list(options?: ListOptions): Promise<ApiResponse<T>>;
-    get(id: string): Promise<T>;
-    create(data: TInput): Promise<T>;
-    update(id: string, data: Partial<TInput>): Promise<T>;
-    delete(id: string): Promise<void>;
-    /**
-     * Round Pin coordinates to integers (API requirement)
-     * @private
-     */
-    private roundPinCoordinates;
-}
-/**
- * Special resource class for World endpoint
- * The /world/ endpoint returns a single World object directly (not paginated)
- * because API keys are world-scoped (one key = one world)
- */
-declare class WorldResource {
-    private client;
-    constructor(client: OnlyWorldsClient);
-    /**
-     * Get the world associated with the current API key
-     * Returns the world directly (not wrapped in pagination)
-     */
-    get(): Promise<World>;
-    /**
-     * Update the current world
-     */
-    update(data: Partial<WorldInput>): Promise<World>;
-}
-/**
- * Main OnlyWorlds API client
- */
-declare class OnlyWorldsClient {
-    private baseUrl;
-    private headers;
-    worlds: WorldResource;
-    tokens: TokenResource;
-    abilities: Resource<Ability, AbilityInput>;
-    characters: Resource<Character, CharacterInput>;
-    collectives: Resource<Collective, CollectiveInput>;
-    constructs: Resource<Construct, ConstructInput>;
-    creatures: Resource<Creature, CreatureInput>;
-    events: Resource<Event, EventInput>;
-    families: Resource<Family, FamilyInput>;
-    institutions: Resource<Institution, InstitutionInput>;
-    languages: Resource<Language, LanguageInput>;
-    laws: Resource<Law, LawInput>;
-    locations: Resource<Location, LocationInput>;
-    maps: Resource<Map, MapInput>;
-    markers: Resource<Marker, MarkerInput>;
-    narratives: Resource<Narrative, NarrativeInput>;
-    objects: Resource<Object$1, ObjectInput>;
-    phenomena: Resource<Phenomenon, PhenomenonInput>;
-    pins: Resource<Pin, PinInput>;
-    relations: Resource<Relation, RelationInput>;
-    species: Resource<Species, SpeciesInput>;
-    titles: Resource<Title, TitleInput>;
-    traits: Resource<Trait, TraitInput>;
-    zones: Resource<Zone, ZoneInput>;
-    constructor(config: OnlyWorldsConfig);
-    /**
-     * Make a request to the OnlyWorlds API
-     */
-    request<T>(method: string, path: string, options?: {
-        params?: Record<string, any>;
-        body?: any;
-    }): Promise<T>;
-    /**
-     * Helper to convert nested objects to _id/_ids format (legacy method)
-     * @deprecated Use prepareRelations instead - it's called automatically in create/update
-     */
-    static prepareInput<T extends Record<string, any>>(data: T): any;
-    /**
-     * Convert relation fields to API format (_id/_ids suffix)
-     *
-     * The OnlyWorlds API expects:
-     * - single_link fields: fieldname_id (e.g., birthplace_id)
-     * - multi_link fields: fieldname_ids (e.g., species_ids)
-     *
-     * This method auto-converts based on FIELD_SCHEMA:
-     * - { species: ["id1", "id2"] } → { species_ids: ["id1", "id2"] }
-     * - { birthplace: "location-id" } → { birthplace_id: "location-id" }
-     * - { species: [{id: "id1", name: "X"}] } → { species_ids: ["id1"] }
-     *
-     * Called automatically by create() and update() methods.
-     */
-    static prepareRelations<T extends Record<string, any>>(data: T, elementType: string): any;
-}
-
-/**
- * Get Material Design icon name for an element type
- * Accepts multiple formats: 'character', 'characters', 'Character', etc.
- *
- * @param type - Element type in any format (singular, plural, any case)
- * @returns Material icon name (e.g., 'person', 'castle', 'thunderstorm')
- *
- * @example
- * getElementIcon('character')   // 'person'
- * getElementIcon('characters')  // 'person'
- * getElementIcon('Character')   // 'person'
- * getElementIcon('phenomena')   // 'thunderstorm'
- */
-declare function getElementIcon(type: string): string;
-
-/** Every element carries these. The extension index signature admits namespaced
- *  pass-through fields (atlas_* / shadow_* / x_*) returned verbatim by the server. */
-interface OwElementBase {
-    /** Element type slug (server-managed, read-only). */
-    type: string;
-    /** Unique identifier, uuidv7 format. */
-    id: string;
-    /** Name of the element. */
-    name: string;
-    /** Any kind of details about the element. */
-    description?: string;
-    /** The top level category to which the element belongs. */
-    supertype?: string;
-    /** The sub level category through which the element is further classified. */
-    subtype?: string;
-    /** URL to an image representing the element. */
-    image_url?: string;
-    /** Creation timestamp (server-managed, read-only). */
-    created_at?: string;
-    /** Last-update timestamp (server-managed, read-only). */
-    updated_at?: string;
-    /** Per-world change cursor, stamped on every write (server-managed, read-only). */
-    change_seq?: number;
-    /** Namespaced extension fields (atlas_* / shadow_* / x_*), returned verbatim. */
-    [ext: string]: unknown;
-}
-type ElementType = 'ability' | 'character' | 'collective' | 'construct' | 'creature' | 'event' | 'family' | 'institution' | 'language' | 'law' | 'location' | 'map' | 'marker' | 'narrative' | 'object' | 'phenomenon' | 'pin' | 'relation' | 'species' | 'title' | 'trait' | 'zone';
-declare const ELEMENT_TYPES: ElementType[];
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OnlyWorlds v2 (keel) wire types -- the NON-generated, hand-owned wire shapes
- * (envelopes, pages, bulk, changes, config). Per-type element field typing is
- * generated (types.generated.ts). One-shape principle: a field reads the way it
- * writes -- links are UUID arrays (or UUID/null), same name both directions.
- * No `_ids` suffix in v2.
- */
-
-/** An element as read from / written to the v2 API. Loose base + extension keys. */
-type OwElement = OwElementBase;
-/** Spatial types live under spatial/ in the OW Folder Format. */
-declare const SPATIAL_TYPES: readonly ElementType[];
-interface OwWorldMeta {
-    id: string;
-    name: string;
-    updated_at?: string;
-    public_read?: boolean;
-    [field: string]: unknown;
-}
-/** List envelope: cursor-paginated. */
-interface OwPage<T = OwElement> {
-    data: T[];
-    has_more: boolean;
-    next_cursor: string | null;
-}
-/** /changes feed -- discriminated union on `op`. Apply in order -> convergence. */
-type OwChange = {
-    op: 'upsert';
-    id: string;
-    type: string;
-    element: OwElement;
-    updated_at: string;
-    [k: string]: unknown;
-} | {
-    op: 'delete';
-    id: string;
-    type: string;
-    deleted_at: string;
-    [k: string]: unknown;
-};
-/**
- * /changes response. Wire shape verified in keel source (core/changes.py) and
- * pinned here: {cursor, changes, has_more, head}.
- */
-interface OwChangesPage {
-    /** Opaque compound cursor -- persist verbatim, never parse, never expires. */
-    cursor: string;
-    changes: OwChange[];
-    has_more: boolean;
-    /**
-     * World's current change_seq. If a persisted cursor is ever AHEAD of head,
-     * the server rewound (disaster restore) -- re-baseline from cursor zero
-     * instead of assuming caught-up.
-     */
-    head: number;
-}
-interface OwBulkItem {
-    type: ElementType | string;
-    element: OwElement | Record<string, unknown>;
-}
-/**
- * One slot of a /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): `status` is
- * the NUMERIC HTTP status of that slot (201/400/...), success slots echo
- * created_at/updated_at, error slots carry an OwErrorBody under `error`.
- */
-interface OwBulkItemResult {
-    status: number;
-    id?: string;
-    created_at?: string;
-    updated_at?: string;
-    error?: OwErrorBody;
-}
-/** The wire error envelope carried in error slots and thrown errors. */
-interface OwErrorBody {
-    type?: string;
-    code?: string;
-    message?: string;
-    param?: string | null;
-    doc_url?: string;
-}
-/**
- * /bulk response. WIRE-CORRECTED (fixtures P2a/P2c): the array key is `items`,
- * not `results`. `wasReplay` is populated by the client from the (lowercase on
- * the wire) Idempotent-Replay response header (fixture P2b) -- not a wire field.
- */
-interface OwBulkResponse {
-    errors: boolean;
-    items: OwBulkItemResult[];
-    /** Client-derived: true when the server replayed a prior Idempotency-Key. */
-    wasReplay?: boolean;
-    [k: string]: unknown;
-}
-interface OwLinkEdit {
-    add?: string[];
-    remove?: string[];
-}
-interface ListParams {
-    limit?: number;
-    cursor?: string;
-    /** One-level stub expansion, e.g. ['friends', 'location']. */
-    expand?: string[];
-    /** Sparse include-set of field names. */
-    fields?: string[];
-    /**
-     * Blessed Django-style filters: __icontains, __in, __gte, __lte, __isnull,
-     * supertype/subtype equality. Unknown params 422 loudly server-side -- the
-     * client passes them through and lets the platform name the typo.
-     */
-    filter?: Record<string, string | number | boolean>;
-}
-interface OwClientConfig {
-    /** ow_w_ / ow_r_ / ow_a_ prefixed key, or grandfathered 10-digit legacy key. */
-    apiKey: string;
-    /**
-     * Optional. Required for writes when the world has a PIN, and for legacy-key
-     * reads of private worlds. Prefixed keys read PIN-less. String, not number --
-     * '0123' !== 123.
-     */
-    apiPin?: string;
-    /** Default: https://www.onlyworlds.com/api/v2 */
-    baseUrl?: string;
-    /**
-     * Page size for element lists. Default 100 (server default; max 1000).
-     * Deliberately visible in config: page size is a citizenship property.
-     */
-    pageSize?: number;
-    /**
-     * Page size for /changes pulls. Default 100. Live precedents: Obsidian 100,
-     * Atlas 250, MCP 25. /changes is the platform's heaviest route -- be polite.
-     */
-    changesPageSize?: number;
-    /** Injectable for tests / fake-keel harnesses. Defaults to globalThis.fetch. */
-    fetch?: typeof globalThis.fetch;
-}
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * keel error envelope handling. The error contract is part of the contract:
- * envelopes carry a machine `code` and a `doc_url` fragment anchored at
- * onlyworlds.github.io/api/errors -- surface both, always. The live wire
- * envelope also carries `type` and `param` (fixtures P4a/P2c); both are
- * surfaced on the thrown error.
- */
-/** Auth codes are distinguishable by design; client recovery UX differs per code. */
-type OwAuthErrorCode = 'invalid_credentials' | 'key_revoked' | 'world_gone';
-declare class OwApiError extends Error {
-    readonly status: number;
-    /** Machine error code from the keel envelope, e.g. 'invalid_credentials'. */
-    readonly code: string | null;
-    /** Error family from the envelope, e.g. 'invalid_request', 'not_found'. */
-    readonly type: string | null;
-    /** Offending field/param named by the envelope (422/400), else null. */
-    readonly param: string | null;
-    /** Documentation link from the envelope -- show it to users/logs verbatim. */
-    readonly docUrl: string | null;
-    /** Raw parsed envelope (or body text when the body wasn't JSON). */
-    readonly detail: unknown;
-    constructor(status: number, code: string | null, message: string, docUrl: string | null, detail: unknown, type?: string | null, param?: string | null);
-    get isAuthError(): boolean;
-    /** 422s/400s name the offending param/field -- typos error loudly platform-wide. */
-    get isValidationError(): boolean;
-    /** Same Idempotency-Key replayed with a different payload. */
-    get isIdempotencyConflict(): boolean;
-}
-/** Network-level failure (fetch rejected) -- no envelope to parse. */
-declare class OwNetworkError extends Error {
-    readonly cause2: unknown;
-    constructor(message: string, cause: unknown);
-}
-/** Parse a wire envelope into OwApiError parts (exported for the error type-tests). */
-declare function parseEnvelope(status: number, body: unknown): OwApiError;
-/** Build an OwApiError from a non-2xx response, tolerating non-JSON bodies. */
-declare function errorFromResponse(res: Response): Promise<OwApiError>;
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OnlyWorlds key-kind detection. Prefixes make leaked keys grep-scannable
- * (Stripe/GitHub precedent) -- and tell a client what auth shape to expect.
- */
-type OwKeyKind = 
-/** ow_w_ -- world key, read + write. Writes need the world's PIN if it has one. */
-'write'
-/** ow_r_ -- world key, read-only, works bare (no PIN). The share-with-players primitive. */
- | 'read'
-/** ow_a_ -- account Bearer token for /account/* routes; can mint world keys. */
- | 'account'
-/** Grandfathered 10-digit key. Needs PIN to read private worlds. */
- | 'legacy' | 'unknown';
-/** Demo range 0000000000-0000000009: read-only aliases, safe as live read gates. */
-declare function isDemoKey(key: string): boolean;
-declare function detectKeyKind(key: string): OwKeyKind;
-/** Can this key kind ever perform world writes? (PIN is a separate, per-world question.) */
-declare function kindCanWrite(kind: OwKeyKind): boolean;
-/**
- * Should a credential UI ask for a PIN with this key?
- * Prefixed keys read PIN-less; legacy keys may need it; writes on pinned
- * worlds always need it. 'optional' means: show the field, don't require it.
- */
-declare function pinExpectation(kind: OwKeyKind): 'never' | 'optional' | 'required-for-private-reads';
-
-/**
- * keel v2 engine absorbed from Assembly's ow-v2-client v0.9.0 (Kael),
- * wire-corrected against live staging fixtures 2026-07-18.
- *
- * OwV2Client -- thin typed fetch client for the keel v2 API.
- *
- * Deliberately thin: no caching, no sync state, no retry policy -- those belong
- * to callers (sync engines, tools, games). What IS encoded here is the wire
- * contract and its safety rails: payload read-only-field stripping, opaque
- * cursors, idempotency headers, doc_url-bearing errors, polite page sizes, and
- * client-side UUID minting so idempotent retries are structurally safe.
- */
-
-declare class OwV2Client {
-    readonly baseUrl: string;
-    readonly keyKind: OwKeyKind;
-    readonly pageSize: number;
-    readonly changesPageSize: number;
-    private readonly apiKey;
-    private readonly apiPin;
-    private readonly fetchImpl;
-    constructor(config: OwClientConfig);
-    /** GET /health -- unauthenticated liveness pulse. */
-    health(): Promise<unknown>;
-    /**
-     * GET /world -- world meta (name, calendar/time fields, public_read).
-     * GOTCHA (by server design): world-meta edits do NOT appear in /changes and
-     * do not bump change_seq. Poll getWorld().updated_at for meta freshness.
-     */
-    getWorld(): Promise<OwWorldMeta>;
-    /** PATCH /world -- partial world-meta update. */
-    patchWorld(partial: Record<string, unknown>): Promise<OwWorldMeta>;
-    /** GET /{type}/ -- one cursor page. */
-    list(type: ElementType | string, params?: ListParams): Promise<OwPage>;
-    /** Cursor-walk every page of a type. Politeness: uses config pageSize. */
-    listAll(type: ElementType | string, params?: Omit<ListParams, 'cursor'>): AsyncGenerator<OwElement>;
-    /** GET /{type}/{id}/ -- optional one-level stub expansion / sparse fields. */
-    get(type: ElementType | string, id: string, opts?: Pick<ListParams, 'expand' | 'fields'>): Promise<OwElement>;
-    /**
-     * POST /{type}/ -- create. Mints an RFC-4122 UUID for element.id when the
-     * caller omits one (design ruling D29d) so a retry carrying the same
-     * Idempotency-Key is structurally safe. Callers MAY still supply their own id.
-     */
-    create(type: ElementType | string, element: OwElement | Record<string, unknown>, opts?: {
-        idempotencyKey?: string;
-    }): Promise<OwElement>;
-    /** PUT /{type}/{id}/ -- upsert-by-client-id. The local-first write primitive. */
-    upsert(type: ElementType | string, id: string, element: OwElement | Record<string, unknown>): Promise<OwElement>;
-    /**
-     * PATCH /{type}/{id}/ -- partial update. DESTRUCTIVE on sent fields: arrays
-     * replace wholesale, omitted fields stay untouched. For link arrays prefer
-     * editLinks() -- atomic server-side merge, no read-before-write.
-     */
-    patch(type: ElementType | string, id: string, partial: Record<string, unknown>): Promise<OwElement>;
-    /**
-     * DELETE /{type}/{id}/ -- idempotent (204 on absent). Server writes a
-     * tombstone AND scrubs the id from every other element's links in the same
-     * transaction -- no client-side unlink pass needed, ever.
-     */
-    delete(type: ElementType | string, id: string): Promise<void>;
-    /**
-     * POST /{type}/{id}/links/{field} with {add, remove} -- atomic link merge.
-     * Dedupes, tolerates already-present/already-absent ids. Returns the FULL
-     * updated element (fixture P5). Use this for all relationship editing; it
-     * retires the read-merge-PATCH dance.
-     */
-    editLinks(type: ElementType | string, id: string, field: string, edit: OwLinkEdit): Promise<OwElement>;
-    /**
-     * POST /bulk -- up to ~1000 items. Partial success by default (HTTP 200
-     * always; inspect per-slot numeric `status` + top-level `errors` flag);
-     * atomic:true for all-or-nothing. Link validation runs against batch U
-     * database -- send in any order, cycles included; no client topo-sort.
-     * Success slots echo server-authoritative timestamps: set your sync baseline
-     * from this response alone. When an idempotencyKey is replayed, the returned
-     * response carries wasReplay:true (read from the Idempotent-Replay header).
-     */
-    bulk(items: OwBulkItem[], opts?: {
-        atomic?: boolean;
-        idempotencyKey?: string;
-    }): Promise<OwBulkResponse>;
-    /**
-     * GET /changes -- one page of the world's ordered change feed.
-     * Cursor is OPAQUE and never expires: persist verbatim, never parse.
-     * Zero/absent cursor = full export (byte-aligned with the Folder Format).
-     * Rewind rule: if your persisted position is ahead of page.head, the server
-     * was restored -- re-baseline from cursor zero; do not assume caught-up.
-     * Citizenship: heaviest route on the platform; default page size is polite.
-     */
-    changes(opts?: {
-        since?: string;
-        limit?: number;
-    }): Promise<OwChangesPage>;
-    /**
-     * Walk the feed from `since` (or from zero = full export) to the current
-     * tail, yielding ops in order. Returns the final cursor via the generator's
-     * return value; persist it for the next incremental pull.
-     */
-    changesAll(since?: string): AsyncGenerator<OwChange, {
-        cursor: string;
-        head: number;
-    }>;
-    private request;
-}
-
-export { type Ability, type AbilityInput, type AccessKeyResponse, type AnyElementId, type ApiResponse, type BaseElement, type Character, type CharacterInput, type Collective, type CollectiveInput, type Construct, type ConstructInput, type Creature, type CreatureInput, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementId, type ElementIds, ElementType$1 as ElementType, type EncryptionInfo, type Event, type EventInput, FIELD_SCHEMA, type Family, type FamilyInput, type FieldInfo, type FieldType, GameTier, type Institution, type InstitutionInput, type Language, type LanguageInput, type Law, type LawInput, type ListOptions, type ListParams, type Location, type LocationInput, type Map, type MapInput, type Marker, type MarkerInput, type Narrative, type NarrativeInput, ONLYWORLDS_VERSION, type Object$1 as Object, type ObjectInput, OnlyWorldsClient, type OnlyWorldsConfig, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type Phenomenon, type PhenomenonInput, type Pin, type PinInput, type Relation, type RelationInput, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type Species, type SpeciesInput, type Title, type TitleInput, type TokenConsumeParams, type TokenConsumeResponse, type TokenStatus, type Trait, type TraitInput, type ElementType as V2ElementType, type World, type WorldInput, type Zone, type ZoneInput, createAnyElementId, createElementId, createElementIds, detectKeyKind, errorFromResponse, getElementIcon, getElementLabel, getElementSections, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };
+export { type AccessKeyResponse, ELEMENT_FAMILIES, ELEMENT_ICONS, ELEMENT_LABELS, ELEMENT_SECTIONS, ELEMENT_TYPES, type ElementFamily, type ElementType, type EncryptionInfo, FAMILY_COLORS, FAMILY_ORDER, FIELD_SCHEMA, type FieldInfo, type FieldType, GameTier, type ListParams, ONLYWORLDS_VERSION, OwApiError, type OwAuthErrorCode, type OwBulkItem, type OwBulkItemResult, type OwBulkResponse, type OwChange, type OwChangesPage, type OwClientConfig, type OwElement, type OwElementBase, type OwErrorBody, type OwKeyKind, type OwLinkEdit, OwNetworkError, type OwPage, OwV2Client, type OwWorldMeta, type RevokeAllSessionsResponse, type RevokeSessionResponse, SPATIAL_TYPES, type SectionInfo, type TokenConsumeParams, type TokenConsumeResponse, TokenResource, type TokenStatus, type TokenTransport, detectKeyKind, elementColor, errorFromResponse, familyOf, getElementIcon, getElementLabel, isDemoKey, kindCanWrite, parseEnvelope, pinExpectation };