@happyvertical/smrt-playbooks 0.51.32 → 0.51.34

package/dist/preflight-types.d.ts

@@ -1,281 +1,147 @@
-import { CapabilityClassification } from '@happyvertical/smrt-types';
-import { CapabilityDeclaration } from '@happyvertical/smrt-types';
-import { SmrtClassOptions } from '@happyvertical/smrt-core';
-
-/**
- * Static layers a browser-plane step is evaluated against.
- *
- * Everything here is a build-time or configuration fact. The generated
- * `authMiddleware` is deliberately absent: it is request-bound, returns a
- * `Response` rather than a boolean, and may consult session stores, rate-limit,
- * or audit — so preflight never invokes it, synthetically or otherwise, and
- * `appAuthConfigured` is the only thing it is allowed to know about it.
- *
- * An `authPredicate` seam (option 1 in #2590) can later be added as an optional
- * member here, turning the `app-auth` layer's `unknown` into a real verdict
- * without changing the report contract.
- */
-export declare interface BrowserPreflightLayerSource {
-    /** `isApiActionEnabled` for the referenced model operation. */
-    isActionExposed(model: string, action: string): boolean;
-    /** `isRoutePublic` for the HTTP method the action maps to. */
-    isRoutePublic(model: string, action: string): boolean;
-    /** Field-level read-permission slugs the step's model declares. */
-    requiredFieldPermissions(model: string, action: string): readonly string[];
-    /** Whether an app-level auth middleware is wired. Never invoked. */
-    appAuthConfigured: boolean;
-}
-
-export declare interface BrowserPreflightOptions {
-    layers: BrowserPreflightLayerSource;
-    /**
-     * The caller's published permission slugs, when the host publishes them.
-     * `null`/absent makes the field layer report `unknown` rather than guess.
-     */
-    permissions?: Iterable<string> | null;
-}
-
-/**
- * A partial override from any layer above the code default. There is no
- * `steps` key, and supplying one is rejected rather than ignored.
- */
-declare interface PlaybookConfigOverrideInput {
-    title?: string | null;
-    description?: string | null;
-    planes?: readonly PlaybookPlane[] | null;
-    onStepFailure?: PlaybookFailurePolicy | null;
-    enabled?: boolean | null;
-    metadata?: PlaybookMetadata | null;
-    [key: string]: unknown;
-}
-
-/**
- * What an agent does when a step fails partway through a plan. Playbooks are
- * scripts, never atomic units, so there is no compensation: the definition
- * says only whether the remainder of the plan is abandoned.
- */
-declare type PlaybookFailurePolicy = 'abort' | 'continue';
-
-/**
- * Record returned by an intent registry for a declared view intent.
- *
- * Seam for #2588: until an intent registry exists, no resolver is supplied and
- * an intent step fails resolution closed.
- */
-declare interface PlaybookIntentRecord {
-    id: string;
-    classification?: CapabilityDeclaration | null;
-    planes?: readonly PlaybookPlane[] | null;
-}
-
-/** Seam for #2588. */
-declare type PlaybookIntentResolver = (id: string) => PlaybookIntentRecord | null | undefined;
-
-/**
- * A step naming a declared view intent by its identity (#2588). Valid only
- * where a surface is mounted.
- */
-declare interface PlaybookIntentStep {
-    kind: 'intent';
-    /** Declared intent identity from the #2588 intent registry. */
-    id: string;
-    label?: string;
-    description?: string;
-    optional?: boolean;
-}
-
-declare type PlaybookMetadata = Record<string, unknown>;
-
-/**
- * Resolves the capability classification of a referenced model operation.
- *
- * Playbooks never classify a step themselves. A host that knows the emitted
- * build-time classification (core's `tool-schema.ts` output, or the runtime
- * manifest) supplies it here; anything it does not know resolves fail-closed
- * to `{ effect: 'destructive', idempotent: false, openWorld: true }`.
- */
-declare type PlaybookOperationClassifier = (step: PlaybookOperationStep) => CapabilityDeclaration | null | undefined;
-
-/**
- * A step naming a model operation by qualified pair — the same qualified
- * form STI discriminators and `@crossPackageRef` already use. Never a
- * generated tool name: that is derived from model, action, and namespace and
- * would silently orphan stored tenant overrides on a namespace change.
- *
- * The step never classifies itself; classification is inherited from the
- * referenced operation (see {@link PlaybookOperationClassifier}).
- */
-declare interface PlaybookOperationStep {
-    kind: 'operation';
-    /** Qualified model name, e.g. `@happyvertical/smrt-commerce:Order`. */
-    model: string;
-    /** Operation name exposed by the model's `@smrt({ api })` surface. */
-    action: string;
-    /** Human-facing label for the agent's narration of this step. */
-    label?: string;
-    /** Longer human-facing description of the step. */
-    description?: string;
-    /** When true, an agent may skip this step without abandoning the plan. */
-    optional?: boolean;
-}
-
-/**
- * Execution planes a playbook can declare validity for.
- *
- * `browser` covers WebMCP / in-page agents driving mounted surfaces;
- * `server` covers Node MCP, CLI, and in-app agents running under
- * `executeAsPrincipal`.
- */
-declare type PlaybookPlane = 'browser' | 'server';
-
-/** One step of a resolved plan, with its inherited classification. */
-declare interface PlaybookPlanStep {
-    index: number;
-    step: PlaybookStep;
-    classification: CapabilityClassification;
-    /** True when the classification is the fail-closed default. */
-    classificationDeclared: boolean;
-}
-
-export declare interface PlaybookPreflightAvailableReport {
-    available: true;
-    /**
-     * Literal `true` on every report, as a type-level reminder: a report is a
-     * prediction, never a grant, and every step is authorized again where it
-     * executes.
-     */
-    advisory: true;
-    key: string;
-    plane: PlaybookPlane;
-    title: string;
-    description: string;
-    verdict: PreflightVerdict;
-    steps: readonly PreflightStepReport[];
-    summary: PreflightSummary;
-}
-
-/** A preflight result. Advisory only — see the two variants above. */
-export declare type PlaybookPreflightReport = PlaybookPreflightAvailableReport | PlaybookPreflightUnavailableReport;
-
-export declare interface PlaybookPreflightRequest {
-    key: string;
-    plane: PlaybookPlane;
-    /**
-     * Opaque, caller-scoped principal identity used to partition the cache. It is
-     * never echoed in the report and never consulted for authority. The cache key
-     * also folds in `resolve.tenantId`, so a principal string need not encode the
-     * tenant to stay correct.
-     */
-    principal: string;
-    /** Options handed to `resolvePlaybook()` — the caller's own layer chain. */
-    resolve?: ResolvePlaybookOptions;
-    /** Evaluates each resolved step. */
-    evaluate: PreflightStepEvaluator;
-}
-
-/**
- * The single, uniform answer for every playbook the caller's own layer chain
- * cannot resolve. An unknown key and an unauthorized key produce this exact
- * frozen value, so preflight is not an enumeration oracle: it carries no key,
- * no plane, and no reason to tell the two apart.
- */
-export declare interface PlaybookPreflightUnavailableReport {
-    available: false;
-    advisory: true;
-    verdict: 'deny';
-    steps: readonly [];
-    summary: PreflightSummary;
-}
-
-/** A playbook step. Exactly two kinds exist in v1; playbooks cannot nest. */
-declare type PlaybookStep = PlaybookOperationStep | PlaybookIntentStep;
-
-/**
- * The authority layers preflight reports on. The two planes are deliberately
- * asymmetric and report different layers:
- *
- * - server plane — `tool-allowlist`, `operation-permission`, and `plane` for an
- *   intent step;
- * - browser plane — `action-exposure`, `public-access`, `field-permissions`,
- *   `app-auth`, and `intent-mount` for an intent step.
- */
-export declare type PreflightLayer = 'tool-allowlist' | 'operation-permission' | 'plane' | 'action-exposure' | 'public-access' | 'field-permissions' | 'app-auth' | 'intent-mount';
-
-/** One authority layer's verdict for one step. */
-export declare interface PreflightLayerReport {
-    layer: PreflightLayer;
-    verdict: PreflightVerdict;
-    reason: PreflightReason;
-    /**
-     * Permission slugs this layer found missing, when it knows them. Present only
-     * on layers that evaluate a slug set.
-     */
-    missingPermissions?: readonly string[];
-}
-
-/** Why a layer reached its verdict. A stable code, never a free-form message. */
-export declare type PreflightReason = 'ok' | 'tool-not-allowed' | 'permission-denied' | 'permission-unknown' | 'plane' | 'action-not-exposed' | 'not-public' | 'auth-required' | 'app-auth-not-evaluated' | 'app-auth-not-configured' | 'fields-redacted' | 'field-permissions-unknown' | 'intent-not-mounted' | 'intent-bridge-not-evaluated' | 'not-evaluated';
-
-/** What a step evaluator returns; `preflightPlan` supplies `index` and `kind`. */
-export declare interface PreflightStepEvaluation {
-    layers: readonly PreflightLayerReport[];
-}
-
-/** Evaluates one resolved plan step without executing any part of it. */
-export declare type PreflightStepEvaluator = (step: PlaybookPlanStep) => PreflightStepEvaluation | Promise<PreflightStepEvaluation>;
-
-/** A step's aggregate verdict plus the per-layer detail behind it. */
-export declare interface PreflightStepReport {
-    index: number;
-    kind: PlaybookStep['kind'];
-    verdict: PreflightVerdict;
-    /** Reason of the first layer that produced the step's aggregate verdict. */
-    reason: PreflightReason;
-    layers: readonly PreflightLayerReport[];
-}
-
-export declare interface PreflightSummary {
-    allow: number;
-    deny: number;
-    unknown: number;
-}
-
-/**
- * Verdict for one authority layer, one step, or a whole plan.
- *
- * `unknown` is a first-class answer, never a rounded-down `allow`: a layer that
- * cannot be evaluated without executing something says so.
- */
-export declare type PreflightVerdict = 'allow' | 'deny' | 'unknown';
-
-declare interface ResolvePlaybookOptions {
-    db?: SmrtClassOptions['db'];
-    tenantId?: string | null;
-    /** Plane the calling agent runs on. Defaults to `'server'`. */
-    plane?: PlaybookPlane;
-    /** Highest-precedence layer, supplied per call. */
-    override?: PlaybookConfigOverrideInput;
-    /** Host-supplied classification source for model-operation steps. */
-    classifier?: PlaybookOperationClassifier;
-    /** Host-supplied intent registry (#2588). */
-    intents?: PlaybookIntentResolver;
-}
-
-export declare interface ServerPreflightOptions {
-    /** `PrincipalRun.isToolAllowed` for the slug that gates this step. */
-    isToolAllowed(step: PlaybookOperationStep): boolean;
-    /**
-     * The operation-permission predicate. Evaluates the catalog gate for the
-     * step's `(collection, action)` without performing the operation.
-     */
-    checkOperationPermission(step: PlaybookOperationStep): PreflightVerdict | Promise<PreflightVerdict>;
-    /** Declared plane validity of a view intent, from the #2588 registry. */
-    intentPlanes?(id: string): readonly PlaybookPlane[] | null | undefined;
-}
-
-export { }
-
-
-declare global {
-    var __smrtPlaybookRegistry: Map<string, PlaybookDefinition> | undefined;
+/**
+ * Preflight contract (issue #2590) — the verdict vocabulary both planes share.
+ *
+ * Kept beside the resolution types rather than inside them because preflight is
+ * a *reader* of a resolved plan: nothing here changes what a playbook is, and
+ * nothing here executes, authorizes, or grants anything.
+ */
+import type { PlaybookOperationStep, PlaybookPlane, PlaybookPlanStep, PlaybookStep, ResolvePlaybookOptions } from './types.js';
+/**
+ * Verdict for one authority layer, one step, or a whole plan.
+ *
+ * `unknown` is a first-class answer, never a rounded-down `allow`: a layer that
+ * cannot be evaluated without executing something says so.
+ */
+export type PreflightVerdict = 'allow' | 'deny' | 'unknown';
+/**
+ * The authority layers preflight reports on. The two planes are deliberately
+ * asymmetric and report different layers:
+ *
+ * - server plane — `tool-allowlist`, `operation-permission`, and `plane` for an
+ *   intent step;
+ * - browser plane — `action-exposure`, `public-access`, `field-permissions`,
+ *   `app-auth`, and `intent-mount` for an intent step.
+ */
+export type PreflightLayer = 'tool-allowlist' | 'operation-permission' | 'plane' | 'action-exposure' | 'public-access' | 'field-permissions' | 'app-auth' | 'intent-mount';
+/** Why a layer reached its verdict. A stable code, never a free-form message. */
+export type PreflightReason = 'ok' | 'tool-not-allowed' | 'permission-denied' | 'permission-unknown' | 'plane' | 'action-not-exposed' | 'not-public' | 'auth-required' | 'app-auth-not-evaluated' | 'app-auth-not-configured' | 'fields-redacted' | 'field-permissions-unknown' | 'intent-not-mounted' | 'intent-bridge-not-evaluated' | 'not-evaluated';
+/** One authority layer's verdict for one step. */
+export interface PreflightLayerReport {
+    layer: PreflightLayer;
+    verdict: PreflightVerdict;
+    reason: PreflightReason;
+    /**
+     * Permission slugs this layer found missing, when it knows them. Present only
+     * on layers that evaluate a slug set.
+     */
+    missingPermissions?: readonly string[];
 }
+/** A step's aggregate verdict plus the per-layer detail behind it. */
+export interface PreflightStepReport {
+    index: number;
+    kind: PlaybookStep['kind'];
+    verdict: PreflightVerdict;
+    /** Reason of the first layer that produced the step's aggregate verdict. */
+    reason: PreflightReason;
+    layers: readonly PreflightLayerReport[];
+}
+/** What a step evaluator returns; `preflightPlan` supplies `index` and `kind`. */
+export interface PreflightStepEvaluation {
+    layers: readonly PreflightLayerReport[];
+}
+/** Evaluates one resolved plan step without executing any part of it. */
+export type PreflightStepEvaluator = (step: PlaybookPlanStep) => PreflightStepEvaluation | Promise<PreflightStepEvaluation>;
+export interface PreflightSummary {
+    allow: number;
+    deny: number;
+    unknown: number;
+}
+export interface PlaybookPreflightAvailableReport {
+    available: true;
+    /**
+     * Literal `true` on every report, as a type-level reminder: a report is a
+     * prediction, never a grant, and every step is authorized again where it
+     * executes.
+     */
+    advisory: true;
+    key: string;
+    plane: PlaybookPlane;
+    title: string;
+    description: string;
+    verdict: PreflightVerdict;
+    steps: readonly PreflightStepReport[];
+    summary: PreflightSummary;
+}
+/**
+ * The single, uniform answer for every playbook the caller's own layer chain
+ * cannot resolve. An unknown key and an unauthorized key produce this exact
+ * frozen value, so preflight is not an enumeration oracle: it carries no key,
+ * no plane, and no reason to tell the two apart.
+ */
+export interface PlaybookPreflightUnavailableReport {
+    available: false;
+    advisory: true;
+    verdict: 'deny';
+    steps: readonly [];
+    summary: PreflightSummary;
+}
+/** A preflight result. Advisory only — see the two variants above. */
+export type PlaybookPreflightReport = PlaybookPreflightAvailableReport | PlaybookPreflightUnavailableReport;
+/**
+ * Static layers a browser-plane step is evaluated against.
+ *
+ * Everything here is a build-time or configuration fact. The generated
+ * `authMiddleware` is deliberately absent: it is request-bound, returns a
+ * `Response` rather than a boolean, and may consult session stores, rate-limit,
+ * or audit — so preflight never invokes it, synthetically or otherwise, and
+ * `appAuthConfigured` is the only thing it is allowed to know about it.
+ *
+ * An `authPredicate` seam (option 1 in #2590) can later be added as an optional
+ * member here, turning the `app-auth` layer's `unknown` into a real verdict
+ * without changing the report contract.
+ */
+export interface BrowserPreflightLayerSource {
+    /** `isApiActionEnabled` for the referenced model operation. */
+    isActionExposed(model: string, action: string): boolean;
+    /** `isRoutePublic` for the HTTP method the action maps to. */
+    isRoutePublic(model: string, action: string): boolean;
+    /** Field-level read-permission slugs the step's model declares. */
+    requiredFieldPermissions(model: string, action: string): readonly string[];
+    /** Whether an app-level auth middleware is wired. Never invoked. */
+    appAuthConfigured: boolean;
+}
+export interface BrowserPreflightOptions {
+    layers: BrowserPreflightLayerSource;
+    /**
+     * The caller's published permission slugs, when the host publishes them.
+     * `null`/absent makes the field layer report `unknown` rather than guess.
+     */
+    permissions?: Iterable<string> | null;
+}
+export interface ServerPreflightOptions {
+    /** `PrincipalRun.isToolAllowed` for the slug that gates this step. */
+    isToolAllowed(step: PlaybookOperationStep): boolean;
+    /**
+     * The operation-permission predicate. Evaluates the catalog gate for the
+     * step's `(collection, action)` without performing the operation.
+     */
+    checkOperationPermission(step: PlaybookOperationStep): PreflightVerdict | Promise<PreflightVerdict>;
+    /** Declared plane validity of a view intent, from the #2588 registry. */
+    intentPlanes?(id: string): readonly PlaybookPlane[] | null | undefined;
+}
+export interface PlaybookPreflightRequest {
+    key: string;
+    plane: PlaybookPlane;
+    /**
+     * Opaque, caller-scoped principal identity used to partition the cache. It is
+     * never echoed in the report and never consulted for authority. The cache key
+     * also folds in `resolve.tenantId`, so a principal string need not encode the
+     * tenant to stay correct.
+     */
+    principal: string;
+    /** Options handed to `resolvePlaybook()` — the caller's own layer chain. */
+    resolve?: ResolvePlaybookOptions;
+    /** Evaluates each resolved step. */
+    evaluate: PreflightStepEvaluator;
+}
+//# sourceMappingURL=preflight-types.d.ts.map

package/dist/preflight-types.d.ts.map

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

package/dist/preflight.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Playbook preflight (issue #2590).
+ *
+ * Playbooks are not atomic and have no compensation, so the real failure mode
+ * is half-execution — five steps started, dead at four. Preflight is what
+ * prevents that, and secondarily lets a tool listing hide playbooks the caller
+ * cannot run.
+ *
+ * **Preflight predicts; it never grants.** Every step re-enforces at execution,
+ * unconditionally — at the REST boundary in the browser, and by
+ * `PrincipalRun.assertToolAllowed()` / `assertOperation()` server-side. Without
+ * that, a permission revoked mid-playbook would leave a cached "allowed"
+ * standing, which is a time-of-check/time-of-use bypass. Nothing in this module
+ * executes, authorizes, or caches an authorization.
+ *
+ * The two planes are deliberately asymmetric:
+ *
+ * - **Server** is a predicate that already exists. `PrincipalRun` exposes
+ *   `isToolAllowed(tool): boolean` alongside the throwing `assertToolAllowed()`,
+ *   and `assertOperation` wraps `assertOperationPermission`. Preflight is the
+ *   intersection of each step against those two, evaluated and never executed.
+ * - **Browser** cannot reuse the generated REST auth contract at all.
+ *   `authMiddleware` is `(objectName, action) => (req) => Promise<Request |
+ *   Response>`: request-bound, `Response`-returning rather than boolean, and
+ *   free to consult session stores, rate-limit, or audit. It is not a dry-run
+ *   predicate, so preflight covers the **static layers only** — action exposure,
+ *   `public` access, and field-level permission slugs — and reports the app-auth
+ *   layer as `unknown`. It never invokes `authMiddleware`, synthetically or
+ *   otherwise.
+ */
+import type { BrowserPreflightOptions, PlaybookPreflightAvailableReport, PlaybookPreflightReport, PlaybookPreflightRequest, PlaybookPreflightUnavailableReport, PreflightStepEvaluator, PreflightVerdict, ServerPreflightOptions } from './preflight-types.js';
+import type { PlaybookPlan } from './types.js';
+/**
+ * The one response every unresolvable playbook produces.
+ *
+ * Frozen and shared so an unknown key and an unauthorized key are byte-for-byte
+ * identical: same shape, same values, no key echo, no reason code, no message.
+ * Preflight answers only for playbooks resolvable through the caller's own
+ * layer chain, and says nothing about anything else — including whether it
+ * exists.
+ */
+export declare const PLAYBOOK_PREFLIGHT_UNAVAILABLE: PlaybookPreflightUnavailableReport;
+/** Fail-closed combination: `deny` beats `unknown` beats `allow`. */
+export declare function worstVerdict(left: PreflightVerdict, right: PreflightVerdict): PreflightVerdict;
+/**
+ * Decomposes a resolved plan into per-step verdicts using `evaluate`.
+ *
+ * Every step is evaluated — evaluation does not short-circuit on the first
+ * denial, because the point of preflight is to show the caller *which* step of
+ * five would die, not merely that one would.
+ */
+export declare function preflightPlan(plan: PlaybookPlan, evaluate: PreflightStepEvaluator): Promise<PlaybookPreflightAvailableReport>;
+/**
+ * Preflights one playbook for one caller on one plane.
+ *
+ * Resolves through the **caller's own layer chain** (their tenant, their
+ * overrides, their plane), decomposes the plan, and evaluates each step with the
+ * plane's evaluator. Any playbook the chain cannot resolve — unknown, disabled,
+ * wrong plane, unresolvable intent — returns the single
+ * {@link PLAYBOOK_PREFLIGHT_UNAVAILABLE} value.
+ *
+ * Results are cached per `(principal, key, plane)` under the playbook cache's
+ * generation counter; see `preflight-cache.ts` for why that is safe.
+ */
+export declare function preflightPlaybook(request: PlaybookPreflightRequest): Promise<PlaybookPreflightReport>;
+/**
+ * Server-plane evaluator: the intersection of the persona tool allow-list and
+ * the operation-permission predicate, per step, with nothing executed.
+ *
+ * An intent step is reported against its **declared** plane validity: an intent
+ * that does not declare `server` is denied with reason `plane`, and one that
+ * does is `unknown`, because server validity rides the #2446 command/ack bridge
+ * whose acknowledgement is not statically knowable. This repeats a check
+ * resolution already made, deliberately — the same defense-in-depth shape as
+ * `assertToolAllowed()` gating both the tool offer and its execution.
+ */
+export declare function createServerStepEvaluator(options: ServerPreflightOptions): PreflightStepEvaluator;
+/**
+ * Browser-plane evaluator: the static layers only.
+ *
+ * - `action-exposure` — `isApiActionEnabled`. A disabled action is a hard,
+ *   statically knowable deny (the route answers 405).
+ * - `public-access` — `isRoutePublic`. A non-public route with **no** app auth
+ *   middleware wired is a hard deny (the generator's fail-closed 401); with one
+ *   wired it is `unknown`, because whether that middleware passes is exactly
+ *   what preflight refuses to guess.
+ * - `field-permissions` — the model's declared field read-permission slugs
+ *   against the caller's published set. Missing slugs redact fields rather than
+ *   fail the step, so the verdict stays `allow` and carries
+ *   `reason: 'fields-redacted'` plus the missing slugs; an unpublished
+ *   permission set reports `unknown`.
+ * - `app-auth` — `unknown` whenever a middleware is wired. This is the layer an
+ *   `authPredicate` seam would later fill in.
+ *
+ * An intent step never crosses the REST boundary at all, so it is reported
+ * `unknown` against `intent-mount`: whether the surface is mounted and what its
+ * staged-control review does are runtime facts of the page, not of the build.
+ */
+export declare function createBrowserStepEvaluator(options: BrowserPreflightOptions): PreflightStepEvaluator;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAUH,OAAO,KAAK,EACV,uBAAuB,EACvB,gCAAgC,EAChC,uBAAuB,EACvB,wBAAwB,EACxB,kCAAkC,EAElC,sBAAsB,EAGtB,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAEV,YAAY,EAGb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,EAAE,kCAOH,CAAC;AAQ3C,qEAAqE;AACrE,wBAAgB,YAAY,CAC1B,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,gBAAgB,GACtB,gBAAgB,CAElB;AA6BD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,YAAY,EAClB,QAAQ,EAAE,sBAAsB,GAC/B,OAAO,CAAC,gCAAgC,CAAC,CA+B3C;AAgED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAqDlC;AAkBD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,sBAAsB,GAC9B,sBAAsB,CA+BxB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,uBAAuB,GAC/B,sBAAsB,CA2DxB"}

package/dist/rest-preflight.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Browser-plane preflight wiring for the generated REST surface (issue #2590).
+ *
+ * Binds the plane-agnostic evaluator in `preflight.ts` to the static layers
+ * `@happyvertical/smrt-core` exposes, and produces the provider the generated
+ * `_preflight` route takes as a seam. Core owns the route and the layer facts;
+ * this package owns resolution and the verdict vocabulary, so the dependency
+ * stays one-way (playbooks → core).
+ *
+ * Nothing here can reach `authMiddleware`: the provider is handed a boolean
+ * `appAuthConfigured` and no auth handle at all.
+ */
+import type { BrowserPreflightLayerSource, PlaybookPreflightReport } from './preflight-types.js';
+import type { ResolvePlaybookOptions } from './types.js';
+/**
+ * A layer source reading the generated REST surface's own static rules.
+ *
+ * A model this build does not register resolves to no object name, and every
+ * layer then fails closed: an unregistered model has no route, so a step naming
+ * one can only die.
+ */
+export declare function createRestPreflightLayerSource(options: {
+    appAuthConfigured: boolean;
+}): BrowserPreflightLayerSource;
+export interface BrowserPreflightProviderOptions {
+    /**
+     * Resolution options shared by every request — classifier, intent registry,
+     * and any host-level runtime override. The per-request database handle and
+     * tenant come from the route.
+     */
+    resolve?: Omit<ResolvePlaybookOptions, 'plane' | 'db'>;
+    /**
+     * Derives the cache-partitioning principal identity for a request. Opaque and
+     * never echoed; defaults to the caller's permission slugs, which is the only
+     * caller-distinguishing input the static layers actually read.
+     */
+    principal?: (request: {
+        permissions?: Iterable<string>;
+        appAuthConfigured: boolean;
+    }) => string;
+}
+/**
+ * Builds the provider wired into `APIConfig.playbookPreflight`.
+ *
+ * ```typescript
+ * const api = new APIGenerator(manifest, {
+ *   playbookPreflight: createBrowserPlaybookPreflight(),
+ * });
+ * ```
+ *
+ * Every unresolvable key — unknown, disabled, browser-invalid, unresolvable
+ * intent — comes back as the single uniform unavailable report, so the endpoint
+ * is not an enumeration oracle.
+ */
+export declare function createBrowserPlaybookPreflight(options?: BrowserPreflightProviderOptions): (request: {
+    key: string;
+    plane: 'browser';
+    permissions?: Iterable<string>;
+    appAuthConfigured: boolean;
+    db?: unknown;
+}) => Promise<PlaybookPreflightReport>;
+//# sourceMappingURL=rest-preflight.d.ts.map

package/dist/rest-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest-preflight.d.ts","sourceRoot":"","sources":["../src/rest-preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAWH,OAAO,KAAK,EACV,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,iBAAiB,EAAE,OAAO,CAAC;CAC5B,GAAG,2BAA2B,CAgC9B;AAED,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,OAAO,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC;IACvD;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QACpB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,iBAAiB,EAAE,OAAO,CAAC;KAC5B,KAAK,MAAM,CAAC;CACd;AAsBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,+BAAoC,GAC5C,CAAC,OAAO,EAAE;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,EAAE,CAAC,EAAE,OAAO,CAAC;CACd,KAAK,OAAO,CAAC,uBAAuB,CAAC,CAqBrC"}

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-playbooks",
-  "packageVersion": "0.51.32",
+  "packageVersion": "0.51.34",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "542c58a25f647adf86852f1e902d8bbebb68f33a38b16be234e568892d0026d0",
-    "packageJson": "69a3de2135e604032f30907770ef358d061238b7db1075e1706cf3fe4525a200",
+    "manifest": "02659cb7bb41840d2aca07706d580a6e628372d09605ac3f181726f0f3a6b945",
+    "packageJson": "5bdf32072411cd2d23269afac6c2df0ebee97d2e4b1f7714569d295f72776b5c",
     "agents": "24cc1ff7167bdb3f2c2b9350d6ba24fb0286013023c5cc49876f16811387e312"
   },
   "exports": [
@@ -24,7 +24,7 @@
     "@happyvertical/sql": "catalog:",
     "@happyvertical/smrt-vitest": "workspace:*",
     "@types/node": "24.13.6",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "vite": "8.1.4",
     "vitest": "4.1.10"
   },