@pwfabric/runtime 0.0.0-stage → 1.0.0-rc.1

package/dist/connectors/declared-connector.js

@@ -0,0 +1,333 @@
+/**
+ * build an engine from its DECLARATION.
+ *
+ * A REST engine is not a class. A class has a call signature, and a
+ * hand-written engine that takes one options object where the runtime passes
+ * two positional arguments ends up asking SharePoint for `lists/undefined`.
+ * A declaration has no signature to get wrong.
+ *
+ * WHAT THIS MODULE IS ALLOWED TO KNOW: how to turn seven declared facts into
+ * an `HttpEntityConnector`. It must not know a vendor's name, and the
+ * placement test measures exactly that — no provider name anywhere in
+ * `packages/runtime`. Everything SharePoint-shaped lives in the declaration,
+ * which lives in the pack that ships the connector.
+ *
+ * WHAT THE BASE DOES NOT LEARN. `entityPathMapper` and `responseMapper` stay
+ * plain functions on `HttpConnectorConfig`; this builds them. The pre-flight —
+ * Graph cannot address a list before its site id is resolved — is handled by
+ * constructing ONE base per resolved binding, so the mapper stays synchronous.
+ * Making it asynchronous would teach a shared contract one vendor's
+ * addressing dance.
+ *
+ * @module @pwfabric/runtime/connectors/declared-connector
+ */
+import { HttpEntityConnector } from '../entity/http-connector.js';
+import { applyEntityQuery } from '../entity/apply-query.js';
+// ============================================================
+// VALUE TRANSFORMS — a CLOSED registry
+// ============================================================
+/**
+ * The only value transforms a declaration may name.
+ *
+ * CLOSED ON PURPOSE. A declaration carries a NAME, never a function — the
+ * moment it could carry a function it would be a class again with extra steps,
+ * and an AI-written declaration would regain the power to get something wrong.
+ * An unknown name throws at construction (see `resolveTransform`) rather than
+ * passing values through unchanged, because a silently skipped transform looks
+ * exactly like a field the source never sent.
+ *
+ * These two are named for what they DO, not for who needs them: the runtime
+ * must not learn a vendor's name.
+ */
+export const VALUE_TRANSFORMS = {
+    /**
+     * A field whose value is a JSON STRING describing a hosted file becomes the
+     * absolute URL. Image/Thumbnail-typed columns serialise this way and a
+     * consumer binding it into an `image` block needs a real URL.
+     */
+    'hosted-file-url': (value) => {
+        if (typeof value !== 'string' || !value.startsWith('{'))
+            return value;
+        try {
+            const parsed = JSON.parse(value);
+            return parsed.serverUrl && parsed.serverRelativeUrl
+                ? `${parsed.serverUrl}${parsed.serverRelativeUrl}`
+                : value;
+        }
+        catch {
+            return value;
+        }
+    },
+    /**
+     * A numeric string becomes a number. Form data yields strings only, while
+     * lookup-style columns are typed numeric by the API.
+     */
+    'numeric-string': (value) => typeof value === 'string' && value !== '' && !Number.isNaN(Number(value)) ? Number(value) : value,
+};
+function resolveTransform(use) {
+    const fn = VALUE_TRANSFORMS[use];
+    if (!fn) {
+        throw new Error(`engine declaration names an unknown transform "${use}" — known: ${Object.keys(VALUE_TRANSFORMS).join(', ')}`);
+    }
+    return fn;
+}
+// ============================================================
+// TEMPLATE
+// ============================================================
+/** `{name}` substitution. An unbound placeholder is left visible, not blanked. */
+function fill(template, bindings) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => bindings[key] ?? whole);
+}
+function readPath(source, path) {
+    return path.split('.').reduce((acc, key) => {
+        if (acc && typeof acc === 'object')
+            return acc[key];
+        return undefined;
+    }, source);
+}
+// ============================================================
+// THE ORIGIN — https, except an explicit http:// on loopback
+// ============================================================
+/** Hosts a declaration may reach over plain `http://`: the machine itself. */
+function isLoopbackHost(hostname) {
+    const h = hostname.toLowerCase();
+    return h === 'localhost' || h === '127.0.0.1' || h === '[::1]' || h.endsWith('.localhost');
+}
+/**
+ * The origin a filled declared host resolves to.
+ *
+ * - no scheme or `https://` → `https://<host>` (unchanged since the first release);
+ * - `http://` on a loopback host (`localhost`, `127.0.0.1`, `[::1]`,
+ *   `*.localhost`) → kept as `http://<host>`, so a development server is reachable;
+ * - `http://` anywhere else → `https://<host>`, as every release before
+ *   this one did. It is never downgraded (the visitor's token must not cross
+ *   the network in clear text), and published apps whose connection holds an
+ *   `http://` address keep working the way they always have.
+ */
+function declaredOrigin(filledHost) {
+    const plain = /^http:\/\//i.exec(filledHost);
+    if (!plain)
+        return { origin: `https://${filledHost.replace(/^https?:\/\//i, '')}` };
+    const rest = filledHost.slice(plain[0].length);
+    let hostname = '';
+    try {
+        hostname = new URL(`http://${rest}`).hostname;
+    }
+    catch {
+        hostname = '';
+    }
+    if (hostname && isLoopbackHost(hostname))
+        return { origin: `http://${rest}` };
+    return { origin: `https://${rest}` };
+}
+export function createDeclaredConnector(options) {
+    const { name, declaration: d, config, getAccessToken } = options;
+    // Fail at construction, not at the first read: a declaration naming a
+    // transform nobody implements is broken whether or not anyone calls it.
+    const transforms = (d.transforms ?? []).map((t) => ({ field: t.field, fn: resolveTransform(t.use) }));
+    const stringConfig = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (typeof v === 'string')
+            stringConfig[k] = v;
+    }
+    /**
+     * THE HOST IS A TEMPLATE — the one substitution a user-owned API cannot do
+     * without, and the one this function used to compute before the config it
+     * would have drawn on even existed.
+     *
+     * `graph.microsoft.com/v1.0` is a constant because Graph is one address for
+     * everyone. A connection to the user's OWN API has no constant to state: the
+     * address IS the thing the user supplies. `host: "{baseUrl}"` is how they
+     * supply it, and the scheme is stripped after filling so a pasted
+     * `https://api.example.com` and a bare `api.example.com` mean the same thing.
+     *
+     * An explicit `http://` survives ONLY for a loopback host — a development
+     * server on `http://127.0.0.1:8787` is otherwise unreachable. Anywhere else
+     * `http://` is upgraded to https, as before: see {@link declaredOrigin}.
+     */
+    const declared = declaredOrigin(fill(d.host, stringConfig));
+    const origin = declared.origin;
+    /**
+     * THE READ PATHS ARE TEMPLATES TOO — and that is what makes a generic REST
+     * connection declarable rather than compiled.
+     *
+     * If `fill` reached only `resolve.path` and `path`, the RESPONSE SHAPE would
+     * have to be hardcoded into the declaration: an API answering `{data:[…]}`
+     * and one answering `{results:[…]}` would need two different atoms. Two
+     * atoms that differ only in a string is code wearing a manifest, and the
+     * declared-engine design's whole claim is that "a new API is a connection
+     * record rather than code".
+     *
+     * `fill` on a string carrying no `{name}` returns that string, so a
+     * declaration without templates behaves as a literal one. `graph-lists`
+     * is the proof and has a test that says so.
+     */
+    const readItems = fill(d.read.items, stringConfig);
+    const readId = fill(d.read.id, stringConfig);
+    const readFlatten = d.read.flatten === undefined ? undefined : fill(d.read.flatten, stringConfig);
+    const authHeaders = async () => {
+        if (d.auth.type !== 'bearer')
+            return {};
+        const token = await getAccessToken();
+        return token ? { Authorization: `Bearer ${token}` } : {};
+    };
+    /** Pre-flight, memoised per template result — the site id and its kin. */
+    const bindings = new Map();
+    function resolveBindings(extra) {
+        const base = { ...stringConfig, ...extra };
+        if (!d.resolve)
+            return Promise.resolve(base);
+        const url = origin + fill(d.resolve.path, base);
+        let pending = bindings.get(url);
+        if (!pending) {
+            pending = authHeaders()
+                .then((headers) => fetch(url, { headers }))
+                .then((res) => res.json())
+                .then((body) => {
+                const value = readPath(body, d.resolve.field);
+                if (typeof value !== 'string') {
+                    throw new Error(`engine pre-flight ${url} carried no "${d.resolve.field}"`);
+                }
+                return { ...base, [d.resolve.as]: value };
+            })
+                .catch((err) => {
+                bindings.delete(url);
+                throw err;
+            });
+            bindings.set(url, pending);
+        }
+        return pending;
+    }
+    function applyTransforms(row) {
+        if (transforms.length === 0)
+            return row;
+        const out = { ...row };
+        for (const { field, fn } of transforms) {
+            if (field in out)
+                out[field] = fn(out[field]);
+        }
+        return out;
+    }
+    function mapRow(raw) {
+        const item = (raw ?? {});
+        const row = { id: readPath(item, readId) };
+        for (const key of d.read.lift ?? []) {
+            const v = readPath(item, key);
+            if (v !== undefined)
+                row[key] = v;
+        }
+        /**
+         * `flatten: "*"` means THE ITEM ITSELF IS THE BAG.
+         *
+         * `mapRow` starts from `{ id }` and only grows when `flatten` names a
+         * nested bag. Graph's bag is `fields`; flat REST has no bag because the
+         * item is already the row — so without this a plain REST read produced
+         * rows carrying nothing but `id`, and the panels rendered empty for a
+         * reason no warning named.
+         *
+         * `"*"` is spelled out rather than inferred from an absent `flatten`:
+         * inferring it would silently change what every existing declaration
+         * means, and a fallback nobody declared is how this family of bugs got
+         * here. It is also not a valid `readPath`, so it can never collide with a
+         * real path. The schema is untouched — it already accepts any non-empty
+         * string, so contracts stay frozen.
+         */
+        const bag = readFlatten === '*' ? item : readFlatten ? readPath(item, readFlatten) : undefined;
+        if (bag && typeof bag === 'object')
+            Object.assign(row, bag);
+        return applyTransforms(row);
+    }
+    /** One base per resolved binding set — the site is already inside baseUrl. */
+    const bases = new Map();
+    function baseFor(extra) {
+        const key = JSON.stringify(extra);
+        let pending = bases.get(key);
+        if (!pending) {
+            pending = resolveBindings(extra)
+                .then((bound) => new HttpEntityConnector(name, {
+                baseUrl: origin,
+                // Synchronous: every binding is already resolved into the string.
+                entityPathMapper: (entityType) => fill(d.path, { ...bound, entityType: String(entityType) }),
+                ...(d.params ? { defaultQueryParams: d.params } : {}),
+                // `none` means no credential at all: the visitor's token must never reach
+                // a host that did not ask for it, so no auth config is passed.
+                ...(d.auth.type === 'none' ? {} : { auth: { type: d.auth.type, token: getAccessToken } }),
+                responseMapper: (raw) => {
+                    const items = readPath(raw, readItems);
+                    return { items: Array.isArray(items) ? items.map(mapRow) : [] };
+                },
+            }))
+                .catch((err) => {
+                bases.delete(key);
+                throw err;
+            });
+            bases.set(key, pending);
+        }
+        return pending;
+    }
+    /** A query may name its own binding overrides (e.g. a different site). */
+    function overridesFrom(query) {
+        const out = {};
+        for (const [k, v] of Object.entries((query ?? {}))) {
+            if (typeof v === 'string' && k in stringConfig)
+                out[k] = v;
+        }
+        return out;
+    }
+    return {
+        name,
+        type: 'custom',
+        async query(entityType, query) {
+            try {
+                const base = await baseFor(overridesFrom(query));
+                // A declared engine talks to a FOREIGN API. The base connector would
+                // serialise the surface's query as the platform's own wire params —
+                // `filter=<json>&sort=&limit=&offset=` — which mean nothing there:
+                // Microsoft Graph answers 400 to any list read carrying `filter=`
+                // (sort-only reads happen to pass, so half the pages would be live and
+                // half fallback). Fetch with the declaration's own params only and apply the query
+                // here, where every declared engine speaks the same query language.
+                const res = await base.query(entityType, {});
+                if (!res.success)
+                    return res;
+                return { success: true, result: applyEntityQuery(res.result.items, query) };
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : 'engine query failed' };
+            }
+        },
+        async read(entityType, instanceId) {
+            const result = await this.query(entityType, {});
+            if (!result.success)
+                return { success: false, error: result.error };
+            const match = result.result.items.find((i) => i.id === instanceId);
+            return match ? { success: true, data: match } : { success: false, error: 'Not found' };
+        },
+        async create(entityType, data) {
+            try {
+                const base = await baseFor({});
+                // The wrap belongs to the LAYER: the base posts whatever it is handed,
+                // and the declaration says what shape to hand it.
+                const body = d.write?.bodyWrap ? { [d.write.bodyWrap]: applyTransforms(data) } : applyTransforms(data);
+                const result = await base.create(entityType, body);
+                return result.success ? { success: true, data: mapRow(result.data) } : result;
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : 'engine create failed' };
+            }
+        },
+        async update() {
+            return { success: false, error: 'declared engines do not support update yet' };
+        },
+        async delete(entityType, instanceId) {
+            try {
+                const base = await baseFor({});
+                return await base.delete(entityType, instanceId);
+            }
+            catch (err) {
+                return { success: false, error: err instanceof Error ? err.message : 'engine delete failed' };
+            }
+        },
+    };
+}
+//# sourceMappingURL=declared-connector.js.map

