@elytracms/studio 0.0.43 → 0.0.44

package/dist/lib/ai/config.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `defineStudio({ ai })` resolution + the capability gate (EC-331).
+ *
+ * House validation-first style (mirrors `resolveWorkspaceConfig`): never throws —
+ * every failure is a structured, path-located {@link AiConfigIssue}; `ok` is false
+ * when any error-severity issue is present. The serializable parts (`enabled`,
+ * `limits`) are Zod-checked; the `provider` is live code, so it is validated by the
+ * **capability gate** (tool calling + structured output required) instead of a shape
+ * parse — the same discipline the workspace config uses for opaque `components`.
+ *
+ * Runs when the AI subsystem boots (the route factory / future chat UI call it), not
+ * on every studio mount — so an unconfigured studio never imports this module and
+ * never pulls the AI SDK. When `enabled: false`, the gate is skipped (nothing loads).
+ */
+import { z } from 'zod';
+import type { AiLimits, AiProvider, KnowledgeSource, StudioAiConfig } from './types';
+export declare const AI_CONFIG_ISSUE_CODES: readonly ["invalid-config-shape", "missing-provider", "provider-missing-capabilities", "provider-not-callable"];
+export type AiConfigIssueCode = (typeof AI_CONFIG_ISSUE_CODES)[number];
+/** A structured, path-located `ai`-config issue (never thrown — collected). */
+export interface AiConfigIssue {
+    code: AiConfigIssueCode;
+    severity: 'error' | 'warning';
+    message: string;
+    path: ReadonlyArray<string | number>;
+}
+/** The serializable, JSON-validatable subset of the limits block. */
+export declare const aiLimitsSchema: z.ZodObject<{
+    maxRequestsPerMinute: z.ZodOptional<z.ZodNumber>;
+    maxRepairAttempts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export interface ResolvedAiConfig {
+    /** Whether the feature is active (present + not `enabled: false`). */
+    enabled: boolean;
+    provider: AiProvider;
+    knowledge: KnowledgeSource[];
+    limits: AiLimits;
+}
+export interface ResolveAiConfigResult {
+    /** True when no error-severity issue is present. */
+    ok: boolean;
+    /** The resolved config; present only when `ok`. */
+    resolved?: ResolvedAiConfig;
+    issues: AiConfigIssue[];
+}
+/**
+ * The capability gate: a provider must declare tool calling + structured output.
+ * Returns the blocking issues (empty when the provider satisfies the gate).
+ */
+export declare function assertProviderCapabilities(provider: AiProvider): AiConfigIssue[];
+/**
+ * Resolve + validate a `defineStudio({ ai })` block. Deterministic; never throws.
+ * The capability gate runs only when the feature is enabled (a disabled block loads
+ * nothing). A `null`/`undefined` block resolves to a disabled, ok result — callers
+ * treat that as "feature absent".
+ */
+export declare function resolveAiConfig(config: StudioAiConfig | null | undefined): ResolveAiConfigResult;
+/** True when a resolved-config result has no error-severity issues. */
+export declare function isAiConfigValid(result: ResolveAiConfigResult): boolean;

package/dist/lib/ai/config.js

@@ -0,0 +1,134 @@
+/**
+ * `defineStudio({ ai })` resolution + the capability gate (EC-331).
+ *
+ * House validation-first style (mirrors `resolveWorkspaceConfig`): never throws —
+ * every failure is a structured, path-located {@link AiConfigIssue}; `ok` is false
+ * when any error-severity issue is present. The serializable parts (`enabled`,
+ * `limits`) are Zod-checked; the `provider` is live code, so it is validated by the
+ * **capability gate** (tool calling + structured output required) instead of a shape
+ * parse — the same discipline the workspace config uses for opaque `components`.
+ *
+ * Runs when the AI subsystem boots (the route factory / future chat UI call it), not
+ * on every studio mount — so an unconfigured studio never imports this module and
+ * never pulls the AI SDK. When `enabled: false`, the gate is skipped (nothing loads).
+ */
+import { z } from 'zod';
+// --- Structured issues ------------------------------------------------------------
+export const AI_CONFIG_ISSUE_CODES = [
+    'invalid-config-shape',
+    'missing-provider',
+    'provider-missing-capabilities',
+    'provider-not-callable',
+];
+// --- Serializable shape (Zod) -----------------------------------------------------
+/** The serializable, JSON-validatable subset of the limits block. */
+export const aiLimitsSchema = z
+    .object({
+    maxRequestsPerMinute: z.number().int().positive().optional(),
+    maxRepairAttempts: z.number().int().nonnegative().optional(),
+})
+    .strict();
+/** Non-throwing structural test that a value looks like an {@link AiProvider}. */
+function looksLikeProvider(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        typeof value.capabilities === 'function' &&
+        typeof value.generateStructured === 'function');
+}
+/**
+ * The capability gate: a provider must declare tool calling + structured output.
+ * Returns the blocking issues (empty when the provider satisfies the gate).
+ */
+export function assertProviderCapabilities(provider) {
+    const issues = [];
+    let caps;
+    try {
+        caps = provider.capabilities();
+    }
+    catch {
+        return [
+            {
+                code: 'provider-not-callable',
+                severity: 'error',
+                message: `AI provider "${provider.id}" threw while reporting its capabilities.`,
+                path: ['ai', 'provider', 'capabilities'],
+            },
+        ];
+    }
+    const missing = [];
+    if (!caps?.toolCalling)
+        missing.push('tool calling');
+    if (!caps?.structuredOutput)
+        missing.push('structured output');
+    if (missing.length > 0) {
+        issues.push({
+            code: 'provider-missing-capabilities',
+            severity: 'error',
+            message: `AI provider "${provider.id}" is missing required capabilities: ${missing.join(', ')}. Tool calling and structured output are required.`,
+            path: ['ai', 'provider'],
+        });
+    }
+    return issues;
+}
+/**
+ * Resolve + validate a `defineStudio({ ai })` block. Deterministic; never throws.
+ * The capability gate runs only when the feature is enabled (a disabled block loads
+ * nothing). A `null`/`undefined` block resolves to a disabled, ok result — callers
+ * treat that as "feature absent".
+ */
+export function resolveAiConfig(config) {
+    const issues = [];
+    if (!config) {
+        return { ok: true, issues };
+    }
+    // Serializable shape: limits (Zod). Shape failure is terminal for that field only.
+    let limits = {};
+    if (config.limits !== undefined) {
+        const parsed = aiLimitsSchema.safeParse(config.limits);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                issues.push({
+                    code: 'invalid-config-shape',
+                    severity: 'error',
+                    message: issue.message,
+                    path: ['ai', 'limits', ...issue.path.map((p) => (typeof p === 'symbol' ? String(p) : p))],
+                });
+            }
+        }
+        else {
+            limits = parsed.data;
+        }
+    }
+    const enabled = config.enabled !== false;
+    // Provider presence + capability gate (live code — validated, not shape-parsed).
+    if (!looksLikeProvider(config.provider)) {
+        issues.push({
+            code: 'missing-provider',
+            severity: 'error',
+            message: 'defineStudio({ ai }) requires a `provider` with `id`, `capabilities()`, and `generateStructured()`.',
+            path: ['ai', 'provider'],
+        });
+    }
+    else if (enabled) {
+        issues.push(...assertProviderCapabilities(config.provider));
+    }
+    const ok = !issues.some((i) => i.severity === 'error');
+    if (!ok)
+        return { ok, issues };
+    return {
+        ok,
+        issues,
+        resolved: {
+            enabled,
+            provider: config.provider,
+            knowledge: config.knowledge ?? [],
+            limits,
+        },
+    };
+}
+/** True when a resolved-config result has no error-severity issues. */
+export function isAiConfigValid(result) {
+    return result.ok;
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/ai/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/lib/ai/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAQvB,qFAAqF;AAErF,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,sBAAsB;IACtB,kBAAkB;IAClB,+BAA+B;IAC/B,uBAAuB;CACf,CAAA;AAWV,qFAAqF;AAErF,qEAAqE;AACrE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,MAAM,CAAC;IACN,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5D,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE;CAC7D,CAAC;KACD,MAAM,EAAE,CAAA;AAoBX,kFAAkF;AAClF,SAAS,iBAAiB,CAAC,KAAc;IACvC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAQ,KAAoB,CAAC,EAAE,KAAK,QAAQ;QAC5C,OAAQ,KAAoB,CAAC,YAAY,KAAK,UAAU;QACxD,OAAQ,KAAoB,CAAC,kBAAkB,KAAK,UAAU,CAC/D,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAoB;IAC7D,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,IAAI,IAAI,CAAA;IACR,IAAI,CAAC;QACH,IAAI,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL;gBACE,IAAI,EAAE,uBAAuB;gBAC7B,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,gBAAgB,QAAQ,CAAC,EAAE,2CAA2C;gBAC/E,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,cAAc,CAAC;aACzC;SACF,CAAA;IACH,CAAC;IACD,MAAM,OAAO,GAAa,EAAE,CAAA;IAC5B,IAAI,CAAC,IAAI,EAAE,WAAW;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IACpD,IAAI,CAAC,IAAI,EAAE,gBAAgB;QAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA;IAC9D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,+BAA+B;YACrC,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,gBAAgB,QAAQ,CAAC,EAAE,uCAAuC,OAAO,CAAC,IAAI,CACrF,IAAI,CACL,oDAAoD;YACrD,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC;SACzB,CAAC,CAAA;IACJ,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyC;IACvE,MAAM,MAAM,GAAoB,EAAE,CAAA;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IAC7B,CAAC;IAED,mFAAmF;IACnF,IAAI,MAAM,GAAa,EAAE,CAAA;IACzB,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACtD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBACxC,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,sBAAsB;oBAC5B,QAAQ,EAAE,OAAO;oBACjB,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;iBAC1F,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,MAAM,CAAC,IAAI,CAAA;QACtB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,KAAK,KAAK,CAAA;IAExC,iFAAiF;IACjF,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,kBAAkB;YACxB,QAAQ,EAAE,OAAO;YACjB,OAAO,EACL,qGAAqG;YACvG,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC;SACzB,CAAC,CAAA;IACJ,CAAC;SAAM,IAAI,OAAO,EAAE,CAAC;QACnB,MAAM,CAAC,IAAI,CAAC,GAAG,0BAA0B,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC7D,CAAC;IAED,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAA;IACtD,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAA;IAE9B,OAAO;QACL,EAAE;QACF,MAAM;QACN,QAAQ,EAAE;YACR,OAAO;YACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,EAAE;YACjC,MAAM;SACP;KACF,CAAA;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,MAA6B;IAC3D,OAAO,MAAM,CAAC,EAAE,CAAA;AAClB,CAAC","sourcesContent":["/**\n * `defineStudio({ ai })` resolution + the capability gate (EC-331).\n *\n * House validation-first style (mirrors `resolveWorkspaceConfig`): never throws —\n * every failure is a structured, path-located {@link AiConfigIssue}; `ok` is false\n * when any error-severity issue is present. The serializable parts (`enabled`,\n * `limits`) are Zod-checked; the `provider` is live code, so it is validated by the\n * **capability gate** (tool calling + structured output required) instead of a shape\n * parse — the same discipline the workspace config uses for opaque `components`.\n *\n * Runs when the AI subsystem boots (the route factory / future chat UI call it), not\n * on every studio mount — so an unconfigured studio never imports this module and\n * never pulls the AI SDK. When `enabled: false`, the gate is skipped (nothing loads).\n */\nimport { z } from 'zod'\nimport type {\n  AiLimits,\n  AiProvider,\n  KnowledgeSource,\n  StudioAiConfig,\n} from './types'\n\n// --- Structured issues ------------------------------------------------------------\n\nexport const AI_CONFIG_ISSUE_CODES = [\n  'invalid-config-shape',\n  'missing-provider',\n  'provider-missing-capabilities',\n  'provider-not-callable',\n] as const\nexport type AiConfigIssueCode = (typeof AI_CONFIG_ISSUE_CODES)[number]\n\n/** A structured, path-located `ai`-config issue (never thrown — collected). */\nexport interface AiConfigIssue {\n  code: AiConfigIssueCode\n  severity: 'error' | 'warning'\n  message: string\n  path: ReadonlyArray<string | number>\n}\n\n// --- Serializable shape (Zod) -----------------------------------------------------\n\n/** The serializable, JSON-validatable subset of the limits block. */\nexport const aiLimitsSchema = z\n  .object({\n    maxRequestsPerMinute: z.number().int().positive().optional(),\n    maxRepairAttempts: z.number().int().nonnegative().optional(),\n  })\n  .strict()\n\n// --- Resolution -------------------------------------------------------------------\n\nexport interface ResolvedAiConfig {\n  /** Whether the feature is active (present + not `enabled: false`). */\n  enabled: boolean\n  provider: AiProvider\n  knowledge: KnowledgeSource[]\n  limits: AiLimits\n}\n\nexport interface ResolveAiConfigResult {\n  /** True when no error-severity issue is present. */\n  ok: boolean\n  /** The resolved config; present only when `ok`. */\n  resolved?: ResolvedAiConfig\n  issues: AiConfigIssue[]\n}\n\n/** Non-throwing structural test that a value looks like an {@link AiProvider}. */\nfunction looksLikeProvider(value: unknown): value is AiProvider {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof (value as AiProvider).id === 'string' &&\n    typeof (value as AiProvider).capabilities === 'function' &&\n    typeof (value as AiProvider).generateStructured === 'function'\n  )\n}\n\n/**\n * The capability gate: a provider must declare tool calling + structured output.\n * Returns the blocking issues (empty when the provider satisfies the gate).\n */\nexport function assertProviderCapabilities(provider: AiProvider): AiConfigIssue[] {\n  const issues: AiConfigIssue[] = []\n  let caps\n  try {\n    caps = provider.capabilities()\n  } catch {\n    return [\n      {\n        code: 'provider-not-callable',\n        severity: 'error',\n        message: `AI provider \"${provider.id}\" threw while reporting its capabilities.`,\n        path: ['ai', 'provider', 'capabilities'],\n      },\n    ]\n  }\n  const missing: string[] = []\n  if (!caps?.toolCalling) missing.push('tool calling')\n  if (!caps?.structuredOutput) missing.push('structured output')\n  if (missing.length > 0) {\n    issues.push({\n      code: 'provider-missing-capabilities',\n      severity: 'error',\n      message: `AI provider \"${provider.id}\" is missing required capabilities: ${missing.join(\n        ', ',\n      )}. Tool calling and structured output are required.`,\n      path: ['ai', 'provider'],\n    })\n  }\n  return issues\n}\n\n/**\n * Resolve + validate a `defineStudio({ ai })` block. Deterministic; never throws.\n * The capability gate runs only when the feature is enabled (a disabled block loads\n * nothing). A `null`/`undefined` block resolves to a disabled, ok result — callers\n * treat that as \"feature absent\".\n */\nexport function resolveAiConfig(config: StudioAiConfig | null | undefined): ResolveAiConfigResult {\n  const issues: AiConfigIssue[] = []\n  if (!config) {\n    return { ok: true, issues }\n  }\n\n  // Serializable shape: limits (Zod). Shape failure is terminal for that field only.\n  let limits: AiLimits = {}\n  if (config.limits !== undefined) {\n    const parsed = aiLimitsSchema.safeParse(config.limits)\n    if (!parsed.success) {\n      for (const issue of parsed.error.issues) {\n        issues.push({\n          code: 'invalid-config-shape',\n          severity: 'error',\n          message: issue.message,\n          path: ['ai', 'limits', ...issue.path.map((p) => (typeof p === 'symbol' ? String(p) : p))],\n        })\n      }\n    } else {\n      limits = parsed.data\n    }\n  }\n\n  const enabled = config.enabled !== false\n\n  // Provider presence + capability gate (live code — validated, not shape-parsed).\n  if (!looksLikeProvider(config.provider)) {\n    issues.push({\n      code: 'missing-provider',\n      severity: 'error',\n      message:\n        'defineStudio({ ai }) requires a `provider` with `id`, `capabilities()`, and `generateStructured()`.',\n      path: ['ai', 'provider'],\n    })\n  } else if (enabled) {\n    issues.push(...assertProviderCapabilities(config.provider))\n  }\n\n  const ok = !issues.some((i) => i.severity === 'error')\n  if (!ok) return { ok, issues }\n\n  return {\n    ok,\n    issues,\n    resolved: {\n      enabled,\n      provider: config.provider,\n      knowledge: config.knowledge ?? [],\n      limits,\n    },\n  }\n}\n\n/** True when a resolved-config result has no error-severity issues. */\nexport function isAiConfigValid(result: ResolveAiConfigResult): boolean {\n  return result.ok\n}\n"]}

package/dist/lib/ai/fake-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * FakeProvider (EC-331): a deterministic, fixture-driven {@link AiProvider} that
+ * implements the same interface as the Anthropic provider, so playground / demo /
+ * tests run the WHOLE loop (config gate → shape → generate → validate → repair →
+ * patch) without a key. Determinism is a project principle: the same fixtures always
+ * yield the same result. Imports no AI SDK.
+ *
+ * For the repair loop, pass `objects: [invalidDoc, validDoc]` — the provider returns
+ * them in call order (the last is reused once the script is exhausted). Or pass
+ * `respond` to compute the object from the request.
+ */
+import type { AiProvider, AiProviderCapabilities, GenerateStructuredRequest, StreamChatRequest } from './types';
+export interface FakeProviderOptions {
+    /** Provider id (default `fake`). */
+    id?: string;
+    /** Model id recorded in provenance (default `fake-model`). */
+    model?: string;
+    /** Reported capabilities (default: both true). Set to test the capability gate. */
+    capabilities?: AiProviderCapabilities;
+    /** Scripted objects returned in call order; the last entry is reused when exhausted. */
+    objects?: unknown[];
+    /** Compute the object from the request + zero-based call index (overrides `objects`). */
+    respond?: (request: GenerateStructuredRequest, callIndex: number) => unknown;
+    /** Fixed text `streamChat` streams back (default: echoes the last user message). */
+    streamText?: string;
+}
+/** A FakeProvider that also records the requests it received, for assertions. */
+export interface FakeProvider extends AiProvider {
+    /** Every `generateStructured` request received, in order. */
+    readonly calls: GenerateStructuredRequest[];
+    /** Every `streamChat` request received, in order. */
+    readonly streamCalls: StreamChatRequest[];
+}
+export declare function createFakeProvider(options?: FakeProviderOptions): FakeProvider;

package/dist/lib/ai/fake-provider.js

@@ -0,0 +1,31 @@
+export function createFakeProvider(options = {}) {
+    const calls = [];
+    const streamCalls = [];
+    const objects = options.objects ?? [];
+    let index = 0;
+    return {
+        id: options.id ?? 'fake',
+        model: options.model ?? 'fake-model',
+        calls,
+        streamCalls,
+        capabilities: () => options.capabilities ?? { toolCalling: true, structuredOutput: true },
+        generateStructured(request) {
+            calls.push(request);
+            const callIndex = index;
+            index += 1;
+            const object = options.respond
+                ? options.respond(request, callIndex)
+                : objects.length > 0
+                    ? objects[Math.min(callIndex, objects.length - 1)]
+                    : {};
+            return Promise.resolve({ object, usage: { inputTokens: 0, outputTokens: 0 } });
+        },
+        streamChat(request) {
+            streamCalls.push(request);
+            const last = request.messages.filter((m) => m.role === 'user').at(-1);
+            const text = options.streamText ?? last?.content ?? '';
+            return Promise.resolve(new Response(text, { headers: { 'content-type': 'text/plain; charset=utf-8' } }));
+        },
+    };
+}
+//# sourceMappingURL=fake-provider.js.map

package/dist/lib/ai/fake-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-provider.js","sourceRoot":"","sources":["../../../src/lib/ai/fake-provider.ts"],"names":[],"mappings":"AAyCA,MAAM,UAAU,kBAAkB,CAAC,UAA+B,EAAE;IAClE,MAAM,KAAK,GAAgC,EAAE,CAAA;IAC7C,MAAM,WAAW,GAAwB,EAAE,CAAA;IAC3C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAA;IACrC,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,MAAM;QACxB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,YAAY;QACpC,KAAK;QACL,WAAW;QACX,YAAY,EAAE,GAA2B,EAAE,CACzC,OAAO,CAAC,YAAY,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE;QAEvE,kBAAkB,CAAC,OAAO;YACxB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACnB,MAAM,SAAS,GAAG,KAAK,CAAA;YACvB,KAAK,IAAI,CAAC,CAAA;YACV,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO;gBAC5B,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC;gBACrC,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;oBAClB,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;oBAClD,CAAC,CAAC,EAAE,CAAA;YACR,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;QAChF,CAAC;QAED,UAAU,CAAC,OAAO;YAChB,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACzB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAA;YACrE,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,EAAE,OAAO,IAAI,EAAE,CAAA;YACtD,OAAO,OAAO,CAAC,OAAO,CACpB,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,EAAE,CAAC,CACjF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["/**\n * FakeProvider (EC-331): a deterministic, fixture-driven {@link AiProvider} that\n * implements the same interface as the Anthropic provider, so playground / demo /\n * tests run the WHOLE loop (config gate → shape → generate → validate → repair →\n * patch) without a key. Determinism is a project principle: the same fixtures always\n * yield the same result. Imports no AI SDK.\n *\n * For the repair loop, pass `objects: [invalidDoc, validDoc]` — the provider returns\n * them in call order (the last is reused once the script is exhausted). Or pass\n * `respond` to compute the object from the request.\n */\nimport type {\n  AiProvider,\n  AiProviderCapabilities,\n  GenerateStructuredRequest,\n  StreamChatRequest,\n} from './types'\n\nexport interface FakeProviderOptions {\n  /** Provider id (default `fake`). */\n  id?: string\n  /** Model id recorded in provenance (default `fake-model`). */\n  model?: string\n  /** Reported capabilities (default: both true). Set to test the capability gate. */\n  capabilities?: AiProviderCapabilities\n  /** Scripted objects returned in call order; the last entry is reused when exhausted. */\n  objects?: unknown[]\n  /** Compute the object from the request + zero-based call index (overrides `objects`). */\n  respond?: (request: GenerateStructuredRequest, callIndex: number) => unknown\n  /** Fixed text `streamChat` streams back (default: echoes the last user message). */\n  streamText?: string\n}\n\n/** A FakeProvider that also records the requests it received, for assertions. */\nexport interface FakeProvider extends AiProvider {\n  /** Every `generateStructured` request received, in order. */\n  readonly calls: GenerateStructuredRequest[]\n  /** Every `streamChat` request received, in order. */\n  readonly streamCalls: StreamChatRequest[]\n}\n\nexport function createFakeProvider(options: FakeProviderOptions = {}): FakeProvider {\n  const calls: GenerateStructuredRequest[] = []\n  const streamCalls: StreamChatRequest[] = []\n  const objects = options.objects ?? []\n  let index = 0\n\n  return {\n    id: options.id ?? 'fake',\n    model: options.model ?? 'fake-model',\n    calls,\n    streamCalls,\n    capabilities: (): AiProviderCapabilities =>\n      options.capabilities ?? { toolCalling: true, structuredOutput: true },\n\n    generateStructured(request) {\n      calls.push(request)\n      const callIndex = index\n      index += 1\n      const object = options.respond\n        ? options.respond(request, callIndex)\n        : objects.length > 0\n          ? objects[Math.min(callIndex, objects.length - 1)]\n          : {}\n      return Promise.resolve({ object, usage: { inputTokens: 0, outputTokens: 0 } })\n    },\n\n    streamChat(request) {\n      streamCalls.push(request)\n      const last = request.messages.filter((m) => m.role === 'user').at(-1)\n      const text = options.streamText ?? last?.content ?? ''\n      return Promise.resolve(\n        new Response(text, { headers: { 'content-type': 'text/plain; charset=utf-8' } }),\n      )\n    },\n  }\n}\n"]}

