@rudra-js/core 0.1.0

package/dist/provider.d.ts

@@ -0,0 +1,80 @@
+import type { z } from 'zod';
+import type { GeneratedSpec } from './component-spec.js';
+/**
+ * The language-model port.
+ *
+ * `@rudra-js/core` depends on no vendor SDK. Adapters live in their own packages,
+ * so a host installs exactly one and the rest never reach its dependency tree.
+ * Anything satisfying this interface works — a hosted API, a self-hosted model,
+ * an in-tenancy deployment, or a recorded fixture.
+ */
+/** Reported by an adapter for cost accounting. Never used for control flow. */
+export interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface ProviderRequest {
+    /**
+     * Stable across every request in a deployment. Adapters that support prompt
+     * caching should mark this as the cached prefix; interpolating anything
+     * per-shopper into it would silently destroy the cache hit rate.
+     */
+    system: string;
+    /** Per-request content. Must not be merged into the cached prefix. */
+    user: string;
+    /**
+     * The schema the response must satisfy. Adapters convert it with their own
+     * SDK helper, so there is no hand-maintained JSON Schema to drift out of
+     * sync with the one `component-spec` defines.
+     */
+    schema: z.ZodType<GeneratedSpec>;
+    /** Fires when the caller's budget elapses. An adapter must stop work. */
+    signal: AbortSignal;
+}
+export interface ProviderResult {
+    spec: GeneratedSpec;
+    usage?: TokenUsage;
+}
+/**
+ * What an adapter promises.
+ *
+ * Three obligations, none of which the caller can verify from the outside, so
+ * they are stated here rather than assumed:
+ *
+ *  1. Return a parsed object, not a string. Turning model output into a
+ *     `GeneratedSpec` is the adapter's job, because only it knows what its
+ *     structured-output mode returns.
+ *  2. Throw on failure — a refusal, a transport error, an unparseable
+ *     response. Never return a partial or invented spec. The caller treats a
+ *     throw as "use the deterministic component", which is always safe; a
+ *     fabricated spec is not.
+ *  3. Respect `signal`, in both directions: do not start work when it is
+ *     already aborted, and stop when it aborts mid-flight. The caller races
+ *     the call against its own timeout regardless, so ignoring it does not
+ *     hold a page open — but it does leave work running and billing after
+ *     nobody is waiting, and it answers a caller that has already given up.
+ *
+ *     `AbortSignal.throwIfAborted()` is the whole of the first half.
+ *
+ * The caller re-validates whatever comes back. An adapter that returns
+ * something malformed is a bug, not a security hole.
+ */
+export interface ComponentProvider {
+    /** Short identifier recorded on every generated spec, e.g. 'anthropic'. */
+    readonly name: string;
+    /** Concrete model identifier, e.g. 'claude-opus-5'. */
+    readonly model: string;
+    generate(request: ProviderRequest): Promise<ProviderResult>;
+}
+/**
+ * A provider that returns a fixed spec and never touches the network.
+ *
+ * This is the benchmark's control: it isolates the cost of the framework from
+ * the latency of a model, which is the only way to report what server-side
+ * rendering itself costs. It is also what the generator's tests run against,
+ * since a test that needs an API key is a test nobody runs.
+ */
+export declare function createFixedSpecProvider(spec: GeneratedSpec): ComponentProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,yEAAyE;IACzE,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7D;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,iBAAiB,CAa9E"}

package/dist/provider.js

@@ -0,0 +1,23 @@
+/**
+ * A provider that returns a fixed spec and never touches the network.
+ *
+ * This is the benchmark's control: it isolates the cost of the framework from
+ * the latency of a model, which is the only way to report what server-side
+ * rendering itself costs. It is also what the generator's tests run against,
+ * since a test that needs an API key is a test nobody runs.
+ */
+export function createFixedSpecProvider(spec) {
+    return {
+        name: 'fixed',
+        model: 'none',
+        generate: async ({ signal }) => {
+            // Nothing here is slow enough to need cancelling, which is exactly why it
+            // is worth checking: the obligation is not "cancel your work", it is "do
+            // not answer a caller that has already given up". A reference
+            // implementation that skips the cheap half teaches the wrong lesson.
+            signal.throwIfAborted();
+            return { spec };
+        },
+    };
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AA4EA;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAmB;IACzD,OAAO;QACL,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,MAAM;QACb,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE;YAC7B,0EAA0E;YAC1E,yEAAyE;YACzE,8DAA8D;YAC9D,qEAAqE;YACrE,MAAM,CAAC,cAAc,EAAE,CAAC;YACxB,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/reconciliation.d.ts

@@ -0,0 +1,49 @@
+import type { Block, GeneratedSpec } from './component-spec.js';
+import type { SignalDigest } from './signal-digest.js';
+import type { Bundle, TrackingInput } from './tracking-input.js';
+/**
+ * More than this and the component stops being a component.
+ *
+ * Exported because the fill pass has to read the same blocks this module will:
+ * one past the cap never renders, so nothing is worth reserving for it.
+ */
+export declare const MAX_BLOCKS = 4;
+export interface ReconcileResult {
+    spec: GeneratedSpec;
+    /** True when something survived that is worth rendering. */
+    isUsable: boolean;
+    /** Machine-readable notes on what was removed or changed, for evaluation. */
+    violations: string[];
+}
+/**
+ * SKUs that must never be recommended, whatever chose them.
+ *
+ * Exported because the deterministic selector applies the same rule when it
+ * picks. Two copies of "never recommend these" would drift, and the pair that
+ * drifted would be the model path and the fallback path — the two whose
+ * comparability the whole evaluation depends on.
+ */
+export declare function neverRecommend(digest: SignalDigest): Set<string>;
+/**
+ * The set this shopper should get, decided before anything is placed.
+ *
+ * The generator needs the answer early, so it can keep the set's products out
+ * of the grid and keep room for them. `chooseBundle` stays private: this hands
+ * out the choice, not the machinery behind it.
+ *
+ * `spokenFor` is what the blocks above the bundle block will have placed by the
+ * time it is reached. Placing it here first is what makes the two choices agree:
+ * a set is only pre-chosen if reconciliation could still reach for it.
+ */
+export declare function bundleForShopper(input: TrackingInput, digest: SignalDigest, spokenFor: readonly string[]): Bundle | undefined;
+/**
+ * The hero products these blocks will really place.
+ *
+ * A hero keeps the product the model named — its headline was written about
+ * that product — so it spends a slot of the item budget the grid cannot have.
+ * One this shopper cannot see is dropped below and spends nothing, so it is not
+ * counted here either.
+ */
+export declare function placeableHeroSkus(blocks: readonly Block[], input: TrackingInput, digest: SignalDigest): string[];
+export declare function reconcileSpec(generated: GeneratedSpec, input: TrackingInput, digest: SignalDigest): ReconcileResult;
+//# sourceMappingURL=reconciliation.d.ts.map

package/dist/reconciliation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation.d.ts","sourceRoot":"","sources":["../src/reconciliation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,MAAM,EAAW,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAqC1E;;;;;GAKG;AACH,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AA2BD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,GAAG,CAAC,MAAM,CAAC,CAQhE;AAwVD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,KAAK,EAAE,EACxB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,YAAY,GACnB,MAAM,EAAE,CAcV;AAoID,wBAAgB,aAAa,CAC3B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,YAAY,GACnB,eAAe,CA0CjB"}