package/dist/connectors/declared-connector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-connector.js","sourceRoot":"","sources":["../../src/connectors/declared-connector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAOjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAE3D,+DAA+D;AAC/D,uCAAuC;AACvC,+DAA+D;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA0D;IACrF;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,EAAE;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAA;QACrE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAuD,CAAA;YACtF,OAAO,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,iBAAiB;gBACjD,CAAC,CAAC,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,iBAAiB,EAAE;gBAClD,CAAC,CAAC,KAAK,CAAA;QACX,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IACD;;;OAGG;IACH,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAC1B,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK;CACpG,CAAA;AAED,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CACb,kDAAkD,GAAG,cAAc,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC9G,CAAA;IACH,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC;AAED,+DAA+D;AAC/D,WAAW;AACX,+DAA+D;AAE/D,kFAAkF;AAClF,SAAS,IAAI,CAAC,QAAgB,EAAE,QAA0C;IACxE,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,CAAA;AACvF,CAAC;AAED,SAAS,QAAQ,CAAC,MAAe,EAAE,IAAY;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAU,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QAClD,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAQ,GAA+B,CAAC,GAAG,CAAC,CAAA;QAChF,OAAO,SAAS,CAAA;IAClB,CAAC,EAAE,MAAM,CAAC,CAAA;AACZ,CAAC;AAED,+DAA+D;AAC/D,6DAA6D;AAC7D,+DAA+D;AAE/D,8EAA8E;AAC9E,SAAS,cAAc,CAAC,QAAgB;IACtC,MAAM,CAAC,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAA;IAChC,OAAO,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAA;AAC5F,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,cAAc,CAAC,UAAkB;IACxC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,WAAW,UAAU,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,EAAE,EAAE,CAAA;IACnF,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;IAC9C,IAAI,QAAQ,GAAG,EAAE,CAAA;IACjB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAA;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,EAAE,CAAA;IACf,CAAC;IACD,IAAI,QAAQ,IAAI,cAAc,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,UAAU,IAAI,EAAE,EAAE,CAAA;IAC7E,OAAO,EAAE,MAAM,EAAE,WAAW,IAAI,EAAE,EAAE,CAAA;AACtC,CAAC;AAeD,MAAM,UAAU,uBAAuB,CAAC,OAAiC;IACvE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAA;IAEhE,sEAAsE;IACtE,wEAAwE;IACxE,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;IAErG,MAAM,YAAY,GAA2B,EAAE,CAAA;IAC/C,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;IAChD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAA;IAC3D,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAA;IAE9B;;;;;;;;;;;;;;OAcG;IACH,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,YAAY,CAAC,CAAA;IAC5C,MAAM,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAEjG,MAAM,WAAW,GAAG,KAAK,IAAqC,EAAE;QAC9D,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAA;QACvC,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAA;QACpC,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1D,CAAC,CAAA;IAED,0EAA0E;IAC1E,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2C,CAAA;IACnE,SAAS,eAAe,CAAC,KAAuC;QAC9D,MAAM,IAAI,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,KAAK,EAAE,CAAA;QAC1C,IAAI,CAAC,CAAC,CAAC,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;QAC5C,MAAM,GAAG,GAAG,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAC/C,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,WAAW,EAAE;iBACpB,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;iBAC1C,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;iBACzB,IAAI,CAAC,CAAC,IAAa,EAAE,EAAE;gBACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,OAAQ,CAAC,KAAK,CAAC,CAAA;gBAC9C,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;oBAC9B,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,gBAAgB,CAAC,CAAC,OAAQ,CAAC,KAAK,GAAG,CAAC,CAAA;gBAC9E,CAAC;gBACD,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,OAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAA;YAC5C,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACtB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACpB,MAAM,GAAG,CAAA;YACX,CAAC,CAAC,CAAA;YACJ,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAC5B,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,SAAS,eAAe,CAAC,GAA4B;QACnD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,GAAG,CAAA;QACvC,MAAM,GAAG,GAAG,EAAE,GAAG,GAAG,EAAE,CAAA;QACtB,KAAK,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,UAAU,EAAE,CAAC;YACvC,IAAI,KAAK,IAAI,GAAG;gBAAE,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAA;QAC/C,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,SAAS,MAAM,CAAC,GAAY;QAC1B,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,EAAE,CAA4B,CAAA;QACnD,MAAM,GAAG,GAA4B,EAAE,EAAE,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAA;QACnE,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;YACpC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;YAC7B,IAAI,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,CAAC;QACD;;;;;;;;;;;;;;;WAeG;QACH,MAAM,GAAG,GAAG,WAAW,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;QAC9F,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAA8B,CAAC,CAAA;QACtF,OAAO,eAAe,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED,8EAA8E;IAC9E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAwC,CAAA;IAC7D,SAAS,OAAO,CAAC,KAAuC;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAA;QACjC,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC5B,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC;iBAC7B,IAAI,CACH,CAAC,KAAK,EAAE,EAAE,CACR,IAAI,mBAAmB,CAAC,IAAI,EAAE;gBAC5B,OAAO,EAAE,MAAM;gBACf,kEAAkE;gBAClE,gBAAgB,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;gBAC5F,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrD,0EAA0E;gBAC1E,+DAA+D;gBAC/D,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,CAAC;gBACzF,cAAc,EAAE,CAAC,GAAG,EAAE,EAAE;oBACtB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;oBACtC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAA;gBACjE,CAAC;aACF,CAAC,CACL;iBACA,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;gBACtB,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACjB,MAAM,GAAG,CAAA;YACX,CAAC,CAAC,CAAA;YACJ,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QACzB,CAAC;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;IAED,0EAA0E;IAC1E,SAAS,aAAa,CAAC,KAA8B;QACnD,MAAM,GAAG,GAA2B,EAAE,CAAA;QACtC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAA4B,CAAC,EAAE,CAAC;YAC9E,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,IAAI,YAAY;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAC5D,CAAC;QACD,OAAO,GAAG,CAAA;IACZ,CAAC;IAED,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,QAAiB;QAEvB,KAAK,CAAC,KAAK,CAAC,UAAwB,EAAE,KAAkB;YACtD,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;gBAChD,qEAAqE;gBACrE,oEAAoE;gBACpE,mEAAmE;gBACnE,kEAAkE;gBAClE,uEAAuE;gBACvE,mFAAmF;gBACnF,oEAAoE;gBACpE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;gBAC5C,IAAI,CAAC,GAAG,CAAC,OAAO;oBAAE,OAAO,GAAG,CAAA;gBAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAA;YAC7E,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAA;YAC9F,CAAC;QACH,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,UAAwB,EAAE,UAA4B;YAC/D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;YAC/C,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAA;YACnE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,CAAsB,CAAC,EAAE,KAAK,UAAU,CAAC,CAAA;YACxF,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAA;QACxF,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,UAAwB,EAAE,IAA6B;YAClE,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAA;gBAC9B,uEAAuE;gBACvE,kDAAkD;gBAClD,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;gBACtG,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;gBAClD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAA;YAC/E,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAA;YAC/F,CAAC;QACH,CAAC;QAED,KAAK,CAAC,MAAM;YACV,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,4CAA4C,EAAE,CAAA;QAChF,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,UAAwB,EAAE,UAA4B;YACjE,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,EAAE,CAAC,CAAA;gBAC9B,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;YAClD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,EAAE,CAAA;YAC/F,CAAC;QACH,CAAC;KACiB,CAAA;AACtB,CAAC","sourcesContent":["/**\n * build an engine from its DECLARATION.\n *\n * A REST engine is not a class. A class has a call signature, and a\n * hand-written engine that takes one options object where the runtime passes\n * two positional arguments ends up asking SharePoint for `lists/undefined`.\n * A declaration has no signature to get wrong.\n *\n * WHAT THIS MODULE IS ALLOWED TO KNOW: how to turn seven declared facts into\n * an `HttpEntityConnector`. It must not know a vendor's name, and the\n * placement test measures exactly that — no provider name anywhere in\n * `packages/runtime`. Everything SharePoint-shaped lives in the declaration,\n * which lives in the pack that ships the connector.\n *\n * WHAT THE BASE DOES NOT LEARN. `entityPathMapper` and `responseMapper` stay\n * plain functions on `HttpConnectorConfig`; this builds them. The pre-flight —\n * Graph cannot address a list before its site id is resolved — is handled by\n * constructing ONE base per resolved binding, so the mapper stays synchronous.\n * Making it asynchronous would teach a shared contract one vendor's\n * addressing dance.\n *\n * @module @pwfabric/runtime/connectors/declared-connector\n */\n\nimport type { EngineDeclaration } from '@pwfabric/contracts'\n\nimport { HttpEntityConnector } from '../entity/http-connector.js'\nimport type {\n  ConnectorQueryResult,\n  ConnectorResult,\n  EntityConnector,\n} from '../entity/connector.js'\nimport type { EntityInstanceId, EntityQuery, EntityTypeId } from '../entity/types.js'\nimport { applyEntityQuery } from '../entity/apply-query.js'\n\n// ============================================================\n// VALUE TRANSFORMS — a CLOSED registry\n// ============================================================\n\n/**\n * The only value transforms a declaration may name.\n *\n * CLOSED ON PURPOSE. A declaration carries a NAME, never a function — the\n * moment it could carry a function it would be a class again with extra steps,\n * and an AI-written declaration would regain the power to get something wrong.\n * An unknown name throws at construction (see `resolveTransform`) rather than\n * passing values through unchanged, because a silently skipped transform looks\n * exactly like a field the source never sent.\n *\n * These two are named for what they DO, not for who needs them: the runtime\n * must not learn a vendor's name.\n */\nexport const VALUE_TRANSFORMS: Readonly<Record<string, (value: unknown) => unknown>> = {\n  /**\n   * A field whose value is a JSON STRING describing a hosted file becomes the\n   * absolute URL. Image/Thumbnail-typed columns serialise this way and a\n   * consumer binding it into an `image` block needs a real URL.\n   */\n  'hosted-file-url': (value) => {\n    if (typeof value !== 'string' || !value.startsWith('{')) return value\n    try {\n      const parsed = JSON.parse(value) as { serverUrl?: string; serverRelativeUrl?: string }\n      return parsed.serverUrl && parsed.serverRelativeUrl\n        ? `${parsed.serverUrl}${parsed.serverRelativeUrl}`\n        : value\n    } catch {\n      return value\n    }\n  },\n  /**\n   * A numeric string becomes a number. Form data yields strings only, while\n   * lookup-style columns are typed numeric by the API.\n   */\n  'numeric-string': (value) =>\n    typeof value === 'string' && value !== '' && !Number.isNaN(Number(value)) ? Number(value) : value,\n}\n\nfunction resolveTransform(use: string): (value: unknown) => unknown {\n  const fn = VALUE_TRANSFORMS[use]\n  if (!fn) {\n    throw new Error(\n      `engine declaration names an unknown transform \"${use}\" — known: ${Object.keys(VALUE_TRANSFORMS).join(', ')}`\n    )\n  }\n  return fn\n}\n\n// ============================================================\n// TEMPLATE\n// ============================================================\n\n/** `{name}` substitution. An unbound placeholder is left visible, not blanked. */\nfunction fill(template: string, bindings: Readonly<Record<string, string>>): string {\n  return template.replace(/\\{(\\w+)\\}/g, (whole, key: string) => bindings[key] ?? whole)\n}\n\nfunction readPath(source: unknown, path: string): unknown {\n  return path.split('.').reduce<unknown>((acc, key) => {\n    if (acc && typeof acc === 'object') return (acc as Record<string, unknown>)[key]\n    return undefined\n  }, source)\n}\n\n// ============================================================\n// THE ORIGIN — https, except an explicit http:// on loopback\n// ============================================================\n\n/** Hosts a declaration may reach over plain `http://`: the machine itself. */\nfunction isLoopbackHost(hostname: string): boolean {\n  const h = hostname.toLowerCase()\n  return h === 'localhost' || h === '127.0.0.1' || h === '[::1]' || h.endsWith('.localhost')\n}\n\n/**\n * The origin a filled declared host resolves to.\n *\n * - no scheme or `https://` → `https://<host>` (unchanged since the first release);\n * - `http://` on a loopback host (`localhost`, `127.0.0.1`, `[::1]`,\n *   `*.localhost`) → kept as `http://<host>`, so a development server is reachable;\n * - `http://` anywhere else → `https://<host>`, as every release before\n *   this one did. It is never downgraded (the visitor's token must not cross\n *   the network in clear text), and published apps whose connection holds an\n *   `http://` address keep working the way they always have.\n */\nfunction declaredOrigin(filledHost: string): { readonly origin: string } {\n  const plain = /^http:\\/\\//i.exec(filledHost)\n  if (!plain) return { origin: `https://${filledHost.replace(/^https?:\\/\\//i, '')}` }\n  const rest = filledHost.slice(plain[0].length)\n  let hostname = ''\n  try {\n    hostname = new URL(`http://${rest}`).hostname\n  } catch {\n    hostname = ''\n  }\n  if (hostname && isLoopbackHost(hostname)) return { origin: `http://${rest}` }\n  return { origin: `https://${rest}` }\n}\n\n// ============================================================\n// THE ENGINE\n// ============================================================\n\nexport interface DeclaredConnectorOptions {\n  /** Connection name — the engine reports it, and the registry keys on it. */\n  readonly name: string\n  readonly declaration: EngineDeclaration\n  /** Per-connection config the declaration's templates draw on. */\n  readonly config: Readonly<Record<string, unknown>>\n  readonly getAccessToken: () => Promise<string | null>\n}\n\nexport function createDeclaredConnector(options: DeclaredConnectorOptions): EntityConnector {\n  const { name, declaration: d, config, getAccessToken } = options\n\n  // Fail at construction, not at the first read: a declaration naming a\n  // transform nobody implements is broken whether or not anyone calls it.\n  const transforms = (d.transforms ?? []).map((t) => ({ field: t.field, fn: resolveTransform(t.use) }))\n\n  const stringConfig: Record<string, string> = {}\n  for (const [k, v] of Object.entries(config)) {\n    if (typeof v === 'string') stringConfig[k] = v\n  }\n\n  /**\n   * THE HOST IS A TEMPLATE — the one substitution a user-owned API cannot do\n   * without, and the one this function used to compute before the config it\n   * would have drawn on even existed.\n   *\n   * `graph.microsoft.com/v1.0` is a constant because Graph is one address for\n   * everyone. A connection to the user's OWN API has no constant to state: the\n   * address IS the thing the user supplies. `host: \"{baseUrl}\"` is how they\n   * supply it, and the scheme is stripped after filling so a pasted\n   * `https://api.example.com` and a bare `api.example.com` mean the same thing.\n   *\n   * An explicit `http://` survives ONLY for a loopback host — a development\n   * server on `http://127.0.0.1:8787` is otherwise unreachable. Anywhere else\n   * `http://` is upgraded to https, as before: see {@link declaredOrigin}.\n   */\n  const declared = declaredOrigin(fill(d.host, stringConfig))\n  const origin = declared.origin\n\n  /**\n   * THE READ PATHS ARE TEMPLATES TOO — and that is what makes a generic REST\n   * connection declarable rather than compiled.\n   *\n   * If `fill` reached only `resolve.path` and `path`, the RESPONSE SHAPE would\n   * have to be hardcoded into the declaration: an API answering `{data:[…]}`\n   * and one answering `{results:[…]}` would need two different atoms. Two\n   * atoms that differ only in a string is code wearing a manifest, and the\n   * declared-engine design's whole claim is that \"a new API is a connection\n   * record rather than code\".\n   *\n   * `fill` on a string carrying no `{name}` returns that string, so a\n   * declaration without templates behaves as a literal one. `graph-lists`\n   * is the proof and has a test that says so.\n   */\n  const readItems = fill(d.read.items, stringConfig)\n  const readId = fill(d.read.id, stringConfig)\n  const readFlatten = d.read.flatten === undefined ? undefined : fill(d.read.flatten, stringConfig)\n\n  const authHeaders = async (): Promise<Record<string, string>> => {\n    if (d.auth.type !== 'bearer') return {}\n    const token = await getAccessToken()\n    return token ? { Authorization: `Bearer ${token}` } : {}\n  }\n\n  /** Pre-flight, memoised per template result — the site id and its kin. */\n  const bindings = new Map<string, Promise<Record<string, string>>>()\n  function resolveBindings(extra: Readonly<Record<string, string>>): Promise<Record<string, string>> {\n    const base = { ...stringConfig, ...extra }\n    if (!d.resolve) return Promise.resolve(base)\n    const url = origin + fill(d.resolve.path, base)\n    let pending = bindings.get(url)\n    if (!pending) {\n      pending = authHeaders()\n        .then((headers) => fetch(url, { headers }))\n        .then((res) => res.json())\n        .then((body: unknown) => {\n          const value = readPath(body, d.resolve!.field)\n          if (typeof value !== 'string') {\n            throw new Error(`engine pre-flight ${url} carried no \"${d.resolve!.field}\"`)\n          }\n          return { ...base, [d.resolve!.as]: value }\n        })\n        .catch((err: unknown) => {\n          bindings.delete(url)\n          throw err\n        })\n      bindings.set(url, pending)\n    }\n    return pending\n  }\n\n  function applyTransforms(row: Record<string, unknown>): Record<string, unknown> {\n    if (transforms.length === 0) return row\n    const out = { ...row }\n    for (const { field, fn } of transforms) {\n      if (field in out) out[field] = fn(out[field])\n    }\n    return out\n  }\n\n  function mapRow(raw: unknown): Record<string, unknown> {\n    const item = (raw ?? {}) as Record<string, unknown>\n    const row: Record<string, unknown> = { id: readPath(item, readId) }\n    for (const key of d.read.lift ?? []) {\n      const v = readPath(item, key)\n      if (v !== undefined) row[key] = v\n    }\n    /**\n     * `flatten: \"*\"` means THE ITEM ITSELF IS THE BAG.\n     *\n     * `mapRow` starts from `{ id }` and only grows when `flatten` names a\n     * nested bag. Graph's bag is `fields`; flat REST has no bag because the\n     * item is already the row — so without this a plain REST read produced\n     * rows carrying nothing but `id`, and the panels rendered empty for a\n     * reason no warning named.\n     *\n     * `\"*\"` is spelled out rather than inferred from an absent `flatten`:\n     * inferring it would silently change what every existing declaration\n     * means, and a fallback nobody declared is how this family of bugs got\n     * here. It is also not a valid `readPath`, so it can never collide with a\n     * real path. The schema is untouched — it already accepts any non-empty\n     * string, so contracts stay frozen.\n     */\n    const bag = readFlatten === '*' ? item : readFlatten ? readPath(item, readFlatten) : undefined\n    if (bag && typeof bag === 'object') Object.assign(row, bag as Record<string, unknown>)\n    return applyTransforms(row)\n  }\n\n  /** One base per resolved binding set — the site is already inside baseUrl. */\n  const bases = new Map<string, Promise<HttpEntityConnector>>()\n  function baseFor(extra: Readonly<Record<string, string>>): Promise<HttpEntityConnector> {\n    const key = JSON.stringify(extra)\n    let pending = bases.get(key)\n    if (!pending) {\n      pending = resolveBindings(extra)\n        .then(\n          (bound) =>\n            new HttpEntityConnector(name, {\n              baseUrl: origin,\n              // Synchronous: every binding is already resolved into the string.\n              entityPathMapper: (entityType) => fill(d.path, { ...bound, entityType: String(entityType) }),\n              ...(d.params ? { defaultQueryParams: d.params } : {}),\n              // `none` means no credential at all: the visitor's token must never reach\n              // a host that did not ask for it, so no auth config is passed.\n              ...(d.auth.type === 'none' ? {} : { auth: { type: d.auth.type, token: getAccessToken } }),\n              responseMapper: (raw) => {\n                const items = readPath(raw, readItems)\n                return { items: Array.isArray(items) ? items.map(mapRow) : [] }\n              },\n            })\n        )\n        .catch((err: unknown) => {\n          bases.delete(key)\n          throw err\n        })\n      bases.set(key, pending)\n    }\n    return pending\n  }\n\n  /** A query may name its own binding overrides (e.g. a different site). */\n  function overridesFrom(query: EntityQuery | undefined): Record<string, string> {\n    const out: Record<string, string> = {}\n    for (const [k, v] of Object.entries((query ?? {}) as Record<string, unknown>)) {\n      if (typeof v === 'string' && k in stringConfig) out[k] = v\n    }\n    return out\n  }\n\n  return {\n    name,\n    type: 'custom' as const,\n\n    async query(entityType: EntityTypeId, query: EntityQuery): Promise<ConnectorQueryResult> {\n      try {\n        const base = await baseFor(overridesFrom(query))\n        // A declared engine talks to a FOREIGN API. The base connector would\n        // serialise the surface's query as the platform's own wire params —\n        // `filter=<json>&sort=&limit=&offset=` — which mean nothing there:\n        // Microsoft Graph answers 400 to any list read carrying `filter=`\n        // (sort-only reads happen to pass, so half the pages would be live and\n        // half fallback). Fetch with the declaration's own params only and apply the query\n        // here, where every declared engine speaks the same query language.\n        const res = await base.query(entityType, {})\n        if (!res.success) return res\n        return { success: true, result: applyEntityQuery(res.result.items, query) }\n      } catch (err) {\n        return { success: false, error: err instanceof Error ? err.message : 'engine query failed' }\n      }\n    },\n\n    async read(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult> {\n      const result = await this.query(entityType, {})\n      if (!result.success) return { success: false, error: result.error }\n      const match = result.result.items.find((i) => (i as { id?: unknown }).id === instanceId)\n      return match ? { success: true, data: match } : { success: false, error: 'Not found' }\n    },\n\n    async create(entityType: EntityTypeId, data: Record<string, unknown>): Promise<ConnectorResult> {\n      try {\n        const base = await baseFor({})\n        // The wrap belongs to the LAYER: the base posts whatever it is handed,\n        // and the declaration says what shape to hand it.\n        const body = d.write?.bodyWrap ? { [d.write.bodyWrap]: applyTransforms(data) } : applyTransforms(data)\n        const result = await base.create(entityType, body)\n        return result.success ? { success: true, data: mapRow(result.data) } : result\n      } catch (err) {\n        return { success: false, error: err instanceof Error ? err.message : 'engine create failed' }\n      }\n    },\n\n    async update(): Promise<ConnectorResult> {\n      return { success: false, error: 'declared engines do not support update yet' }\n    },\n\n    async delete(entityType: EntityTypeId, instanceId: EntityInstanceId): Promise<ConnectorResult> {\n      try {\n        const base = await baseFor({})\n        return await base.delete(entityType, instanceId)\n      } catch (err) {\n        return { success: false, error: err instanceof Error ? err.message : 'engine delete failed' }\n      }\n    },\n  } as EntityConnector\n}\n"]}

