@honua/app-platform 0.1.2-beta.0 → 0.1.7-beta.0

package/scene-workspace/state-sync-port-kit.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared machinery for the shipped renderer state-sync ports.
+ *
+ * `createSceneStateSynchronizer` is a transport: it revisions, coalesces, and
+ * delivers, but it never touches a renderer. Everything a *real* port has to get
+ * right — sequence discipline, echo suppression, bounded convergence, listener
+ * lifecycles, and honest degradation reporting — lives here once so the
+ * MapLibre and Cesium ports differ only in the renderer they drive.
+ *
+ * ## Echo suppression and convergence
+ *
+ * Every renderer change loop has the same hazard: state applied *from* the
+ * shared envelope makes the renderer fire its own change event, which would be
+ * re-published as a local change and bounce back forever. Two mechanisms close
+ * the loop, and both are needed:
+ *
+ * 1. **Applied-signature matching.** Immediately after applying a delivery the
+ *    port reads the renderer back and records a quantized signature of what the
+ *    renderer actually holds. The next renderer event whose signature matches is
+ *    an echo: it is published once with `causeRevision` set to the applied
+ *    revision, which the synchronizer classifies as `loop-suppressed` and drops.
+ *    Publishing the acknowledgement rather than swallowing it keeps the loop
+ *    closure observable instead of invisible.
+ * 2. **Lossy sides do not write back.** When a renderer cannot hold what it was
+ *    given (a globe pitch a 2D map clamps, a pose outside the zoom range) the
+ *    port applies its best effort, records a {@link SceneStateSyncPortDegradation},
+ *    and leaves the shared value alone. Writing the clamped value back would
+ *    drag every other view down to the least capable renderer's limits *and*
+ *    would be the one shape that can oscillate. With this rule a change
+ *    converges in one round trip: origin publishes, target applies, target
+ *    acknowledges, done.
+ *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface.
+ * @module
+ */
+import type { SceneCameraDegradationCode } from "./camera-correspondence.js";
+import { type SceneStateSyncAttributionValue, type SceneStateSyncIdentity, type SceneStateSyncInput, type SceneStateSyncPort, type SceneStateSyncRenderer, type SceneStateSyncSlice, type SceneStateSyncValueMap } from "./state-sync.js";
+/**
+ * Named ways a shipped port could not fully honour a slice. Camera codes are
+ * shared with the pure projection helpers so one vocabulary covers both.
+ */
+export type SceneStateSyncPortDegradationCode = SceneCameraDegradationCode | "selection-source-missing" | "selection-target-unresolved" | "selection-not-fully-expressible" | "filters-no-target-layers" | "filters-layer-rejected" | "time-field-unconfigured" | "time-clock-unavailable" | "time-clock-host-owned" | "time-plan-rejected" | "detail-target-unresolved" | "attribution-id-rejected";
+/** One reported shortfall, attributed to the port and revision that caused it. */
+export interface SceneStateSyncPortDegradation {
+    readonly portId: string;
+    readonly slice: SceneStateSyncSlice;
+    readonly code: SceneStateSyncPortDegradationCode;
+    readonly message: string;
+    readonly at: string;
+    readonly revision?: number;
+    /** What the shared state asked for, when the shortfall is numeric. */
+    readonly requested?: number;
+    /** What the renderer was given instead. */
+    readonly applied?: number;
+}
+/** Optional quantitative context for {@link PortCore.degrade}. */
+export interface SceneStateSyncPortDegradationDetail {
+    readonly revision?: number;
+    readonly requested?: number;
+    readonly applied?: number;
+}
+/**
+ * A {@link SceneStateSyncPort} bound to a live renderer.
+ *
+ * Beyond the transport contract it adds the two things a real binding needs: a
+ * way for the host application to publish renderer-origin state the renderer
+ * has no event for (selection, filters, time), and an owned teardown.
+ */
+export interface SceneStateSyncRendererPort extends SceneStateSyncPort {
+    /**
+     * Publish a renderer-origin change. Returns what the port did with it:
+     * `published` for a genuine local change, `acknowledged` for an echo of a
+     * delivery this port applied, `duplicate` when nothing changed, and `disposed`
+     * after teardown.
+     */
+    publish<Slice extends SceneStateSyncSlice>(slice: Slice, value: SceneStateSyncValueMap[Slice]): SceneStateSyncPublishOutcome;
+    /**
+     * Read a slice back out of the live renderer and publish it if it changed.
+     *
+     * The push path (renderer events) is wired automatically where the renderer
+     * has one; this is the pull complement for slices whose change notification is
+     * frame-driven or absent. `unsupported` means this renderer holds no readable
+     * state for the slice.
+     */
+    readFromRenderer(slice: SceneStateSyncSlice): SceneStateSyncPublishOutcome | "unsupported";
+    /** Everything this port could not fully honour, oldest first and bounded. */
+    readonly degradations: readonly SceneStateSyncPortDegradation[];
+    readonly disposed: boolean;
+    /** Release every renderer listener this port owns. Idempotent. */
+    dispose(): void;
+}
+/** What a port did with a renderer-origin value. */
+export type SceneStateSyncPublishOutcome = "published" | "acknowledged" | "duplicate" | "disposed";
+/**
+ * Reduce free-form attribution text to the credential-free identifier charset
+ * the `attribution` slice accepts.
+ *
+ * The slice carries identifiers, not markup: `"County orthophotography"` becomes
+ * `county-orthophotography`, and `<a href="...">OpenStreetMap</a> contributors`
+ * becomes `openstreetmap-contributors`. Anything with no identifier characters
+ * at all — or anything carrying a URL with credentials — yields `undefined`
+ * rather than a lossy guess, and the caller reports it as a degradation. The
+ * safe-id rule is a boundary to satisfy, not to relax.
+ *
+ * Reduction is a single bounded character pass rather than a chain of regular
+ * expressions: attribution text is attacker-influenceable (it arrives from a
+ * style document or a provider), and markup stripping with a pattern is a
+ * polynomial-backtracking shape.
+ */
+export declare function sceneAttributionId(value: unknown): string | undefined;
+/**
+ * Build an `attribution` slice value from live credit strings, dropping what
+ * cannot be reduced to a safe identifier and de-duplicating the rest.
+ */
+export declare function sceneAttributionValue(values: Iterable<unknown>): SceneStateSyncAttributionValue;
+export interface PortCoreOptions {
+    readonly id: string;
+    readonly renderer: SceneStateSyncRenderer;
+    readonly identity: SceneStateSyncIdentity;
+    readonly now?: () => string;
+    readonly onDegraded?: (degradation: SceneStateSyncPortDegradation) => void;
+    /** Attach renderer listeners; returns the detach. Called on first subscriber. */
+    readonly bind?: () => () => void;
+}
+export interface PortCore {
+    readonly id: string;
+    readonly degradations: readonly SceneStateSyncPortDegradation[];
+    readonly disposed: boolean;
+    subscribe(listener: (event: SceneStateSyncInput) => void, signal?: AbortSignal): () => void;
+    publish<Slice extends SceneStateSyncSlice>(slice: Slice, value: SceneStateSyncValueMap[Slice]): SceneStateSyncPublishOutcome;
+    /**
+     * Register what counts as an echo of `revision`.
+     *
+     * Pass the renderer read-back first and the delivered value second when they
+     * differ: a renderer that clamped what it was given must acknowledge its own
+     * clamped read-back instead of publishing it as a new local change.
+     */
+    markApplied(slice: SceneStateSyncSlice, revision: number, ...values: readonly unknown[]): void;
+    degrade(slice: SceneStateSyncSlice, code: SceneStateSyncPortDegradationCode, message: string, detail?: SceneStateSyncPortDegradationDetail): void;
+    dispose(): void;
+}
+/** Build the shared listener/sequence/echo core a shipped port is wrapped around. */
+export declare function createPortCore(options: PortCoreOptions): PortCore;
+/**
+ * Quantized equality signature for a slice value.
+ *
+ * Camera values are quantized before comparison because a renderer round-trip
+ * is never bit-exact: Cesium re-derives longitude/latitude/height from a
+ * Cartesian position, and a 2D map re-derives a zoom from a scale. Without a
+ * tolerance every applied camera would look like a fresh local change and the
+ * loop would never converge. The quantization is ~1 cm horizontally, nine
+ * significant digits of height, and 1/10000 of a degree of orientation — far
+ * below what any renderer displays, and far above float round-trip noise.
+ */
+export declare function sliceSignature(slice: SceneStateSyncSlice, value: unknown): string;
+//# sourceMappingURL=state-sync-port-kit.d.ts.map

