@honua/react 0.0.20-alpha.0

package/studio/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * Browser-safe TypeScript projections for the Studio package families
+ * (query, analysis, map, dashboard, report, form, app, workflow, GP, ETL).
+ *
+ * Console interop, MCP, QGIS, generated apps, and embeds must not fork the
+ * server-owned package schemas. These projections mirror the canonical
+ * server wire shapes — the `format` string on each family is the version
+ * gate, exactly as on {@link HonuaMapPackage}. The `map` and `dashboard`
+ * families already have established SDK-native types and are re-tagged here
+ * rather than re-declared.
+ *
+ * The remaining families (query, analysis, report, form, workflow, GP, ETL)
+ * have no finalized server contract yet, so their interfaces are minimal,
+ * open-ended stubs (every field optional, plus `[extra: string]: unknown`)
+ * gated by a `HONUA_X_PACKAGE_FORMAT_V1` constant. They expand once the
+ * server shape lands.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0` and before the matching
+ *   server contracts ship.
+ * @module
+ */
+import type { HonuaGeneratedAppManifest, HonuaGeneratedAppPackage } from "../generated-app/manifest.js";
+import type { HonuaMapPackage, HonuaMapPackageStatus } from "../runtime/map-package.js";
+/** Canonical format string for the v1 QueryPackage shape. */
+export declare const HONUA_QUERY_PACKAGE_FORMAT_V1: "honua_query_package.v1";
+/** Canonical format string for the v1 AnalysisPackage shape. */
+export declare const HONUA_ANALYSIS_PACKAGE_FORMAT_V1: "honua_analysis_package.v1";
+/** Canonical format string for the v1 ReportPackage shape. */
+export declare const HONUA_REPORT_PACKAGE_FORMAT_V1: "honua_report_package.v1";
+/** Canonical format string for the v1 FormPackage shape. */
+export declare const HONUA_FORM_PACKAGE_FORMAT_V1: "honua_form_package.v1";
+/** Canonical format string for the v1 WorkflowPackage shape. */
+export declare const HONUA_WORKFLOW_PACKAGE_FORMAT_V1: "honua_workflow_package.v1";
+/** Canonical format string for the v1 GPPackage shape. */
+export declare const HONUA_GP_PACKAGE_FORMAT_V1: "honua_gp_package.v1";
+/** Canonical format string for the v1 ETLPackage shape. */
+export declare const HONUA_ETL_PACKAGE_FORMAT_V1: "honua_etl_package.v1";
+export type HonuaQueryPackageFormat = typeof HONUA_QUERY_PACKAGE_FORMAT_V1;
+export type HonuaAnalysisPackageFormat = typeof HONUA_ANALYSIS_PACKAGE_FORMAT_V1;
+export type HonuaReportPackageFormat = typeof HONUA_REPORT_PACKAGE_FORMAT_V1;
+export type HonuaFormPackageFormat = typeof HONUA_FORM_PACKAGE_FORMAT_V1;
+export type HonuaWorkflowPackageFormat = typeof HONUA_WORKFLOW_PACKAGE_FORMAT_V1;
+export type HonuaGPPackageFormat = typeof HONUA_GP_PACKAGE_FORMAT_V1;
+export type HonuaETLPackageFormat = typeof HONUA_ETL_PACKAGE_FORMAT_V1;
+/**
+ * Lifecycle states a Studio package may occupy server-side. Shared with the
+ * stable {@link HonuaMapPackageStatus} so every family reports one lifecycle.
+ *
+ * @experimental
+ */
+export type HonuaStudioPackageStatus = HonuaMapPackageStatus;
+/**
+ * Fields every stub Studio package family carries. `format` is narrowed to a
+ * family-specific literal by each interface; unknown additive fields are
+ * preserved through `[extra: string]: unknown` so minor server revisions do
+ * not break clients.
+ *
+ * @experimental
+ */
+export interface HonuaStudioPackageBase {
+    readonly packageId: string;
+    readonly format: string;
+    readonly status?: HonuaStudioPackageStatus;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly expiresAt?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Minimal reference to a source a package binds to. Open-ended until the
+ * server source-binding contract for non-map families is finalized.
+ *
+ * @experimental
+ */
+export interface HonuaStudioBindingRef {
+    readonly sourceId?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Query specification carried by a {@link HonuaQueryPackage}.
+ *
+ * @experimental
+ */
+export interface HonuaStudioQuerySpec {
+    readonly where?: string;
+    readonly orderBy?: string | readonly string[];
+    readonly outFields?: readonly string[];
+    readonly groupBy?: readonly string[];
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client projection of a server QueryPackage.
+ *
+ * @experimental
+ */
+export interface HonuaQueryPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaQueryPackageFormat;
+    readonly sourceBindings?: readonly HonuaStudioBindingRef[];
+    readonly querySpec?: HonuaStudioQuerySpec;
+    readonly previewLimit?: number;
+}
+/**
+ * Client projection of a server AnalysisPackage.
+ *
+ * @experimental
+ */
+export interface HonuaAnalysisPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaAnalysisPackageFormat;
+    readonly sourcePackageId?: string;
+    readonly analysisKind?: string;
+    readonly parameters?: Record<string, unknown>;
+    readonly resultBindings?: readonly HonuaStudioBindingRef[];
+}
+/**
+ * One section in a {@link HonuaReportPackage} layout.
+ *
+ * @experimental
+ */
+export interface HonuaReportSectionSpec {
+    readonly id?: string;
+    readonly kind?: string;
+    readonly title?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client projection of a server ReportPackage.
+ *
+ * @experimental
+ */
+export interface HonuaReportPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaReportPackageFormat;
+    readonly title?: string;
+    readonly templateId?: string;
+    readonly sections?: readonly HonuaReportSectionSpec[];
+    readonly mapPackageId?: string;
+}
+/**
+ * One field in a {@link HonuaFormPackage}.
+ *
+ * @experimental
+ */
+export interface HonuaFormFieldSpec {
+    readonly name?: string;
+    readonly label?: string;
+    readonly type?: string;
+    readonly required?: boolean;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client projection of a server FormPackage.
+ *
+ * @experimental
+ */
+export interface HonuaFormPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaFormPackageFormat;
+    readonly title?: string;
+    readonly sourceId?: string;
+    readonly fields?: readonly HonuaFormFieldSpec[];
+    readonly submitAction?: string;
+}
+/**
+ * One step in a {@link HonuaWorkflowPackage}.
+ *
+ * @experimental
+ */
+export interface HonuaWorkflowStepSpec {
+    readonly id?: string;
+    readonly kind?: string;
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client projection of a server WorkflowPackage.
+ *
+ * @experimental
+ */
+export interface HonuaWorkflowPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaWorkflowPackageFormat;
+    readonly title?: string;
+    readonly steps?: readonly HonuaWorkflowStepSpec[];
+    readonly trigger?: string;
+}
+/**
+ * One geoprocessing input/output parameter in a {@link HonuaGPPackage}.
+ *
+ * @experimental
+ */
+export interface HonuaGPParameterSpec {
+    readonly name?: string;
+    readonly dataType?: string;
+    readonly direction?: "input" | "output" | (string & {});
+    readonly [extra: string]: unknown;
+}
+/**
+ * Client projection of a server GPPackage (geoprocessing).
+ *
+ * @experimental
+ */
+export interface HonuaGPPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaGPPackageFormat;
+    readonly processId?: string;
+    readonly inputs?: readonly HonuaGPParameterSpec[];
+    readonly outputs?: readonly HonuaGPParameterSpec[];
+}
+/**
+ * Client projection of a server ETLPackage.
+ *
+ * @experimental
+ */
+export interface HonuaETLPackage extends HonuaStudioPackageBase {
+    readonly format: HonuaETLPackageFormat;
+    readonly pipelineId?: string;
+    readonly sourceKind?: string;
+    readonly targetKind?: string;
+    readonly transformSpec?: unknown;
+}
+/**
+ * Maps each Studio package family discriminant to its projection shape.
+ * `map` and `dashboard`/`app` reuse the established SDK-native types rather
+ * than re-declaring them.
+ *
+ * @experimental
+ */
+export interface StudioPackageFamilyShapes {
+    readonly query: HonuaQueryPackage;
+    readonly analysis: HonuaAnalysisPackage;
+    readonly map: HonuaMapPackage;
+    readonly dashboard: HonuaGeneratedAppManifest;
+    readonly report: HonuaReportPackage;
+    readonly form: HonuaFormPackage;
+    readonly app: HonuaGeneratedAppPackage;
+    readonly workflow: HonuaWorkflowPackage;
+    readonly gp: HonuaGPPackage;
+    readonly etl: HonuaETLPackage;
+}
+/**
+ * The client-side discriminant tag naming a package family. The server wire
+ * shape does not carry this field — projection helpers add it.
+ *
+ * @experimental
+ */
+export type HonuaStudioPackageFamily = keyof StudioPackageFamilyShapes;
+/**
+ * Discriminated union over every Studio package family, tagged by a
+ * client-side `packageFamily` field. Narrow on `packageFamily` to access the
+ * family-specific shape. Build values through {@link tagStudioPackage} rather
+ * than casting a raw wire object — the tag is not present on the wire.
+ *
+ * @experimental
+ */
+export type HonuaStudioPackage = {
+    readonly [F in HonuaStudioPackageFamily]: {
+        readonly packageFamily: F;
+    } & StudioPackageFamilyShapes[F];
+}[HonuaStudioPackageFamily];
+/**
+ * Every known Studio package family discriminant, in spec order.
+ *
+ * @experimental
+ */
+export declare const STUDIO_PACKAGE_FAMILIES: readonly ["query", "analysis", "map", "dashboard", "report", "form", "app", "workflow", "gp", "etl"];
+/**
+ * Type guard for a known {@link HonuaStudioPackageFamily} discriminant.
+ *
+ * @experimental
+ */
+export declare function isStudioPackageFamily(value: unknown): value is HonuaStudioPackageFamily;
+/**
+ * Tag a raw family package with its client-side `packageFamily` discriminant,
+ * producing a narrowable {@link HonuaStudioPackage} union member. The server
+ * wire shape omits the tag; this is the canonical way to add it.
+ *
+ * @experimental
+ */
+export declare function tagStudioPackage<F extends HonuaStudioPackageFamily>(family: F, pkg: StudioPackageFamilyShapes[F]): Extract<HonuaStudioPackage, {
+    readonly packageFamily: F;
+}>;
+//# sourceMappingURL=types.d.ts.map

package/studio/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/studio/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AACxG,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAExF,6DAA6D;AAC7D,eAAO,MAAM,6BAA6B,EAAG,wBAAiC,CAAC;AAC/E,gEAAgE;AAChE,eAAO,MAAM,gCAAgC,EAAG,2BAAoC,CAAC;AACrF,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,EAAG,yBAAkC,CAAC;AACjF,4DAA4D;AAC5D,eAAO,MAAM,4BAA4B,EAAG,uBAAgC,CAAC;AAC7E,gEAAgE;AAChE,eAAO,MAAM,gCAAgC,EAAG,2BAAoC,CAAC;AACrF,0DAA0D;AAC1D,eAAO,MAAM,0BAA0B,EAAG,qBAA8B,CAAC;AACzE,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,EAAG,sBAA+B,CAAC;AAE3E,MAAM,MAAM,uBAAuB,GAAG,OAAO,6BAA6B,CAAC;AAC3E,MAAM,MAAM,0BAA0B,GAAG,OAAO,gCAAgC,CAAC;AACjF,MAAM,MAAM,wBAAwB,GAAG,OAAO,8BAA8B,CAAC;AAC7E,MAAM,MAAM,sBAAsB,GAAG,OAAO,4BAA4B,CAAC;AACzE,MAAM,MAAM,0BAA0B,GAAG,OAAO,gCAAgC,CAAC;AACjF,MAAM,MAAM,oBAAoB,GAAG,OAAO,0BAA0B,CAAC;AACrE,MAAM,MAAM,qBAAqB,GAAG,OAAO,2BAA2B,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,sBAAsB;IAC/D,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;CAC5D;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IAChE,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACtD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,sBAAsB;IAC9D,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACxD,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,sBAAsB;IAC5D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,sBAAsB;IAC7D,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,GAAG,EAAE,wBAAwB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,yBAAyB,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,CAAC,IAAI,wBAAwB,GAAG;QAAE,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAA;KAAE,GAAG,yBAAyB,CAAC,CAAC,CAAC;CACvG,CAAC,wBAAwB,CAAC,CAAC;AAE5B;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,sGAWoB,CAAC;AAEzD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAEvF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,wBAAwB,EACjE,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,kBAAkB,EAAE;IAAE,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAA;CAAE,CAAC,CAK5D"}

package/studio/types.js

@@ -0,0 +1,71 @@
+/**
+ * Browser-safe TypeScript projections for the Studio package families
+ * (query, analysis, map, dashboard, report, form, app, workflow, GP, ETL).
+ *
+ * Console interop, MCP, QGIS, generated apps, and embeds must not fork the
+ * server-owned package schemas. These projections mirror the canonical
+ * server wire shapes — the `format` string on each family is the version
+ * gate, exactly as on {@link HonuaMapPackage}. The `map` and `dashboard`
+ * families already have established SDK-native types and are re-tagged here
+ * rather than re-declared.
+ *
+ * The remaining families (query, analysis, report, form, workflow, GP, ETL)
+ * have no finalized server contract yet, so their interfaces are minimal,
+ * open-ended stubs (every field optional, plus `[extra: string]: unknown`)
+ * gated by a `HONUA_X_PACKAGE_FORMAT_V1` constant. They expand once the
+ * server shape lands.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0` and before the matching
+ *   server contracts ship.
+ * @module
+ */
+/** Canonical format string for the v1 QueryPackage shape. */
+export const HONUA_QUERY_PACKAGE_FORMAT_V1 = "honua_query_package.v1";
+/** Canonical format string for the v1 AnalysisPackage shape. */
+export const HONUA_ANALYSIS_PACKAGE_FORMAT_V1 = "honua_analysis_package.v1";
+/** Canonical format string for the v1 ReportPackage shape. */
+export const HONUA_REPORT_PACKAGE_FORMAT_V1 = "honua_report_package.v1";
+/** Canonical format string for the v1 FormPackage shape. */
+export const HONUA_FORM_PACKAGE_FORMAT_V1 = "honua_form_package.v1";
+/** Canonical format string for the v1 WorkflowPackage shape. */
+export const HONUA_WORKFLOW_PACKAGE_FORMAT_V1 = "honua_workflow_package.v1";
+/** Canonical format string for the v1 GPPackage shape. */
+export const HONUA_GP_PACKAGE_FORMAT_V1 = "honua_gp_package.v1";
+/** Canonical format string for the v1 ETLPackage shape. */
+export const HONUA_ETL_PACKAGE_FORMAT_V1 = "honua_etl_package.v1";
+/**
+ * Every known Studio package family discriminant, in spec order.
+ *
+ * @experimental
+ */
+export const STUDIO_PACKAGE_FAMILIES = [
+    "query",
+    "analysis",
+    "map",
+    "dashboard",
+    "report",
+    "form",
+    "app",
+    "workflow",
+    "gp",
+    "etl",
+];
+/**
+ * Type guard for a known {@link HonuaStudioPackageFamily} discriminant.
+ *
+ * @experimental
+ */
+export function isStudioPackageFamily(value) {
+    return typeof value === "string" && STUDIO_PACKAGE_FAMILIES.includes(value);
+}
+/**
+ * Tag a raw family package with its client-side `packageFamily` discriminant,
+ * producing a narrowable {@link HonuaStudioPackage} union member. The server
+ * wire shape omits the tag; this is the canonical way to add it.
+ *
+ * @experimental
+ */
+export function tagStudioPackage(family, pkg) {
+    return { ...pkg, packageFamily: family };
+}

