@mesofact/runtime 0.8.29

package/dist/routes.d.ts

@@ -0,0 +1,67 @@
+import { type HooksConfig } from "./hooks.js";
+export type RouteMode = "static" | "ssr" | "spa";
+export type Placement = "host" | "edge" | "auto";
+export type Requires = "user" | "project" | "region";
+export type CachePolicyConfig = {
+    ttl: number;
+    swr?: number;
+    negative_ttl?: number;
+    vary?: readonly string[];
+};
+export type RetryOn = "connection" | "5xx" | "any";
+export type RetryPolicy = {
+    attempts: number;
+    backoff_ms: readonly number[];
+    retry_on?: RetryOn;
+    budget_ms?: number;
+};
+export type QueuePolicy = {
+    queue: string;
+    ack: "on_enqueue" | "on_origin_2xx";
+    max_delay_ms?: number;
+};
+export type ResiliencePolicy = {
+    retry?: RetryPolicy;
+    queue?: QueuePolicy;
+    timeout_ms?: number;
+};
+export declare const DEFAULT_RESILIENCE_TIMEOUT_MS = 30000;
+export type PrerenderConfig = {
+    params: ReadonlyArray<Record<string, string>>;
+} | {
+    from: string;
+    query: string;
+    param: string;
+} | {
+    from_data: string;
+    items_key: string;
+    param: string;
+} | {
+    deferred: true;
+};
+export type RouteEntry = {
+    route: string;
+    mode: RouteMode;
+    entrypoint: string;
+    client_entrypoint?: string;
+    requires?: readonly Requires[];
+    source_reads?: readonly string[];
+    data_inputs?: readonly string[];
+    cache_policy: CachePolicyConfig;
+    concurrency?: number;
+    prerender?: PrerenderConfig;
+    placement?: Placement;
+    resilience?: ResiliencePolicy;
+};
+export type ErrorRoutes = {
+    "404"?: string;
+    "5xx"?: string;
+};
+export type RoutesConfig = {
+    routes: readonly RouteEntry[];
+    error_routes?: ErrorRoutes;
+    hooks?: HooksConfig;
+    site_url?: string;
+};
+export declare function defineRoutes(config: RoutesConfig): RoutesConfig;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAiC,KAAK,WAAW,EAAc,MAAM,YAAY,CAAC;AAEzF,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,KAAK,CAAC;AAOjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B,CAAC;AASF,MAAM,MAAM,OAAO,GAAG,YAAY,GAAG,KAAK,GAAG,KAAK,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IAExB,QAAQ,EAAE,MAAM,CAAC;IAEjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAG9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IAGnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,YAAY,GAAG,eAAe,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,KAAK,CAAC,EAAE,WAAW,CAAC;IAEpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAGF,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAsBpD,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAkBvB,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IAInB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAG/B,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAIjC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,YAAY,EAAE,iBAAiB,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,eAAe,CAAC;IAG5B,SAAS,CAAC,EAAE,SAAS,CAAC;IAMtB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9B,YAAY,CAAC,EAAE,WAAW,CAAC;IAM3B,KAAK,CAAC,EAAE,WAAW,CAAC;IAMpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAyC/D"}

package/dist/routes.js