package/dist/connectors/engine-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Connector Engine Registry
+ *
+ * Connection name → constructed engine instance. Owns the load-and-
+ * construct lifecycle: `configure()` declares the world's connections
+ * (which engine bundle serves each name + per-connection config), and
+ * `resolve()` lazily loads the bundle via `ConnectorModuleLoader` and
+ * constructs the engine ONCE with `(getAccessToken, config)` — the exact
+ * signature the existing engines (GraphListConnector, the Graph motor)
+ * already take.
+ *
+ * Auth seam: the access-token hook handed to each engine closes over an
+ * injectable resolver. By default the resolver answers
+ * `null` — engines behave as unauthenticated and degrade honestly. A host
+ * plugs the AuthRegistry in via `setAccessTokenResolver` (or the factory
+ * option) without another core change.
+ *
+ * Error isolation: `resolve()` NEVER throws. A failed load or construction
+ * marks the entry `failed` with the reason (`getStatus`) and resolves
+ * `null`; consumers surface the reason (e.g. into the `__errors` context)
+ * instead of crashing the surface.
+ *
+ * @module @pwfabric/runtime/connectors/engine-registry
+ */
+import { type ConnectorModuleLoaderImpl } from './module-loader.js';
+import type { ConnectorAccessTokenResolver, ConnectorConnectionBinding, ConnectorEngine, ConnectorEngineRegistry, ConnectorEngineStatus } from './types.js';
+export declare class DefaultConnectorEngineRegistry implements ConnectorEngineRegistry {
+    private readonly entries;
+    private readonly loader;
+    private tokenResolver;
+    constructor(options?: {
+        readonly loader?: ConnectorModuleLoaderImpl;
+        readonly getAccessToken?: ConnectorAccessTokenResolver;
+    });
+    configure(bindings: readonly ConnectorConnectionBinding[]): void;
+    register(connection: string, engine: ConnectorEngine): void;
+    resolve(connection: string): Promise<ConnectorEngine | null>;
+    getStatus(connection: string): ConnectorEngineStatus;
+    setAccessTokenResolver(resolver: ConnectorAccessTokenResolver): void;
+    list(): readonly string[];
+    clear(): void;
+}
+/**
+ * Create a connector engine registry. One per world/host render context —
+ * deliberately NOT a singleton (per-connection config is world state).
+ */
+export declare function createConnectorEngineRegistry(options?: {
+    readonly loader?: ConnectorModuleLoaderImpl;
+    readonly getAccessToken?: ConnectorAccessTokenResolver;
+}): ConnectorEngineRegistry;