package/studio/validate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Family-agnostic validation for Studio packages produced outside Console —
+ * by an MCP client, the QGIS plugin, or the SDK itself. It returns the same
+ * unified {@link StudioPackageValidationResponse} envelope as the per-family
+ * validators, so a package generated through any surface is validated against
+ * one contract.
+ *
+ * For the `map` family this delegates to the established
+ * {@link validateMapPackage} (no duplication). For every other family it runs
+ * the shared base checks (`packageId`/`format`, lifecycle) and, when present,
+ * the shared {@link HonuaPackageProvenance} checks. Provenance is optional, but
+ * when a package carries it, MCP- and QGIS-origin packages must satisfy the
+ * same provenance shape as Console.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import { type HonuaPackageProvenance } from "./provenance.js";
+import type { StudioPackageValidationResponse } from "./validation.js";
+export interface ValidateStudioPackageOptions {
+    /** Wall-clock for lifecycle (expired) diagnostics. Defaults to `Date.now()`. */
+    readonly now?: number | Date;
+    /** Require a {@link HonuaPackageProvenance} envelope to be present. */
+    readonly requireProvenance?: boolean;
+}
+/**
+ * Validate a package of any Studio family produced outside Console. Dispatches
+ * to the map validator for the `map` family and applies shared base +
+ * provenance checks for every family.
+ *
+ * @experimental
+ */
+export declare function validateStudioPackage<T = unknown>(family: string, value: unknown, options?: ValidateStudioPackageOptions): StudioPackageValidationResponse<T>;
+/**
+ * Validate just the {@link HonuaPackageProvenance} envelope on a package value.
+ * Useful when a host (MCP/QGIS) wants to confirm attribution without running
+ * the full family validation.
+ *
+ * @experimental
+ */
+export declare function validatePackageProvenance(value: unknown, options?: {
+    readonly required?: boolean;
+}): StudioPackageValidationResponse<HonuaPackageProvenance>;
+//# sourceMappingURL=validate.d.ts.map