@@ -0,0 +1,130 @@
+//! @yah:relay(R015, "Render cube support — placement axis + SSR build path + lint (W173)")
+//! @yah:at(2026-06-04T19:31:37Z)
+//! @yah:status(open)
+//! @yah:next("W173 lives in the yah parent camp at .yah/docs/working/W173-mesofact-render-cube.md (relative from mesofact root: ../../.yah/docs/working/W173-mesofact-render-cube.md). Read § 'v1 schema delta' and § 'SSR_PREFIXES derivation rule' before T1/T2.")
+//! @yah:next("yah-side consumer relay is R434 in the parent camp — R434-F3 (mesofact-dev SSR subprocess), R434-F4 (pond reconciler ssr_runtime), R434-F5 (first SSR consumer route) all assume this relay ships first.")
+//! @yah:next("Coordinate handoff via @mesofact/runtime version bump: yah-side consumes via packages/yah/workload-spec/index.ts and crates/yah/cloud/src/reconciler/mesofact_static.rs.")
+//! @yah:next("Order: T1 (schema) → T2 (build path) → then T3 + T4 unblock once a real SSR consumer exists on the yah side (R434-F5).")
+//!
+//! @yah:ticket(R015-F1, "Add Placement axis + placement?: field to RouteEntry + defineRoutes validation")
+//! @yah:assignee(agent:claude)
+//! @yah:at(2026-06-04T19:32:10Z)
+//! @yah:status(review)
+//! @yah:phase(P1)
+//! @yah:parent(R015)
+//! @yah:next("Add `export type Placement = \"host\" | \"edge\" | \"auto\"` alongside the existing RouteMode at routes.ts:5.")
+//! @yah:next("Add `placement?: Placement` to RouteEntry. ssr-only — reject (loud, at defineRoutes call site) on any non-\"ssr\" mode. Default \"auto\" → \"host\" today (auto-classifier deferred per W173).")
+//! @yah:next("RouteMode \"ssr\" slot already exists in this file — do NOT regress it. Do not remove or rename existing fields (requires, source_reads, concurrency, prerender, cache_policy.negative_ttl/vary).")
+//! @yah:next("Add a unit test that defineRoutes throws when placement is set on a static or spa route.")
+//! @yah:next("Place where the build classifier eventually slots in: comment that `placement: \"auto\"` resolves to \"host\" until the auto-classifier (W173 § 'Future auto-classifier criteria') lands.")
+//! @yah:verify("defineRoutes accepts every existing yah-side routes file (../../app/yah/web/marketing/mesofact.routes.ts and ../../app/yah/web/dashboard/mesofact.routes.ts) unchanged")
+//! @yah:verify("defineRoutes throws on `mode:\"static\", placement:\"host\"` etc.")
+//! @yah:verify("bun test passes for the new placement validation cases")
+//! @yah:handoff("Placement axis shipped. Changes to packages/mesofact-runtime/src/routes.ts: added `export type Placement = \"host\" | \"edge\" | \"auto\"`; added `placement?: Placement` to RouteEntry; defineRoutes now throws when placement is set on a non-ssr route (loud, names the offending route, default left undefined — auto-resolution happens at build time per W173). Exported Placement from src/index.ts. New tests/routes.test.ts covers 8 cases (ssr+host/edge/auto/undefined accepted; static+placement and spa+placement rejected; error message names route; mixed-mode workload accepted). Verified: bun test → 57 pass across 7 files; tsc --noEmit clean for runtime + build + worker; existing yah-side route files (marketing 5, dashboard 7, yah-dev 3) still parse unchanged.")
+//! @yah:verify("cd packages/mesofact-runtime && bun test — 57 pass")
+//! @yah:verify("cd packages/mesofact-runtime && bun run typecheck — clean")
+//! @yah:verify("cd packages/mesofact-build && bun run typecheck — clean")
+//! @yah:verify("cd packages/mesofact-worker && bun run typecheck — clean")
+// `mesofact.routes.ts` — user-authored route table. Build phase 2 reads this,
+// phase 3 infers `source_reads`, phase 4 validates, phase 6 emits the manifest.
+// See `.yah/docs/architecture/mesofact.md` §"Build pipeline".
+import { HOOK_NAMES, HOOK_ROUTE_CLAIMS, isHookName } from "./hooks.js";
+// Default per-attempt timeout used when `resilience.timeout_ms` is omitted.
+export const DEFAULT_RESILIENCE_TIMEOUT_MS = 30_000;
+export function defineRoutes(config) {
+    if (config.site_url !== undefined && !/^https?:\/\/[^/]+/.test(config.site_url)) {
+        throw new Error(`defineRoutes: site_url=${JSON.stringify(config.site_url)} must be an absolute origin like "https://yah.dev" (scheme + host, no trailing path) — the sitemap emitter joins it with each route's path`);
+    }
+    for (const r of config.routes) {
+        if (r.placement !== undefined && r.mode !== "ssr") {
+            throw new Error(`defineRoutes: route ${r.route} has placement=${JSON.stringify(r.placement)} but mode=${JSON.stringify(r.mode)}; placement is only valid on mode:"ssr"`);
+        }
+        if (r.prerender && "from_data" in r.prerender) {
+            const declared = r.data_inputs ?? [];
+            if (!declared.includes(r.prerender.from_data)) {
+                throw new Error(`defineRoutes: route ${r.route} has prerender.from_data=${JSON.stringify(r.prerender.from_data)} but that path is not in data_inputs (${JSON.stringify(declared)}); declare the file in data_inputs first so the build reads it once`);
+            }
+        }
+        if (r.prerender && "deferred" in r.prerender) {
+            if (r.prerender.deferred !== true) {
+                throw new Error(`defineRoutes: route ${r.route} has prerender.deferred=${JSON.stringify(r.prerender.deferred)} — omit prerender (render once at build) or set deferred: true`);
+            }
+            if (r.mode !== "static") {
+                throw new Error(`defineRoutes: route ${r.route} has prerender.deferred but mode=${JSON.stringify(r.mode)}; deferred (publish-time) params are only valid on mode:"static" — ssr renders per request, spa shells are not instance-addressed`);
+            }
+            if (!r.route.includes(":")) {
+                throw new Error(`defineRoutes: route ${r.route} has prerender.deferred but no ":param" segment — a literal route has exactly one instance, rendered at build`);
+            }
+        }
+        if (r.resilience !== undefined)
+            validateResilience(r);
+    }
+    if (config.hooks !== undefined)
+        validateHooks(config);
+    return config;
+}
+// Mode 2 hook declaration (R756-F6). Same fail-fast home as placement and
+// resilience: throw at config import, before any bundling work.
+function validateHooks(config) {
+    const hooks = config.hooks;
+    for (const [name, entrypoint] of Object.entries(hooks)) {
+        if (!isHookName(name)) {
+            throw new Error(`defineRoutes: unknown hook ${JSON.stringify(name)} — known hooks are ${HOOK_NAMES.map((h) => JSON.stringify(h)).join(", ")}. A hook name is engine-defined: only mesofact invokes hooks, so a name it ` +
+                `does not know would never be called.`);
+        }
+        if (typeof entrypoint !== "string" || entrypoint.trim() === "") {
+            throw new Error(`defineRoutes: hooks.${name}=${JSON.stringify(entrypoint)} must be a non-empty entrypoint ` +
+                `path relative to the project root (e.g. "src/${name}.ts")`);
+        }
+        const claimed = HOOK_ROUTE_CLAIMS[name];
+        if (claimed !== undefined && config.routes.some((r) => r.route === claimed)) {
+            throw new Error(`defineRoutes: hook ${JSON.stringify(name)} is declared twice — as hooks.${name} and by ` +
+                `claiming the route ${JSON.stringify(claimed)}. Both mean "this app contributes a ` +
+                `${name} verdict"; pick one. The hooks declaration is usually the one you want — the ` +
+                `module stays out of ssr_prefixes, so the edge never forwards ${claimed} to the SSR ` +
+                `origin and the Rust probe route never shadows it.`);
+        }
+    }
+}
+const RETRY_ON = new Set(["connection", "5xx", "any"]);
+// W181 validation rules. Throws at defineRoutes time (fail fast at config
+// import, before any bundling work — same home as placement rejection).
+function validateResilience(r) {
+    const res = r.resilience;
+    if (r.mode !== "ssr") {
+        throw new Error(`defineRoutes: route ${r.route} declares resilience but mode=${JSON.stringify(r.mode)}; resilience is only valid on mode:"ssr" (the policy wraps the edge→origin proxy hop, which only exists for SSR routes)`);
+    }
+    if (r.placement === "edge") {
+        throw new Error(`defineRoutes: route ${r.route} declares resilience on placement:"edge" — retrying the Worker from the Worker is circular (W181 OQ1); remove the block or use placement:"host"`);
+    }
+    if (res.queue !== undefined) {
+        throw new Error(`defineRoutes: route ${r.route} declares resilience.queue — queue policy is reserved for v2 and not implemented yet (W181 § "v1 scope"); remove the block (the type slot exists so v1 routes won't break when v2 lands)`);
+    }
+    if (res.timeout_ms !== undefined && (!Number.isFinite(res.timeout_ms) || res.timeout_ms <= 0)) {
+        throw new Error(`defineRoutes: route ${r.route} has resilience.timeout_ms=${String(res.timeout_ms)}; expected a positive number of milliseconds`);
+    }
+    const retry = res.retry;
+    if (retry === undefined)
+        return;
+    if (!Number.isInteger(retry.attempts) || retry.attempts < 1) {
+        throw new Error(`defineRoutes: route ${r.route} has resilience.retry.attempts=${String(retry.attempts)}; expected an integer >= 1 (1 = no retry)`);
+    }
+    if (!Array.isArray(retry.backoff_ms) || retry.backoff_ms.length !== retry.attempts - 1) {
+        throw new Error(`defineRoutes: route ${r.route} has resilience.retry.backoff_ms of length ${Array.isArray(retry.backoff_ms) ? retry.backoff_ms.length : "?"}; expected attempts - 1 = ${retry.attempts - 1} entries (one gap between each pair of attempts)`);
+    }
+    if (retry.backoff_ms.some((b) => !Number.isFinite(b) || b < 0)) {
+        throw new Error(`defineRoutes: route ${r.route} has a negative or non-numeric resilience.retry.backoff_ms entry`);
+    }
+    if (retry.retry_on !== undefined && !RETRY_ON.has(retry.retry_on)) {
+        throw new Error(`defineRoutes: route ${r.route} has resilience.retry.retry_on=${JSON.stringify(retry.retry_on)}; expected "connection" | "5xx" | "any"`);
+    }
+    if (retry.budget_ms !== undefined) {
+        const perAttempt = res.timeout_ms ?? DEFAULT_RESILIENCE_TIMEOUT_MS;
+        const backoffSum = retry.backoff_ms.reduce((a, b) => a + b, 0);
+        const floor = backoffSum + retry.attempts * perAttempt;
+        if (retry.budget_ms < floor) {
+            throw new Error(`defineRoutes: route ${r.route} has resilience.retry.budget_ms=${retry.budget_ms} < ${floor} (sum(backoff_ms)=${backoffSum} + attempts=${retry.attempts} × per-attempt timeout=${perAttempt}); raise budget_ms or lower the attempt/timeout shape`);
+        }
+    }
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.js","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"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"}