package/scene-workspace/state-sync-port-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-sync-port-kit.d.ts","sourceRoot":"","sources":["../../../src/scene-workspace/state-sync-port-kit.ts"],"names":[],"mappings":"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"}

package/scene-workspace/state-sync-port-kit.js

@@ -0,0 +1,319 @@
+/**
+ * Shared machinery for the shipped renderer state-sync ports.
+ *
+ * `createSceneStateSynchronizer` is a transport: it revisions, coalesces, and
+ * delivers, but it never touches a renderer. Everything a *real* port has to get
+ * right — sequence discipline, echo suppression, bounded convergence, listener
+ * lifecycles, and honest degradation reporting — lives here once so the
+ * MapLibre and Cesium ports differ only in the renderer they drive.
+ *
+ * ## Echo suppression and convergence
+ *
+ * Every renderer change loop has the same hazard: state applied *from* the
+ * shared envelope makes the renderer fire its own change event, which would be
+ * re-published as a local change and bounce back forever. Two mechanisms close
+ * the loop, and both are needed:
+ *
+ * 1. **Applied-signature matching.** Immediately after applying a delivery the
+ *    port reads the renderer back and records a quantized signature of what the
+ *    renderer actually holds. The next renderer event whose signature matches is
+ *    an echo: it is published once with `causeRevision` set to the applied
+ *    revision, which the synchronizer classifies as `loop-suppressed` and drops.
+ *    Publishing the acknowledgement rather than swallowing it keeps the loop
+ *    closure observable instead of invisible.
+ * 2. **Lossy sides do not write back.** When a renderer cannot hold what it was
+ *    given (a globe pitch a 2D map clamps, a pose outside the zoom range) the
+ *    port applies its best effort, records a {@link SceneStateSyncPortDegradation},
+ *    and leaves the shared value alone. Writing the clamped value back would
+ *    drag every other view down to the least capable renderer's limits *and*
+ *    would be the one shape that can oscillate. With this rule a change
+ *    converges in one round trip: origin publishes, target applies, target
+ *    acknowledges, done.
+ *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface.
+ * @module
+ */
+import { HonuaSceneStateSyncError, SCENE_STATE_SYNC_KIND, SCENE_STATE_SYNC_VERSION, } from "./state-sync.js";
+const MAX_DEGRADATIONS = 256;
+const MAX_ATTRIBUTION_ID_LENGTH = 256;
+const MAX_ATTRIBUTION_SOURCE_LENGTH = 4_096;
+/**
+ * Reduce free-form attribution text to the credential-free identifier charset
+ * the `attribution` slice accepts.
+ *
+ * The slice carries identifiers, not markup: `"County orthophotography"` becomes
+ * `county-orthophotography`, and `<a href="...">OpenStreetMap</a> contributors`
+ * becomes `openstreetmap-contributors`. Anything with no identifier characters
+ * at all — or anything carrying a URL with credentials — yields `undefined`
+ * rather than a lossy guess, and the caller reports it as a degradation. The
+ * safe-id rule is a boundary to satisfy, not to relax.
+ *
+ * Reduction is a single bounded character pass rather than a chain of regular
+ * expressions: attribution text is attacker-influenceable (it arrives from a
+ * style document or a provider), and markup stripping with a pattern is a
+ * polynomial-backtracking shape.
+ */
+export function sceneAttributionId(value) {
+    if (typeof value !== "string" || value.length > MAX_ATTRIBUTION_SOURCE_LENGTH)
+        return undefined;
+    if (containsCredentialBearingUrl(value))
+        return undefined;
+    let slug = "";
+    let inTag = false;
+    let separatorPending = false;
+    for (const character of value) {
+        if (character === "<") {
+            inTag = true;
+            separatorPending = true;
+            continue;
+        }
+        if (character === ">") {
+            inTag = false;
+            separatorPending = true;
+            continue;
+        }
+        if (inTag)
+            continue;
+        const lowered = character.toLowerCase();
+        if (!isAttributionCharacter(lowered)) {
+            separatorPending = true;
+            continue;
+        }
+        // The charset allows `.`, `_`, and `:` inside an identifier but not as its
+        // first character, so a leading run of them is dropped rather than emitted.
+        if (slug.length === 0 && !isAlphanumeric(lowered))
+            continue;
+        if (separatorPending && slug.length > 0)
+            slug += "-";
+        separatorPending = false;
+        slug += lowered;
+        if (slug.length > MAX_ATTRIBUTION_ID_LENGTH)
+            return undefined;
+    }
+    while (slug.length > 0 && !isAlphanumeric(slug.charAt(slug.length - 1)))
+        slug = slug.slice(0, -1);
+    return slug.length === 0 ? undefined : slug;
+}
+function isAlphanumeric(character) {
+    return (character >= "a" && character <= "z") || (character >= "0" && character <= "9");
+}
+/** The identifier charset minus `-`, which the pass emits as a separator. */
+function isAttributionCharacter(character) {
+    return isAlphanumeric(character) || character === "." || character === "_" || character === ":";
+}
+/**
+ * Whether the text carries a URL with userinfo (`scheme://user:secret@host`).
+ *
+ * The slug reduction below keeps `:` and `.`, so a credential pair would
+ * survive it as a readable token. Scanned character by character rather than
+ * with a regular expression so a hostile string cannot drive backtracking.
+ */
+function containsCredentialBearingUrl(value) {
+    const AUTHORITY_TERMINATORS = "/?# \t\n";
+    let index = value.indexOf("://");
+    while (index !== -1) {
+        const authorityStart = index + 3;
+        let end = authorityStart;
+        while (end < value.length && !AUTHORITY_TERMINATORS.includes(value[end]))
+            end += 1;
+        if (value.slice(authorityStart, end).includes("@"))
+            return true;
+        index = value.indexOf("://", authorityStart);
+    }
+    return false;
+}
+/**
+ * Build an `attribution` slice value from live credit strings, dropping what
+ * cannot be reduced to a safe identifier and de-duplicating the rest.
+ */
+export function sceneAttributionValue(values) {
+    const ids = new Set();
+    for (const value of values) {
+        const id = sceneAttributionId(value);
+        if (id !== undefined)
+            ids.add(id);
+    }
+    return Object.freeze({ ids: Object.freeze([...ids].sort()) });
+}
+/** Build the shared listener/sequence/echo core a shipped port is wrapped around. */
+export function createPortCore(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const listeners = new Set();
+    const abortReleases = new Map();
+    const degradations = [];
+    const appliedSignatures = new Map();
+    const lastSignatures = new Map();
+    let unbind;
+    let sequence = 0;
+    let disposed = false;
+    function ensureBound() {
+        if (unbind === undefined && listeners.size > 0 && options.bind)
+            unbind = options.bind();
+    }
+    function releaseIfIdle() {
+        if (listeners.size === 0 && unbind) {
+            const release = unbind;
+            unbind = undefined;
+            release();
+        }
+    }
+    function emit(slice, value, causeRevision) {
+        sequence += 1;
+        const event = Object.freeze({
+            kind: SCENE_STATE_SYNC_KIND,
+            version: SCENE_STATE_SYNC_VERSION,
+            sequence,
+            emittedAt: now(),
+            slice,
+            value,
+            identity: options.identity,
+            ...(causeRevision === undefined ? {} : { causeRevision }),
+        });
+        for (const listener of [...listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A synchronizer that rejects one event must not break the renderer.
+            }
+        }
+    }
+    return {
+        id: options.id,
+        get degradations() {
+            return Object.freeze([...degradations]);
+        },
+        get disposed() {
+            return disposed;
+        },
+        subscribe(listener, signal) {
+            if (typeof listener !== "function")
+                throw new HonuaSceneStateSyncError("invalid-input", "listener must be a function");
+            if (disposed)
+                return () => undefined;
+            listeners.add(listener);
+            ensureBound();
+            const release = () => {
+                if (!listeners.delete(listener))
+                    return;
+                abortReleases.get(listener)?.();
+                abortReleases.delete(listener);
+                releaseIfIdle();
+            };
+            if (signal) {
+                if (signal.aborted) {
+                    release();
+                    return () => undefined;
+                }
+                const onAbort = () => release();
+                signal.addEventListener("abort", onAbort, { once: true });
+                abortReleases.set(listener, () => signal.removeEventListener("abort", onAbort));
+            }
+            return release;
+        },
+        publish(slice, value) {
+            if (disposed)
+                return "disposed";
+            const signature = sliceSignature(slice, value);
+            const applied = appliedSignatures.get(slice);
+            if (applied?.signatures.has(signature)) {
+                appliedSignatures.delete(slice);
+                lastSignatures.set(slice, signature);
+                emit(slice, value, applied.revision);
+                return "acknowledged";
+            }
+            if (lastSignatures.get(slice) === signature)
+                return "duplicate";
+            appliedSignatures.delete(slice);
+            lastSignatures.set(slice, signature);
+            emit(slice, value);
+            return "published";
+        },
+        markApplied(slice, revision, ...values) {
+            const signatures = new Set(values.map((value) => sliceSignature(slice, value)));
+            appliedSignatures.set(slice, { revision, signatures });
+            const first = values[0];
+            lastSignatures.set(slice, sliceSignature(slice, first));
+        },
+        degrade(slice, code, message, detail = {}) {
+            const degradation = Object.freeze({
+                portId: options.id,
+                slice,
+                code,
+                message,
+                at: now(),
+                ...(detail.revision === undefined ? {} : { revision: detail.revision }),
+                ...(detail.requested === undefined ? {} : { requested: detail.requested }),
+                ...(detail.applied === undefined ? {} : { applied: detail.applied }),
+            });
+            degradations.push(degradation);
+            if (degradations.length > MAX_DEGRADATIONS)
+                degradations.splice(0, degradations.length - MAX_DEGRADATIONS);
+            try {
+                options.onDegraded?.(degradation);
+            }
+            catch {
+                // Observers cannot break renderer application.
+            }
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            for (const release of abortReleases.values())
+                release();
+            abortReleases.clear();
+            listeners.clear();
+            appliedSignatures.clear();
+            lastSignatures.clear();
+            releaseIfIdle();
+        },
+    };
+}
+/**
+ * Quantized equality signature for a slice value.
+ *
+ * Camera values are quantized before comparison because a renderer round-trip
+ * is never bit-exact: Cesium re-derives longitude/latitude/height from a
+ * Cartesian position, and a 2D map re-derives a zoom from a scale. Without a
+ * tolerance every applied camera would look like a fresh local change and the
+ * loop would never converge. The quantization is ~1 cm horizontally, nine
+ * significant digits of height, and 1/10000 of a degree of orientation — far
+ * below what any renderer displays, and far above float round-trip noise.
+ */
+export function sliceSignature(slice, value) {
+    if (slice !== "camera")
+        return stableStringify(value);
+    if (value === null || typeof value !== "object")
+        return stableStringify(value);
+    const camera = value;
+    return [
+        quantize(camera.longitude, 7),
+        quantize(camera.latitude, 7),
+        quantizeSignificant(camera.height),
+        quantize(camera.heading, 4),
+        quantize(camera.pitch, 4),
+        quantize(camera.roll, 4),
+    ].join("|");
+}
+function quantize(value, decimals) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "-";
+    const fixed = value.toFixed(decimals);
+    return fixed === `-${(0).toFixed(decimals)}` ? (0).toFixed(decimals) : fixed;
+}
+function quantizeSignificant(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "-";
+    return Number(value.toPrecision(9)).toString();
+}
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+        .join(",")}}`;
+}

package/scene-workspace/state-sync.d.ts

@@ -1,9 +1,42 @@
+/**
+ * Versioned envelope that keeps two renderers — typically a Cesium scene and a
+ * MapLibre map — on the same camera, selection, filter, time, and detail state.
+ *
+ * The synchronizer is transport-neutral: it maps slices onto a caller-supplied
+ * port and reports per-slice fidelity instead of silently degrading.
+ *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface; the
+ *   envelope kind, version, and slice vocabulary are stable through 0.1.x, and
+ *   diagnostic codes grow additively.
+ * @module
+ */
 import type { FeatureSelectionTarget, FilterClause } from "../exploration/index.js";
-import type { SceneCameraState, SceneDetailState, SceneTimelineState } from "./types.js";
+import type { SceneCameraState, SceneDetailState, SceneTimelineState, SceneWorkspaceSlice } from "./types.js";
 export declare const SCENE_STATE_SYNC_KIND: "honua.scene-state-sync";
 export declare const SCENE_STATE_SYNC_VERSION: "1.0";
 export declare const SCENE_STATE_SYNC_SLICES: readonly ["camera", "selection", "filters", "time", "detail", "attribution", "realtime"];
 export type SceneStateSyncSlice = (typeof SCENE_STATE_SYNC_SLICES)[number];
+/**
+ * How the two slice vocabularies relate (issue #1049, REQ-006).
+ *
+ * They are deliberately different sizes because they answer different
+ * questions. `SCENE_STATE_SYNC_SLICES` is a *wire* vocabulary: the seven pieces
+ * of state that two renderers in the same application have to agree on.
+ * `SCENE_WORKSPACE_SLICES` is a *store* vocabulary: the thirteen change
+ * notifications one workspace publishes to its own subscribers.
+ *
+ * The overlap is exactly what crosses renderers, and this table names it. The
+ * workspace-only members are single-application concerns with nothing to
+ * synchronize — `all` is a subscription wildcard, and `scene`, `layers`,
+ * `primitives`, `diagnostics`, `evidence`, and `history` describe what one
+ * renderer was asked to draw and what it reported back, which is per-renderer by
+ * construction. `attribution` maps to `null` in the other direction: it is
+ * derived from what each renderer actually credits rather than stored as
+ * workspace state.
+ *
+ * The only rename across the boundary is `time` (wire) / `timeline` (store).
+ */
+export declare const SCENE_STATE_SYNC_SLICE_WORKSPACE_CROSSWALK: Readonly<Record<SceneStateSyncSlice, SceneWorkspaceSlice | null>>;
 export type SceneStateSyncRenderer = "maplibre" | "cesium" | "custom";
 export type SceneStateSyncFidelity = "exact" | "equivalent" | "unsupported";
 export interface SceneStateSyncIdentity {

package/scene-workspace/state-sync.d.ts.map

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

package/scene-workspace/state-sync.js

@@ -1,3 +1,15 @@
+/**
+ * Versioned envelope that keeps two renderers — typically a Cesium scene and a
+ * MapLibre map — on the same camera, selection, filter, time, and detail state.
+ *
+ * The synchronizer is transport-neutral: it maps slices onto a caller-supplied
+ * port and reports per-slice fidelity instead of silently degrading.
+ *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface; the
+ *   envelope kind, version, and slice vocabulary are stable through 0.1.x, and
+ *   diagnostic codes grow additively.
+ * @module
+ */
 export const SCENE_STATE_SYNC_KIND = "honua.scene-state-sync";
 export const SCENE_STATE_SYNC_VERSION = "1.0";
 export const SCENE_STATE_SYNC_SLICES = [
@@ -9,6 +21,35 @@ export const SCENE_STATE_SYNC_SLICES = [
     "attribution",
     "realtime",
 ];
+/**
+ * How the two slice vocabularies relate (issue #1049, REQ-006).
+ *
+ * They are deliberately different sizes because they answer different
+ * questions. `SCENE_STATE_SYNC_SLICES` is a *wire* vocabulary: the seven pieces
+ * of state that two renderers in the same application have to agree on.
+ * `SCENE_WORKSPACE_SLICES` is a *store* vocabulary: the thirteen change
+ * notifications one workspace publishes to its own subscribers.
+ *
+ * The overlap is exactly what crosses renderers, and this table names it. The
+ * workspace-only members are single-application concerns with nothing to
+ * synchronize — `all` is a subscription wildcard, and `scene`, `layers`,
+ * `primitives`, `diagnostics`, `evidence`, and `history` describe what one
+ * renderer was asked to draw and what it reported back, which is per-renderer by
+ * construction. `attribution` maps to `null` in the other direction: it is
+ * derived from what each renderer actually credits rather than stored as
+ * workspace state.
+ *
+ * The only rename across the boundary is `time` (wire) / `timeline` (store).
+ */
+export const SCENE_STATE_SYNC_SLICE_WORKSPACE_CROSSWALK = Object.freeze({
+    camera: "camera",
+    selection: "selection",
+    filters: "filters",
+    time: "timeline",
+    detail: "detail",
+    attribution: null,
+    realtime: "realtime",
+});
 export class HonuaSceneStateSyncError extends Error {
     code;
     constructor(code, message, options = {}) {
@@ -25,6 +66,7 @@ const MAX_SYNCHRONOUS_SUBSCRIBE_EVENTS = 32;
 const MAX_SELECTION = 2_048;
 const MAX_FILTERS = 128;
 const MAX_ATTRIBUTIONS = 128;
+const MAX_TIME_SPEED = 1_000_000;
 const MAX_JSON_NODES = 4_096;
 const MAX_JSON_DEPTH = 24;
 const MAX_JSON_PROPERTIES = 256;
@@ -742,11 +784,16 @@ function normalizeTime(foreign) {
     };
     const playing = optionalDataProperty(foreign, "playing");
     const progress = optionalDataProperty(foreign, "progress");
+    // Clock rate is signed (a globe can run time backwards) and bounded, so a
+    // renderer cannot put an unusable multiplier on the wire.
+    const speed = optionalDataProperty(foreign, "speed");
     if (playing !== undefined && typeof playing !== "boolean")
         throw new HonuaSceneStateSyncError("invalid-input", "time.playing is invalid");
     if (progress !== undefined &&
         (typeof progress !== "number" || !Number.isFinite(progress) || progress < 0 || progress > 1))
         throw new HonuaSceneStateSyncError("invalid-input", "time.progress is invalid");
+    if (speed !== undefined && (typeof speed !== "number" || !Number.isFinite(speed) || Math.abs(speed) > MAX_TIME_SPEED))
+        throw new HonuaSceneStateSyncError("invalid-input", "time.speed is invalid");
     const currentTime = iso("currentTime");
     const startTime = iso("startTime");
     const endTime = iso("endTime");
@@ -756,6 +803,7 @@ function normalizeTime(foreign) {
         ...(endTime === undefined ? {} : { endTime }),
         ...(playing === undefined ? {} : { playing }),
         ...(progress === undefined ? {} : { progress }),
+        ...(speed === undefined ? {} : { speed: Object.is(speed, -0) ? 0 : speed }),
     });
 }
 function normalizeDetail(foreign) {

package/scene-workspace/types.d.ts

@@ -4,6 +4,8 @@
  * These types intentionally describe state and adapter events without
  * importing Cesium, MapLibre, or any rendering package.
  *
+ * @beta Part of the beta `@honua/app-platform/scene-workspace` surface; these
+ *   state shapes are not renamed or removed through 0.1.x and grow additively.
  * @module
  */
 import type { FeatureId, SourceId } from "../contract/types.js";
@@ -39,6 +41,12 @@ export interface SceneTimelineState {
     readonly endTime?: string;
     readonly playing?: boolean;
     readonly progress?: number;
+    /**
+     * Clock rate: simulated seconds advanced per real second. Renderer-neutral,
+     * and bound to Cesium's `Clock.multiplier` by the scene adapter's time
+     * binding. Omit it and the renderer's own rate is left alone.
+     */
+    readonly speed?: number;
 }
 export interface SceneEvidenceReference {
     readonly id: string;