package/dist/lib/ai/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@elytracms/studio/lib/ai` — the headless AI platform seam (EC-331, phase 1).
+ *
+ * Public surface: the config gate, the provider adapters (Anthropic + Fake), the
+ * knowledge mechanism, the target-shape derivation, the `applyContentWithShape`
+ * engine, the server-route factory, and the provenance seam. No chat UI here.
+ *
+ * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —
+ * only `anthropic-provider` touches them, via dynamic `import()`. So importing this
+ * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block
+ * (which only references `StudioAiConfig` as a type) reaches none of it.
+ */
+export declare const PACKAGE = "@elytracms/studio/lib/ai";
+export * from './types';
+export * from './config';
+export * from './provenance';
+export * from './knowledge';
+export * from './shape';
+export * from './apply-content';
+export * from './anthropic-provider';
+export * from './fake-provider';
+export * from './route';

package/dist/lib/ai/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@elytracms/studio/lib/ai` — the headless AI platform seam (EC-331, phase 1).
+ *
+ * Public surface: the config gate, the provider adapters (Anthropic + Fake), the
+ * knowledge mechanism, the target-shape derivation, the `applyContentWithShape`
+ * engine, the server-route factory, and the provenance seam. No chat UI here.
+ *
+ * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —
+ * only `anthropic-provider` touches them, via dynamic `import()`. So importing this
+ * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block
+ * (which only references `StudioAiConfig` as a type) reaches none of it.
+ */
+export const PACKAGE = '@elytracms/studio/lib/ai';
+export * from './types';
+export * from './config';
+export * from './provenance';
+export * from './knowledge';
+export * from './shape';
+export * from './apply-content';
+export * from './anthropic-provider';
+export * from './fake-provider';
+export * from './route';
+//# sourceMappingURL=index.js.map