package/dist/source.d.ts

@@ -0,0 +1,36 @@
+export type ListOpts = {
+    limit?: number;
+    cursor?: string;
+    delimiter?: string;
+};
+export type R2Object = {
+    key: string;
+    size: number;
+    last_modified: string;
+    etag?: string;
+};
+export interface Source {
+    readonly name: string;
+    noTrack(): this;
+    timeout(ms: number): this;
+}
+export interface BlobSource extends Source {
+    fetch(key: string): Promise<Uint8Array | null>;
+    list(prefix: string, opts?: ListOpts): Promise<R2Object[]>;
+}
+export interface KeyValueSource extends Source {
+    get<T>(table: string, id: string): Promise<T | null>;
+    query<T>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+export declare abstract class BaseSource implements Source {
+    readonly name: string;
+    constructor(name: string);
+    noTrack(): this;
+    timeout(ms: number): this;
+    protected consumeOverrides(defaultTimeoutMs: number): {
+        track: boolean;
+        timeout_ms: number;
+    };
+    protected emitTag(tag: string, track: boolean): void;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAGF,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAItB,OAAO,IAAI,IAAI,CAAC;IAIhB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAGD,MAAM,WAAW,UAAW,SAAQ,MAAM;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC5D;AAGD,MAAM,WAAW,cAAe,SAAQ,MAAM;IAC5C,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACrD,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CACzD;AAID,8BAAsB,UAAW,YAAW,MAAM;aACpB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;IAExC,OAAO,IAAI,IAAI;IAMf,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAUzB,SAAS,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG;QACpD,KAAK,EAAE,OAAO,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB;IAcD,SAAS,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAIrD"}

package/dist/source.js

@@ -0,0 +1,52 @@
+// Adapter API surface. Read-only by design — mesofact has no write API.
+// See `.yah/docs/architecture/mesofact.md` §"Adapter API surface".
+//
+// The design doc lists `get`/`query`/`fetch`/`list` on a single interface with
+// per-backend annotations. We split them into BlobSource (r2) and
+// KeyValueSource (sqlite/pg) so callers get type-safety on what they hold:
+// `r2('assets').get(...)` is a type error, not a runtime trap.
+import { currentTrackCtx } from "./track-ctx.js";
+// Shared impl for `.noTrack()` / `.timeout(ms)` and tag emission. Adapters
+// extend this and implement the read methods their backend supports.
+export class BaseSource {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+    noTrack() {
+        const ctx = currentTrackCtx();
+        if (ctx)
+            ctx.next.track = false;
+        return this;
+    }
+    timeout(ms) {
+        const ctx = currentTrackCtx();
+        if (ctx)
+            ctx.next.timeout_ms = ms;
+        return this;
+    }
+    // Consume per-call overrides applied by the most recent `.noTrack()` /
+    // `.timeout(ms)` and return the effective settings for a single read. The
+    // override slot resets after this call, so two chained reads only carry the
+    // override on the first.
+    consumeOverrides(defaultTimeoutMs) {
+        const ctx = currentTrackCtx();
+        if (!ctx)
+            return { track: true, timeout_ms: defaultTimeoutMs };
+        const effective = {
+            track: ctx.next.track,
+            timeout_ms: ctx.next.timeout_ms ?? defaultTimeoutMs,
+        };
+        ctx.next = { track: true };
+        return effective;
+    }
+    // Add a read-set tag to the ambient trackCtx, unless tracking was disabled
+    // for this call or there is no ctx (e.g. test harness running render outside
+    // `runInTrackCtx`).
+    emitTag(tag, track) {
+        if (!track)
+            return;
+        currentTrackCtx()?.tags.add(tag);
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.js","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,kEAAkE;AAClE,2EAA2E;AAC3E,+DAA+D;AAE/D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAwCjD,2EAA2E;AAC3E,qEAAqE;AACrE,MAAM,OAAgB,UAAU;IACF;IAA5B,YAA4B,IAAY;QAAZ,SAAI,GAAJ,IAAI,CAAQ;IAAG,CAAC;IAE5C,OAAO;QACL,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,IAAI,GAAG;YAAE,GAAG,CAAC,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,uEAAuE;IACvE,0EAA0E;IAC1E,4EAA4E;IAC5E,yBAAyB;IACf,gBAAgB,CAAC,gBAAwB;QAIjD,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC;QAC/D,MAAM,SAAS,GAAG;YAChB,KAAK,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK;YACrB,UAAU,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,gBAAgB;SACpD,CAAC;QACF,GAAG,CAAC,IAAI,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,oBAAoB;IACV,OAAO,CAAC,GAAW,EAAE,KAAc;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,eAAe,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/track-ctx.d.ts

@@ -0,0 +1,13 @@
+export type TrackCtx = {
+    readonly tags: Set<string>;
+    next: {
+        track: boolean;
+        timeout_ms?: number;
+    };
+};
+export declare function runInTrackCtx<T>(fn: () => Promise<T>): Promise<{
+    value: T;
+    ctx: TrackCtx;
+}>;
+export declare function currentTrackCtx(): TrackCtx | undefined;
+//# sourceMappingURL=track-ctx.d.ts.map

package/dist/track-ctx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-ctx.d.ts","sourceRoot":"","sources":["../src/track-ctx.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAI3B,IAAI,EAAE;QACJ,KAAK,EAAE,OAAO,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH,CAAC;AAIF,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,CAAC,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,CAAC,CAG3F;AAED,wBAAgB,eAAe,IAAI,QAAQ,GAAG,SAAS,CAEtD"}

package/dist/track-ctx.js

@@ -0,0 +1,15 @@
+// Per-render ambient context. Adapters in this package read it to register
+// read-set tags and honor `.noTrack()` / `.timeout(ms)` overrides. The worker
+// re-exports it for backward compatibility with R005's surface.
+//
+// See `.yah/docs/architecture/mesofact.md` §"Adapter read-set provenance".
+import { AsyncLocalStorage } from "node:async_hooks";
+const storage = new AsyncLocalStorage();
+export function runInTrackCtx(fn) {
+    const ctx = { tags: new Set(), next: { track: true } };
+    return storage.run(ctx, async () => ({ value: await fn(), ctx }));
+}
+export function currentTrackCtx() {
+    return storage.getStore();
+}
+//# sourceMappingURL=track-ctx.js.map

package/dist/track-ctx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-ctx.js","sourceRoot":"","sources":["../src/track-ctx.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAE3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAarD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAY,CAAC;AAElD,MAAM,UAAU,aAAa,CAAI,EAAoB;IACnD,MAAM,GAAG,GAAa,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;IACjE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,OAAO,CAAC,QAAQ,EAAE,CAAC;AAC5B,CAAC"}

package/dist/validate.d.ts

@@ -0,0 +1,20 @@
+import type { Manifest } from "./manifest.js";
+export type SourceScope = "global" | "project" | "user";
+export type SourceCatalog = Record<string, {
+    scope: SourceScope;
+}>;
+export type ValidationErrorKind = "shape" | "unsupported_version" | "mode1_scoped_source" | "mode1_requires_user" | "unknown_hook";
+export type ValidationError = {
+    kind: ValidationErrorKind;
+    path: string;
+    message: string;
+};
+export type ValidationResult = {
+    ok: true;
+    manifest: Manifest;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+export declare function validate(input: unknown, catalog?: SourceCatalog): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,QAAQ,EAKT,MAAM,eAAe,CAAC;AAIvB,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAExD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,qBAAqB,GACrB,qBAAqB,GACrB,qBAAqB,GAKrB,cAAc,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAkR7C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,gBAAgB,CAoEtF"}