package/studio/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/studio/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAsC,KAAK,sBAAsB,EAAwB,MAAM,iBAAiB,CAAC;AAGxH,OAAO,KAAK,EAA2B,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AA4BhG,MAAM,WAAW,4BAA4B;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,4BAAiC,GACzC,+BAA+B,CAAC,CAAC,CAAC,CAgEpC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,+BAA+B,CAAC,sBAAsB,CAAC,CASzD"}

package/studio/validate.js

@@ -0,0 +1,255 @@
+/**
+ * Family-agnostic validation for Studio packages produced outside Console —
+ * by an MCP client, the QGIS plugin, or the SDK itself. It returns the same
+ * unified {@link StudioPackageValidationResponse} envelope as the per-family
+ * validators, so a package generated through any surface is validated against
+ * one contract.
+ *
+ * For the `map` family this delegates to the established
+ * {@link validateMapPackage} (no duplication). For every other family it runs
+ * the shared base checks (`packageId`/`format`, lifecycle) and, when present,
+ * the shared {@link HonuaPackageProvenance} checks. Provenance is optional, but
+ * when a package carries it, MCP- and QGIS-origin packages must satisfy the
+ * same provenance shape as Console.
+ *
+ * @experimental Not yet covered by the SDK's semver contract — these shapes
+ *   may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+import { validateMapPackage } from "../runtime/map-package-validation.js";
+import { HONUA_MAP_PACKAGE_FORMAT_V1 } from "../runtime/map-package.js";
+import { HONUA_PACKAGE_PROVENANCE_FORMAT_V1, getPackageProvenance } from "./provenance.js";
+import { STUDIO_PACKAGE_FAMILIES, isStudioPackageFamily } from "./types.js";
+import { fromMapPackageValidation } from "./validation.js";
+/**
+ * Expected `format` string for each family whose projection carries a single
+ * `format` discriminant. `map` and `dashboard` reuse their established
+ * constants; the `app` family is identified by `version` rather than `format`
+ * and is therefore not in this table.
+ */
+const FAMILY_FORMAT = {
+    query: "honua_query_package.v1",
+    analysis: "honua_analysis_package.v1",
+    map: HONUA_MAP_PACKAGE_FORMAT_V1,
+    dashboard: "honua_generated_app_manifest.v1",
+    report: "honua_report_package.v1",
+    form: "honua_form_package.v1",
+    workflow: "honua_workflow_package.v1",
+    gp: "honua_gp_package.v1",
+    etl: "honua_etl_package.v1",
+};
+/** The package-identity field each family uses. */
+function packageIdOf(family, value) {
+    if (family === "map")
+        return typeof value.mapPackageId === "string" ? value.mapPackageId : undefined;
+    if (family === "dashboard")
+        return typeof value.appId === "string" ? value.appId : undefined;
+    if (family === "app")
+        return typeof value.id === "string" ? value.id : undefined;
+    return typeof value.packageId === "string" ? value.packageId : undefined;
+}
+/**
+ * Validate a package of any Studio family produced outside Console. Dispatches
+ * to the map validator for the `map` family and applies shared base +
+ * provenance checks for every family.
+ *
+ * @experimental
+ */
+export function validateStudioPackage(family, value, options = {}) {
+    const diagnostics = [];
+    if (!isStudioPackageFamily(family)) {
+        diagnostics.push({
+            code: "unknown-family",
+            severity: "error",
+            message: `Unknown Studio package family "${family}". Expected one of: ${STUDIO_PACKAGE_FAMILIES.join(", ")}.`,
+            path: "packageFamily",
+        });
+        return { valid: false, diagnostics };
+    }
+    if (!isRecord(value)) {
+        diagnostics.push({
+            code: "invalid-package",
+            severity: "error",
+            message: `${family} package must be a JSON object.`,
+        });
+        return { valid: false, diagnostics };
+    }
+    // The map family has a full structural validator already — reuse it so MCP
+    // and QGIS map packages validate identically to Console's.
+    if (family === "map") {
+        const mapResponse = fromMapPackageValidation(validateMapPackage(value, { now: options.now }));
+        const merged = [...mapResponse.diagnostics];
+        appendProvenanceDiagnostics(merged, value, options);
+        return {
+            valid: mapResponse.valid && !hasErrors(merged),
+            diagnostics: merged,
+            ...(mapResponse.pkg === undefined ? {} : { pkg: mapResponse.pkg }),
+        };
+    }
+    const packageId = packageIdOf(family, value);
+    if (!packageId) {
+        diagnostics.push({
+            code: "missing-package-id",
+            severity: "error",
+            message: `${family} package must carry a non-empty identity field.`,
+            path: family === "dashboard" ? "appId" : family === "app" ? "id" : "packageId",
+        });
+    }
+    const expectedFormat = FAMILY_FORMAT[family];
+    if (expectedFormat !== undefined && family !== "app" && value.format !== expectedFormat) {
+        diagnostics.push({
+            code: "unsupported-format",
+            severity: "error",
+            message: `${family} package format must be "${expectedFormat}".`,
+            path: "format",
+            detail: { expected: expectedFormat, received: value.format },
+        });
+    }
+    appendLifecycleDiagnostics(diagnostics, value, options);
+    appendProvenanceDiagnostics(diagnostics, value, options);
+    return {
+        valid: !hasErrors(diagnostics),
+        diagnostics,
+        pkg: value,
+    };
+}
+/**
+ * Validate just the {@link HonuaPackageProvenance} envelope on a package value.
+ * Useful when a host (MCP/QGIS) wants to confirm attribution without running
+ * the full family validation.
+ *
+ * @experimental
+ */
+export function validatePackageProvenance(value, options = {}) {
+    const diagnostics = [];
+    appendProvenanceDiagnostics(diagnostics, value, { requireProvenance: options.required });
+    const provenance = getPackageProvenance(value);
+    return {
+        valid: !hasErrors(diagnostics),
+        diagnostics,
+        ...(provenance === undefined ? {} : { pkg: provenance }),
+    };
+}
+const KNOWN_ORIGINS = new Set(["console", "studio", "mcp", "qgis", "sdk"]);
+function appendProvenanceDiagnostics(diagnostics, value, options) {
+    const raw = isRecord(value) ? value.provenance : undefined;
+    if (raw === undefined) {
+        if (options.requireProvenance) {
+            diagnostics.push({
+                code: "missing-provenance",
+                severity: "error",
+                message: "Package provenance is required but absent.",
+                path: "provenance",
+            });
+        }
+        return;
+    }
+    if (!isRecord(raw)) {
+        diagnostics.push({
+            code: "invalid-provenance",
+            severity: "error",
+            message: "Package provenance must be a JSON object.",
+            path: "provenance",
+        });
+        return;
+    }
+    if (raw.format !== HONUA_PACKAGE_PROVENANCE_FORMAT_V1) {
+        diagnostics.push({
+            code: "unsupported-provenance-format",
+            severity: "error",
+            message: `Package provenance.format must be "${HONUA_PACKAGE_PROVENANCE_FORMAT_V1}".`,
+            path: "provenance.format",
+            detail: { expected: HONUA_PACKAGE_PROVENANCE_FORMAT_V1, received: raw.format },
+        });
+        return;
+    }
+    if (typeof raw.origin !== "string" || raw.origin.length === 0) {
+        diagnostics.push({
+            code: "missing-provenance-origin",
+            severity: "error",
+            message: "Package provenance.origin must be a non-empty string.",
+            path: "provenance.origin",
+        });
+    }
+    else if (!KNOWN_ORIGINS.has(raw.origin)) {
+        diagnostics.push({
+            code: "unknown-provenance-origin",
+            severity: "warning",
+            message: `Package provenance.origin "${raw.origin}" is not a known surface.`,
+            path: "provenance.origin",
+            detail: { origin: raw.origin, known: [...KNOWN_ORIGINS] },
+        });
+    }
+    if (raw.dataBindings !== undefined && !Array.isArray(raw.dataBindings)) {
+        diagnostics.push({
+            code: "invalid-provenance-data-bindings",
+            severity: "error",
+            message: "Package provenance.dataBindings must be an array when present.",
+            path: "provenance.dataBindings",
+        });
+    }
+    else if (Array.isArray(raw.dataBindings)) {
+        raw.dataBindings.forEach((binding, i) => {
+            if (!isRecord(binding) || typeof binding.sourceId !== "string" || binding.sourceId.length === 0) {
+                diagnostics.push({
+                    code: "invalid-provenance-data-binding",
+                    severity: "error",
+                    message: "Each provenance dataBinding must carry a non-empty sourceId.",
+                    path: `provenance.dataBindings[${i}].sourceId`,
+                });
+            }
+        });
+    }
+    if (raw.permissions !== undefined && !Array.isArray(raw.permissions)) {
+        diagnostics.push({
+            code: "invalid-provenance-permissions",
+            severity: "error",
+            message: "Package provenance.permissions must be an array when present.",
+            path: "provenance.permissions",
+        });
+    }
+    else if (Array.isArray(raw.permissions)) {
+        raw.permissions.forEach((permission, i) => {
+            if (!isRecord(permission) || typeof permission.scope !== "string" || permission.scope.length === 0) {
+                diagnostics.push({
+                    code: "invalid-provenance-permission",
+                    severity: "error",
+                    message: "Each provenance permission must carry a non-empty scope.",
+                    path: `provenance.permissions[${i}].scope`,
+                });
+            }
+        });
+    }
+}
+function appendLifecycleDiagnostics(diagnostics, value, options) {
+    const nowMs = options.now instanceof Date ? options.now.getTime() : (options.now ?? Date.now());
+    if (value.status === "Expired") {
+        diagnostics.push({
+            code: "expired-package",
+            severity: "error",
+            message: "Package status is Expired.",
+            path: "status",
+        });
+    }
+    const expiresAt = parseTimestamp(value.expiresAt);
+    if (expiresAt !== undefined && expiresAt <= nowMs) {
+        diagnostics.push({
+            code: "expired-package",
+            severity: "error",
+            message: "Package expiresAt is in the past.",
+            path: "expiresAt",
+        });
+    }
+}
+function parseTimestamp(value) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const parsed = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function hasErrors(diagnostics) {
+    return diagnostics.some((d) => d.severity === "error");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}