package/dist/lib/ai/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/ai/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,0BAA0B,CAAA;AAEjD,cAAc,SAAS,CAAA;AACvB,cAAc,UAAU,CAAA;AACxB,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA;AACvB,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,SAAS,CAAA","sourcesContent":["/**\n * `@elytracms/studio/lib/ai` — the headless AI platform seam (EC-331, phase 1).\n *\n * Public surface: the config gate, the provider adapters (Anthropic + Fake), the\n * knowledge mechanism, the target-shape derivation, the `applyContentWithShape`\n * engine, the server-route factory, and the provenance seam. No chat UI here.\n *\n * Bundle discipline: nothing exported here statically imports `ai` / `@ai-sdk/*` —\n * only `anthropic-provider` touches them, via dynamic `import()`. So importing this\n * barrel never eagerly loads the AI SDK, and a studio without an `ai` config block\n * (which only references `StudioAiConfig` as a type) reaches none of it.\n */\nexport const PACKAGE = '@elytracms/studio/lib/ai'\n\nexport * from './types'\nexport * from './config'\nexport * from './provenance'\nexport * from './knowledge'\nexport * from './shape'\nexport * from './apply-content'\nexport * from './anthropic-provider'\nexport * from './fake-provider'\nexport * from './route'\n"]}

package/dist/lib/ai/knowledge.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Knowledge mechanism (EC-331): `ai.knowledge: KnowledgeSource[]` resolution +
+ * assembly. Knowledge is a MECHANISM, not a storage policy — a source is an inline
+ * literal (markdown versioned with the repo), an async function, or a
+ * `fromCollection('<id>')` helper for studio-editable prose (content is DATA; only
+ * the mechanism is code). `resolveKnowledge` flattens all three kinds into a
+ * deterministic item list; `assembleKnowledgeBlock` renders the context block the
+ * engine injects. Knowledge is DATA, never instructions (see the engine's stance).
+ */
+import type { KnowledgeCollectionReader, KnowledgeCollectionSource, KnowledgeFn, KnowledgeItem, KnowledgeSource, ResolvedKnowledge } from './types';
+/** `fromCollection('faq')` — sugar for a studio-editable knowledge source. */
+export declare function fromCollection(collectionId: string, options?: {
+    field?: string;
+}): KnowledgeCollectionSource;
+/** A `fromCollection(...)` source. */
+export declare function isKnowledgeCollectionSource(source: KnowledgeSource): source is KnowledgeCollectionSource;
+/** A knowledge function source. */
+export declare function isKnowledgeFn(source: KnowledgeSource): source is KnowledgeFn;
+/** An inline knowledge literal. */
+export declare function isKnowledgeItem(source: KnowledgeSource): source is KnowledgeItem;
+export interface ResolveKnowledgeOptions {
+    /**
+     * Reads prose out of a `fromCollection` source. Wired by the studio/starter-kit to
+     * the operations layer. When absent, collection sources resolve to nothing (the
+     * mechanism is present, but there is no reader to pull the editable content).
+     */
+    readCollection?: KnowledgeCollectionReader;
+}
+/**
+ * Resolve `KnowledgeSource[]` into a flat, ordered {@link ResolvedKnowledge}.
+ * Deterministic per input; never throws — a source that produces nothing simply
+ * contributes no items. Order is preserved (config order = context order).
+ */
+export declare function resolveKnowledge(sources: readonly KnowledgeSource[] | undefined, options?: ResolveKnowledgeOptions): Promise<ResolvedKnowledge>;
+/**
+ * Render resolved knowledge into a markdown context block for the model. Empty
+ * knowledge yields an empty string (the engine then omits the block entirely).
+ */
+export declare function assembleKnowledgeBlock(resolved: ResolvedKnowledge): string;

package/dist/lib/ai/knowledge.js

@@ -0,0 +1,60 @@
+/** `fromCollection('faq')` — sugar for a studio-editable knowledge source. */
+export function fromCollection(collectionId, options = {}) {
+    return {
+        kind: 'collection',
+        collectionId,
+        ...(options.field !== undefined ? { field: options.field } : {}),
+    };
+}
+/** A `fromCollection(...)` source. */
+export function isKnowledgeCollectionSource(source) {
+    return (typeof source === 'object' &&
+        source !== null &&
+        source.kind === 'collection');
+}
+/** A knowledge function source. */
+export function isKnowledgeFn(source) {
+    return typeof source === 'function';
+}
+/** An inline knowledge literal. */
+export function isKnowledgeItem(source) {
+    return (typeof source === 'object' &&
+        source !== null &&
+        !isKnowledgeCollectionSource(source) &&
+        typeof source.content === 'string');
+}
+function toItems(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Resolve `KnowledgeSource[]` into a flat, ordered {@link ResolvedKnowledge}.
+ * Deterministic per input; never throws — a source that produces nothing simply
+ * contributes no items. Order is preserved (config order = context order).
+ */
+export async function resolveKnowledge(sources, options = {}) {
+    const items = [];
+    for (const source of sources ?? []) {
+        if (isKnowledgeFn(source)) {
+            items.push(...toItems(await source()));
+        }
+        else if (isKnowledgeCollectionSource(source)) {
+            if (options.readCollection)
+                items.push(...(await options.readCollection(source)));
+        }
+        else if (isKnowledgeItem(source)) {
+            items.push(source);
+        }
+    }
+    return { items: items.filter((i) => i.content.trim().length > 0) };
+}
+/**
+ * Render resolved knowledge into a markdown context block for the model. Empty
+ * knowledge yields an empty string (the engine then omits the block entirely).
+ */
+export function assembleKnowledgeBlock(resolved) {
+    if (resolved.items.length === 0)
+        return '';
+    const sections = resolved.items.map((item) => item.title ? `## ${item.title}\n${item.content.trim()}` : item.content.trim());
+    return `# Project knowledge\n\n${sections.join('\n\n')}`;
+}
+//# sourceMappingURL=knowledge.js.map

package/dist/lib/ai/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../../src/lib/ai/knowledge.ts"],"names":[],"mappings":"AAkBA,8EAA8E;AAC9E,MAAM,UAAU,cAAc,CAC5B,YAAoB,EACpB,UAA8B,EAAE;IAEhC,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,YAAY;QACZ,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjE,CAAA;AACH,CAAC;AAED,sCAAsC;AACtC,MAAM,UAAU,2BAA2B,CACzC,MAAuB;IAEvB,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACd,MAAoC,CAAC,IAAI,KAAK,YAAY,CAC5D,CAAA;AACH,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,aAAa,CAAC,MAAuB;IACnD,OAAO,OAAO,MAAM,KAAK,UAAU,CAAA;AACrC,CAAC;AAED,mCAAmC;AACnC,MAAM,UAAU,eAAe,CAAC,MAAuB;IACrD,OAAO,CACL,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,2BAA2B,CAAC,MAAM,CAAC;QACpC,OAAQ,MAAwB,CAAC,OAAO,KAAK,QAAQ,CACtD,CAAA;AACH,CAAC;AAED,SAAS,OAAO,CAAC,KAAsC;IACrD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;AAC/C,CAAC;AAWD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAA+C,EAC/C,UAAmC,EAAE;IAErC,MAAM,KAAK,GAAoB,EAAE,CAAA;IACjC,KAAK,MAAM,MAAM,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QACnC,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC,CAAA;QACxC,CAAC;aAAM,IAAI,2BAA2B,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/C,IAAI,OAAO,CAAC,cAAc;gBAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;QACnF,CAAC;aAAM,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACpB,CAAC;IACH,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAA;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAA2B;IAChE,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAC3C,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAC9E,CAAA;IACD,OAAO,0BAA0B,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;AAC1D,CAAC","sourcesContent":["/**\n * Knowledge mechanism (EC-331): `ai.knowledge: KnowledgeSource[]` resolution +\n * assembly. Knowledge is a MECHANISM, not a storage policy — a source is an inline\n * literal (markdown versioned with the repo), an async function, or a\n * `fromCollection('<id>')` helper for studio-editable prose (content is DATA; only\n * the mechanism is code). `resolveKnowledge` flattens all three kinds into a\n * deterministic item list; `assembleKnowledgeBlock` renders the context block the\n * engine injects. Knowledge is DATA, never instructions (see the engine's stance).\n */\nimport type {\n  KnowledgeCollectionReader,\n  KnowledgeCollectionSource,\n  KnowledgeFn,\n  KnowledgeItem,\n  KnowledgeSource,\n  ResolvedKnowledge,\n} from './types'\n\n/** `fromCollection('faq')` — sugar for a studio-editable knowledge source. */\nexport function fromCollection(\n  collectionId: string,\n  options: { field?: string } = {},\n): KnowledgeCollectionSource {\n  return {\n    kind: 'collection',\n    collectionId,\n    ...(options.field !== undefined ? { field: options.field } : {}),\n  }\n}\n\n/** A `fromCollection(...)` source. */\nexport function isKnowledgeCollectionSource(\n  source: KnowledgeSource,\n): source is KnowledgeCollectionSource {\n  return (\n    typeof source === 'object' &&\n    source !== null &&\n    (source as KnowledgeCollectionSource).kind === 'collection'\n  )\n}\n\n/** A knowledge function source. */\nexport function isKnowledgeFn(source: KnowledgeSource): source is KnowledgeFn {\n  return typeof source === 'function'\n}\n\n/** An inline knowledge literal. */\nexport function isKnowledgeItem(source: KnowledgeSource): source is KnowledgeItem {\n  return (\n    typeof source === 'object' &&\n    source !== null &&\n    !isKnowledgeCollectionSource(source) &&\n    typeof (source as KnowledgeItem).content === 'string'\n  )\n}\n\nfunction toItems(value: KnowledgeItem | KnowledgeItem[]): KnowledgeItem[] {\n  return Array.isArray(value) ? value : [value]\n}\n\nexport interface ResolveKnowledgeOptions {\n  /**\n   * Reads prose out of a `fromCollection` source. Wired by the studio/starter-kit to\n   * the operations layer. When absent, collection sources resolve to nothing (the\n   * mechanism is present, but there is no reader to pull the editable content).\n   */\n  readCollection?: KnowledgeCollectionReader\n}\n\n/**\n * Resolve `KnowledgeSource[]` into a flat, ordered {@link ResolvedKnowledge}.\n * Deterministic per input; never throws — a source that produces nothing simply\n * contributes no items. Order is preserved (config order = context order).\n */\nexport async function resolveKnowledge(\n  sources: readonly KnowledgeSource[] | undefined,\n  options: ResolveKnowledgeOptions = {},\n): Promise<ResolvedKnowledge> {\n  const items: KnowledgeItem[] = []\n  for (const source of sources ?? []) {\n    if (isKnowledgeFn(source)) {\n      items.push(...toItems(await source()))\n    } else if (isKnowledgeCollectionSource(source)) {\n      if (options.readCollection) items.push(...(await options.readCollection(source)))\n    } else if (isKnowledgeItem(source)) {\n      items.push(source)\n    }\n  }\n  return { items: items.filter((i) => i.content.trim().length > 0) }\n}\n\n/**\n * Render resolved knowledge into a markdown context block for the model. Empty\n * knowledge yields an empty string (the engine then omits the block entirely).\n */\nexport function assembleKnowledgeBlock(resolved: ResolvedKnowledge): string {\n  if (resolved.items.length === 0) return ''\n  const sections = resolved.items.map((item) =>\n    item.title ? `## ${item.title}\\n${item.content.trim()}` : item.content.trim(),\n  )\n  return `# Project knowledge\\n\\n${sections.join('\\n\\n')}`\n}\n"]}

package/dist/lib/ai/provenance.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Provenance seam (EC-331). AI-authored content carries an origin marker the
+ * draft-write path records so an assistant-authored draft is attributable in
+ * history — distinct from a human edit.
+ *
+ * There is no document-level or draft-level origin field in the store yet (today
+ * only the retired project-`VersionRecord` has `origin: 'edit' | 'import' |
+ * 'rollback'`, and the active per-document `DocumentVersionRecord` carries only
+ * `label`/`createdAt`). Phase 1 defines the seam minimally: the engine attaches
+ * this marker to its result; wiring it into `documents.upsert` /
+ * `DocumentVersionRecord` (and any UI) is deferred to EC-199. No behaviour here.
+ */
+import type { AiProvenance, AiProvider } from './types';
+/** The origin discriminator for assistant-authored writes. */
+export declare const AI_ORIGIN: "assistant";
+/**
+ * Build the provenance marker for an engine run. `at` defaults to now (ISO); a
+ * fixed clock can be injected for deterministic tests.
+ */
+export declare function aiProvenance(provider: AiProvider, at?: string): AiProvenance;

package/dist/lib/ai/provenance.js

@@ -0,0 +1,15 @@
+/** The origin discriminator for assistant-authored writes. */
+export const AI_ORIGIN = 'assistant';
+/**
+ * Build the provenance marker for an engine run. `at` defaults to now (ISO); a
+ * fixed clock can be injected for deterministic tests.
+ */
+export function aiProvenance(provider, at = new Date().toISOString()) {
+    return {
+        origin: AI_ORIGIN,
+        provider: provider.id,
+        ...(provider.model !== undefined ? { model: provider.model } : {}),
+        at,
+    };
+}
+//# sourceMappingURL=provenance.js.map

package/dist/lib/ai/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../../src/lib/ai/provenance.ts"],"names":[],"mappings":"AAcA,8DAA8D;AAC9D,MAAM,CAAC,MAAM,SAAS,GAAG,WAAoB,CAAA;AAE7C;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,QAAoB,EAAE,KAAa,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IACtF,OAAO;QACL,MAAM,EAAE,SAAS;QACjB,QAAQ,EAAE,QAAQ,CAAC,EAAE;QACrB,GAAG,CAAC,QAAQ,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,EAAE;KACH,CAAA;AACH,CAAC","sourcesContent":["/**\n * Provenance seam (EC-331). AI-authored content carries an origin marker the\n * draft-write path records so an assistant-authored draft is attributable in\n * history — distinct from a human edit.\n *\n * There is no document-level or draft-level origin field in the store yet (today\n * only the retired project-`VersionRecord` has `origin: 'edit' | 'import' |\n * 'rollback'`, and the active per-document `DocumentVersionRecord` carries only\n * `label`/`createdAt`). Phase 1 defines the seam minimally: the engine attaches\n * this marker to its result; wiring it into `documents.upsert` /\n * `DocumentVersionRecord` (and any UI) is deferred to EC-199. No behaviour here.\n */\nimport type { AiProvenance, AiProvider } from './types'\n\n/** The origin discriminator for assistant-authored writes. */\nexport const AI_ORIGIN = 'assistant' as const\n\n/**\n * Build the provenance marker for an engine run. `at` defaults to now (ISO); a\n * fixed clock can be injected for deterministic tests.\n */\nexport function aiProvenance(provider: AiProvider, at: string = new Date().toISOString()): AiProvenance {\n  return {\n    origin: AI_ORIGIN,\n    provider: provider.id,\n    ...(provider.model !== undefined ? { model: provider.model } : {}),\n    at,\n  }\n}\n"]}

package/dist/lib/ai/route.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Server-route factory (EC-331): a streaming chat/completion endpoint the consuming
+ * studio app mounts. Key custody = host route (never the browser, never Convex): the
+ * `provider` holds the host-env key and this handler is a THIN model proxy — NO data
+ * access, NO service credentials.
+ *
+ * Framework-agnostic on purpose: it returns a Web `Request → Response` handler the
+ * host wires into whatever server entry it has (a TanStack Start server route, a
+ * Convex `httpAction`, a plain fetch handler). The current demo studio builds as a
+ * pure client SPA with server functions disabled (EC-234), so actually mounting this
+ * is an EC-199 integration step; phase 1 ships the handler + its contract.
+ *
+ * Session-gated: `getSession` (host-wired, reading its own auth — this module never
+ * touches `lib/auth`) must return a session for authenticated callers; anonymous
+ * callers are rejected. Plus a soft, in-memory per-project rate counter (spend guard).
+ */
+import type { AiRouteHandler, AiRouteHandlerOptions } from './types';
+/**
+ * Build the mounted route handler. The returned function is a plain
+ * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin
+ * proxy to `provider.streamChat`. Never throws to the caller: every failure is a
+ * structured JSON response with an appropriate status.
+ */
+export declare function createAiRouteHandler(options: AiRouteHandlerOptions): AiRouteHandler;

package/dist/lib/ai/route.js

@@ -0,0 +1,90 @@
+function jsonResponse(value, status) {
+    return new Response(JSON.stringify(value), {
+        status,
+        headers: { 'content-type': 'application/json' },
+    });
+}
+function isChatMessage(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    return ((m.role === 'system' || m.role === 'user' || m.role === 'assistant') &&
+        typeof m.content === 'string');
+}
+/** Parse a request body into a {@link StreamChatRequest}, or `null` when malformed. */
+function parseChatBody(body) {
+    if (typeof body !== 'object' || body === null)
+        return null;
+    const { messages, system } = body;
+    if (!Array.isArray(messages) || messages.length === 0 || !messages.every(isChatMessage)) {
+        return null;
+    }
+    return {
+        messages: messages,
+        ...(typeof system === 'string' ? { system } : {}),
+    };
+}
+/**
+ * Build the mounted route handler. The returned function is a plain
+ * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin
+ * proxy to `provider.streamChat`. Never throws to the caller: every failure is a
+ * structured JSON response with an appropriate status.
+ */
+export function createAiRouteHandler(options) {
+    const maxPerMinute = options.limits?.maxRequestsPerMinute;
+    const buckets = new Map();
+    const projectKey = options.projectKey ?? (() => 'global');
+    function rateLimited(key) {
+        if (maxPerMinute === undefined || maxPerMinute <= 0)
+            return false;
+        const now = Date.now();
+        const bucket = buckets.get(key);
+        if (!bucket || now - bucket.windowStart >= 60_000) {
+            buckets.set(key, { windowStart: now, count: 1 });
+            return false;
+        }
+        bucket.count += 1;
+        return bucket.count > maxPerMinute;
+    }
+    return async (request) => {
+        // 1. Session gate — reject anonymous callers (the route holds spend, not data).
+        let session;
+        try {
+            session = await options.getSession(request);
+        }
+        catch {
+            return jsonResponse({ error: 'unauthorized' }, 401);
+        }
+        if (!session)
+            return jsonResponse({ error: 'unauthorized' }, 401);
+        // 2. Method.
+        if (request.method !== 'POST')
+            return jsonResponse({ error: 'method-not-allowed' }, 405);
+        // 3. Soft per-project rate / spend counter.
+        if (rateLimited(projectKey(request)))
+            return jsonResponse({ error: 'rate-limited' }, 429);
+        // 4. Body → chat request.
+        let body;
+        try {
+            body = await request.json();
+        }
+        catch {
+            return jsonResponse({ error: 'invalid-json' }, 400);
+        }
+        const chat = parseChatBody(body);
+        if (!chat) {
+            return jsonResponse({ error: 'invalid-request', message: 'expected { messages: AiChatMessage[] }' }, 400);
+        }
+        // 5. Thin proxy to the provider stream.
+        if (!options.provider.streamChat) {
+            return jsonResponse({ error: 'provider-cannot-stream' }, 501);
+        }
+        try {
+            return await options.provider.streamChat(chat);
+        }
+        catch {
+            return jsonResponse({ error: 'provider-error' }, 502);
+        }
+    };
+}
+//# sourceMappingURL=route.js.map

package/dist/lib/ai/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../src/lib/ai/route.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Server-route factory (EC-331): a streaming chat/completion endpoint the consuming\n * studio app mounts. Key custody = host route (never the browser, never Convex): the\n * `provider` holds the host-env key and this handler is a THIN model proxy — NO data\n * access, NO service credentials.\n *\n * Framework-agnostic on purpose: it returns a Web `Request → Response` handler the\n * host wires into whatever server entry it has (a TanStack Start server route, a\n * Convex `httpAction`, a plain fetch handler). The current demo studio builds as a\n * pure client SPA with server functions disabled (EC-234), so actually mounting this\n * is an EC-199 integration step; phase 1 ships the handler + its contract.\n *\n * Session-gated: `getSession` (host-wired, reading its own auth — this module never\n * touches `lib/auth`) must return a session for authenticated callers; anonymous\n * callers are rejected. Plus a soft, in-memory per-project rate counter (spend guard).\n */\nimport type {\n  AiChatMessage,\n  AiRouteHandler,\n  AiRouteHandlerOptions,\n  AiSession,\n  StreamChatRequest,\n} from './types'\n\nfunction jsonResponse(value: unknown, status: number): Response {\n  return new Response(JSON.stringify(value), {\n    status,\n    headers: { 'content-type': 'application/json' },\n  })\n}\n\ninterface RateBucket {\n  windowStart: number\n  count: number\n}\n\nfunction isChatMessage(value: unknown): value is AiChatMessage {\n  if (typeof value !== 'object' || value === null) return false\n  const m = value as { role?: unknown; content?: unknown }\n  return (\n    (m.role === 'system' || m.role === 'user' || m.role === 'assistant') &&\n    typeof m.content === 'string'\n  )\n}\n\n/** Parse a request body into a {@link StreamChatRequest}, or `null` when malformed. */\nfunction parseChatBody(body: unknown): StreamChatRequest | null {\n  if (typeof body !== 'object' || body === null) return null\n  const { messages, system } = body as { messages?: unknown; system?: unknown }\n  if (!Array.isArray(messages) || messages.length === 0 || !messages.every(isChatMessage)) {\n    return null\n  }\n  return {\n    messages: messages as AiChatMessage[],\n    ...(typeof system === 'string' ? { system } : {}),\n  }\n}\n\n/**\n * Build the mounted route handler. The returned function is a plain\n * `(Request) => Promise<Response>` — session-gated, soft-rate-limited, and a thin\n * proxy to `provider.streamChat`. Never throws to the caller: every failure is a\n * structured JSON response with an appropriate status.\n */\nexport function createAiRouteHandler(options: AiRouteHandlerOptions): AiRouteHandler {\n  const maxPerMinute = options.limits?.maxRequestsPerMinute\n  const buckets = new Map<string, RateBucket>()\n  const projectKey = options.projectKey ?? (() => 'global')\n\n  function rateLimited(key: string): boolean {\n    if (maxPerMinute === undefined || maxPerMinute <= 0) return false\n    const now = Date.now()\n    const bucket = buckets.get(key)\n    if (!bucket || now - bucket.windowStart >= 60_000) {\n      buckets.set(key, { windowStart: now, count: 1 })\n      return false\n    }\n    bucket.count += 1\n    return bucket.count > maxPerMinute\n  }\n\n  return async (request: Request): Promise<Response> => {\n    // 1. Session gate — reject anonymous callers (the route holds spend, not data).\n    let session: AiSession | null\n    try {\n      session = await options.getSession(request)\n    } catch {\n      return jsonResponse({ error: 'unauthorized' }, 401)\n    }\n    if (!session) return jsonResponse({ error: 'unauthorized' }, 401)\n\n    // 2. Method.\n    if (request.method !== 'POST') return jsonResponse({ error: 'method-not-allowed' }, 405)\n\n    // 3. Soft per-project rate / spend counter.\n    if (rateLimited(projectKey(request))) return jsonResponse({ error: 'rate-limited' }, 429)\n\n    // 4. Body → chat request.\n    let body: unknown\n    try {\n      body = await request.json()\n    } catch {\n      return jsonResponse({ error: 'invalid-json' }, 400)\n    }\n    const chat = parseChatBody(body)\n    if (!chat) {\n      return jsonResponse(\n        { error: 'invalid-request', message: 'expected { messages: AiChatMessage[] }' },\n        400,\n      )\n    }\n\n    // 5. Thin proxy to the provider stream.\n    if (!options.provider.streamChat) {\n      return jsonResponse({ error: 'provider-cannot-stream' }, 501)\n    }\n    try {\n      return await options.provider.streamChat(chat)\n    } catch {\n      return jsonResponse({ error: 'provider-error' }, 502)\n    }\n  }\n}\n"]}