package/dist/connectors/engine-registry.js

@@ -0,0 +1,135 @@
+/**
+ * Connector Engine Registry
+ *
+ * Connection name → constructed engine instance. Owns the load-and-
+ * construct lifecycle: `configure()` declares the world's connections
+ * (which engine bundle serves each name + per-connection config), and
+ * `resolve()` lazily loads the bundle via `ConnectorModuleLoader` and
+ * constructs the engine ONCE with `(getAccessToken, config)` — the exact
+ * signature the existing engines (GraphListConnector, the Graph motor)
+ * already take.
+ *
+ * Auth seam: the access-token hook handed to each engine closes over an
+ * injectable resolver. By default the resolver answers
+ * `null` — engines behave as unauthenticated and degrade honestly. A host
+ * plugs the AuthRegistry in via `setAccessTokenResolver` (or the factory
+ * option) without another core change.
+ *
+ * Error isolation: `resolve()` NEVER throws. A failed load or construction
+ * marks the entry `failed` with the reason (`getStatus`) and resolves
+ * `null`; consumers surface the reason (e.g. into the `__errors` context)
+ * instead of crashing the surface.
+ *
+ * @module @pwfabric/runtime/connectors/engine-registry
+ */
+import { ConnectorModuleLoader } from './module-loader.js';
+// ============================================================
+// HELPERS
+// ============================================================
+/** Duck-check the minimal read contract every engine must satisfy. */
+function isConnectorEngine(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.query === 'function');
+}
+/** Default token resolver — unauthenticated until a host installs one. */
+const NULL_TOKEN_RESOLVER = async () => null;
+// ============================================================
+// REGISTRY IMPLEMENTATION
+// ============================================================
+export class DefaultConnectorEngineRegistry {
+    entries = new Map();
+    loader;
+    tokenResolver;
+    constructor(options) {
+        this.loader = options?.loader ?? ConnectorModuleLoader;
+        this.tokenResolver = options?.getAccessToken ?? NULL_TOKEN_RESOLVER;
+    }
+    configure(bindings) {
+        // Replace semantics: drop entries whose binding disappeared, keep
+        // constructed engines whose binding is unchanged (identity by
+        // connection + descriptor + config reference equality is too strict —
+        // a reconfigure resets the entry so config changes take effect).
+        this.entries.clear();
+        for (const binding of bindings) {
+            this.entries.set(binding.connection, {
+                binding,
+                engine: null,
+                pending: null,
+                failure: null,
+            });
+        }
+    }
+    register(connection, engine) {
+        this.entries.set(connection, { binding: null, engine, pending: null, failure: null });
+    }
+    async resolve(connection) {
+        const entry = this.entries.get(connection);
+        if (!entry)
+            return null;
+        if (entry.engine)
+            return entry.engine;
+        if (entry.failure !== null)
+            return null; // sticky until reconfigure/clear
+        if (entry.pending)
+            return entry.pending;
+        if (!entry.binding)
+            return null;
+        const binding = entry.binding;
+        const construct = async () => {
+            try {
+                const factory = await this.loader.load(binding.descriptor);
+                // The hook closes over `this.tokenResolver` so a later
+                // setAccessTokenResolver takes effect on the NEXT token
+                // request without reconstructing engines.
+                const getAccessToken = async () => this.tokenResolver(binding);
+                const engine = factory(getAccessToken, binding.config ?? {});
+                if (!isConnectorEngine(engine)) {
+                    throw new Error(`Engine for connection '${binding.connection}' does not expose query() — ` +
+                        `not a usable connector engine`);
+                }
+                entry.engine = engine;
+                return engine;
+            }
+            catch (err) {
+                entry.failure = err instanceof Error ? err.message : String(err);
+                return null;
+            }
+            finally {
+                entry.pending = null;
+            }
+        };
+        entry.pending = construct();
+        return entry.pending;
+    }
+    getStatus(connection) {
+        const entry = this.entries.get(connection);
+        if (!entry)
+            return { state: 'unregistered' };
+        if (entry.engine)
+            return { state: 'ready' };
+        if (entry.failure !== null)
+            return { state: 'failed', reason: entry.failure };
+        return { state: 'pending' };
+    }
+    setAccessTokenResolver(resolver) {
+        this.tokenResolver = resolver;
+    }
+    list() {
+        return Array.from(this.entries.keys());
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create a connector engine registry. One per world/host render context —
+ * deliberately NOT a singleton (per-connection config is world state).
+ */
+export function createConnectorEngineRegistry(options) {
+    return new DefaultConnectorEngineRegistry(options);
+}
+//# sourceMappingURL=engine-registry.js.map

package/dist/connectors/engine-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-registry.js","sourceRoot":"","sources":["../../src/connectors/engine-registry.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Connector Engine Registry\n *\n * Connection name → constructed engine instance. Owns the load-and-\n * construct lifecycle: `configure()` declares the world's connections\n * (which engine bundle serves each name + per-connection config), and\n * `resolve()` lazily loads the bundle via `ConnectorModuleLoader` and\n * constructs the engine ONCE with `(getAccessToken, config)` — the exact\n * signature the existing engines (GraphListConnector, the Graph motor)\n * already take.\n *\n * Auth seam: the access-token hook handed to each engine closes over an\n * injectable resolver. By default the resolver answers\n * `null` — engines behave as unauthenticated and degrade honestly. A host\n * plugs the AuthRegistry in via `setAccessTokenResolver` (or the factory\n * option) without another core change.\n *\n * Error isolation: `resolve()` NEVER throws. A failed load or construction\n * marks the entry `failed` with the reason (`getStatus`) and resolves\n * `null`; consumers surface the reason (e.g. into the `__errors` context)\n * instead of crashing the surface.\n *\n * @module @pwfabric/runtime/connectors/engine-registry\n */\n\nimport { ConnectorModuleLoader, type ConnectorModuleLoaderImpl } from './module-loader.js'\nimport type {\n  ConnectorAccessTokenResolver,\n  ConnectorConnectionBinding,\n  ConnectorEngine,\n  ConnectorEngineRegistry,\n  ConnectorEngineStatus,\n} from './types.js'\n\n// ============================================================\n// HELPERS\n// ============================================================\n\n/** Duck-check the minimal read contract every engine must satisfy. */\nfunction isConnectorEngine(value: unknown): value is ConnectorEngine {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as { query?: unknown }).query === 'function'\n  )\n}\n\n/** Default token resolver — unauthenticated until a host installs one. */\nconst NULL_TOKEN_RESOLVER: ConnectorAccessTokenResolver = async () => null\n\ninterface RegistryEntry {\n  readonly binding: ConnectorConnectionBinding | null\n  engine: ConnectorEngine | null\n  pending: Promise<ConnectorEngine | null> | null\n  failure: string | null\n}\n\n// ============================================================\n// REGISTRY IMPLEMENTATION\n// ============================================================\n\nexport class DefaultConnectorEngineRegistry implements ConnectorEngineRegistry {\n  private readonly entries = new Map<string, RegistryEntry>()\n  private readonly loader: ConnectorModuleLoaderImpl\n  private tokenResolver: ConnectorAccessTokenResolver\n\n  constructor(options?: {\n    readonly loader?: ConnectorModuleLoaderImpl\n    readonly getAccessToken?: ConnectorAccessTokenResolver\n  }) {\n    this.loader = options?.loader ?? ConnectorModuleLoader\n    this.tokenResolver = options?.getAccessToken ?? NULL_TOKEN_RESOLVER\n  }\n\n  configure(bindings: readonly ConnectorConnectionBinding[]): void {\n    // Replace semantics: drop entries whose binding disappeared, keep\n    // constructed engines whose binding is unchanged (identity by\n    // connection + descriptor + config reference equality is too strict —\n    // a reconfigure resets the entry so config changes take effect).\n    this.entries.clear()\n    for (const binding of bindings) {\n      this.entries.set(binding.connection, {\n        binding,\n        engine: null,\n        pending: null,\n        failure: null,\n      })\n    }\n  }\n\n  register(connection: string, engine: ConnectorEngine): void {\n    this.entries.set(connection, { binding: null, engine, pending: null, failure: null })\n  }\n\n  async resolve(connection: string): Promise<ConnectorEngine | null> {\n    const entry = this.entries.get(connection)\n    if (!entry) return null\n    if (entry.engine) return entry.engine\n    if (entry.failure !== null) return null // sticky until reconfigure/clear\n    if (entry.pending) return entry.pending\n    if (!entry.binding) return null\n\n    const binding = entry.binding\n    const construct = async (): Promise<ConnectorEngine | null> => {\n      try {\n        const factory = await this.loader.load(binding.descriptor)\n        // The hook closes over `this.tokenResolver` so a later\n        // setAccessTokenResolver takes effect on the NEXT token\n        // request without reconstructing engines.\n        const getAccessToken = async (): Promise<string | null> =>\n          this.tokenResolver(binding)\n        const engine: unknown = factory(getAccessToken, binding.config ?? {})\n        if (!isConnectorEngine(engine)) {\n          throw new Error(\n            `Engine for connection '${binding.connection}' does not expose query() — ` +\n              `not a usable connector engine`\n          )\n        }\n        entry.engine = engine\n        return engine\n      } catch (err) {\n        entry.failure = err instanceof Error ? err.message : String(err)\n        return null\n      } finally {\n        entry.pending = null\n      }\n    }\n\n    entry.pending = construct()\n    return entry.pending\n  }\n\n  getStatus(connection: string): ConnectorEngineStatus {\n    const entry = this.entries.get(connection)\n    if (!entry) return { state: 'unregistered' }\n    if (entry.engine) return { state: 'ready' }\n    if (entry.failure !== null) return { state: 'failed', reason: entry.failure }\n    return { state: 'pending' }\n  }\n\n  setAccessTokenResolver(resolver: ConnectorAccessTokenResolver): void {\n    this.tokenResolver = resolver\n  }\n\n  list(): readonly string[] {\n    return Array.from(this.entries.keys())\n  }\n\n  clear(): void {\n    this.entries.clear()\n  }\n}\n\n// ============================================================\n// FACTORY\n// ============================================================\n\n/**\n * Create a connector engine registry. One per world/host render context —\n * deliberately NOT a singleton (per-connection config is world state).\n */\nexport function createConnectorEngineRegistry(options?: {\n  readonly loader?: ConnectorModuleLoaderImpl\n  readonly getAccessToken?: ConnectorAccessTokenResolver\n}): ConnectorEngineRegistry {\n  return new DefaultConnectorEngineRegistry(options)\n}\n"]}

package/dist/connectors/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Connector Engine Module
+ *
+ * Platform-side loading + registry for CONNECTOR/PROVIDER atom engines,
+ * so platform-rendered surfaces can execute the same engines the runner
+ * app runs from its bundled pack source.
+ *
+ * @module @pwfabric/runtime/connectors
+ */
+export type { ConnectorEngineKind, ConnectorEngineDescriptor, ConnectorAccessTokenHook, ConnectorEngineFactory, ConnectorEngineModule, ConnectorEngine, ConnectorConnectionBinding, ConnectorAccessTokenResolver, ConnectorEngineStatus, ConnectorEngineRegistry, SurfaceConnection, SurfaceConnectionsValue, } from './types.js';
+export { ConnectorModuleLoader, ConnectorModuleLoaderImpl, createConnectorModuleLoader, type ConnectorModuleEvaluator, } from './module-loader.js';
+export { DefaultConnectorEngineRegistry, createConnectorEngineRegistry, } from './engine-registry.js';
+export { createDeclaredConnector, VALUE_TRANSFORMS } from './declared-connector.js';
+export type { DeclaredConnectorOptions } from './declared-connector.js';

package/dist/connectors/index.js

@@ -0,0 +1,14 @@
+/**
+ * Connector Engine Module
+ *
+ * Platform-side loading + registry for CONNECTOR/PROVIDER atom engines,
+ * so platform-rendered surfaces can execute the same engines the runner
+ * app runs from its bundled pack source.
+ *
+ * @module @pwfabric/runtime/connectors
+ */
+export { ConnectorModuleLoader, ConnectorModuleLoaderImpl, createConnectorModuleLoader, } from './module-loader.js';
+export { DefaultConnectorEngineRegistry, createConnectorEngineRegistry, } from './engine-registry.js';
+// an engine built from its declaration; the runtime learns no vendor name.
+export { createDeclaredConnector, VALUE_TRANSFORMS } from './declared-connector.js';
+//# sourceMappingURL=index.js.map

package/dist/connectors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/connectors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAiBH,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,2BAA2B,GAE5B,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EACL,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,sBAAsB,CAAA;AAE7B,2EAA2E;AAC3E,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA","sourcesContent":["/**\n * Connector Engine Module\n *\n * Platform-side loading + registry for CONNECTOR/PROVIDER atom engines,\n * so platform-rendered surfaces can execute the same engines the runner\n * app runs from its bundled pack source.\n *\n * @module @pwfabric/runtime/connectors\n */\n\nexport type {\n  ConnectorEngineKind,\n  ConnectorEngineDescriptor,\n  ConnectorAccessTokenHook,\n  ConnectorEngineFactory,\n  ConnectorEngineModule,\n  ConnectorEngine,\n  ConnectorConnectionBinding,\n  ConnectorAccessTokenResolver,\n  ConnectorEngineStatus,\n  ConnectorEngineRegistry,\n  SurfaceConnection,\n  SurfaceConnectionsValue,\n} from './types.js'\n\nexport {\n  ConnectorModuleLoader,\n  ConnectorModuleLoaderImpl,\n  createConnectorModuleLoader,\n  type ConnectorModuleEvaluator,\n} from './module-loader.js'\n\nexport {\n  DefaultConnectorEngineRegistry,\n  createConnectorEngineRegistry,\n} from './engine-registry.js'\n\n// an engine built from its declaration; the runtime learns no vendor name.\nexport { createDeclaredConnector, VALUE_TRANSFORMS } from './declared-connector.js'\nexport type { DeclaredConnectorOptions } from './declared-connector.js'\n"]}