@fabricorg/sdui-release 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+import { PortableJsonSchema } from '@fabricorg/platform';
+export { JsonValue } from '@fabricorg/platform';
+import { UsageContractDocument } from '@fabricorg/gen-capability';
+import { AssemblyLockfile } from '@fabricorg/assembly';
+
+/**
+ * Version of the SDUI document contract. A vertical negotiates on this, not on
+ * this package's version, and it moves only when the serialized shape changes.
+ */
+declare const SDUI_DOCUMENT_FORMAT_VERSION: 1;
+/**
+ * Version of the SDUI token-set contract.
+ */
+declare const SDUI_TOKEN_SET_FORMAT_VERSION: 1;
+/**
+ * Version of the SDUI component-pack contract.
+ */
+declare const SDUI_COMPONENT_PACK_FORMAT_VERSION: 1;
+/**
+ * Version of the promoted SDUI release contract.
+ */
+declare const SDUI_RELEASE_FORMAT_VERSION: 2;
+/**
+ * A capability read reference embedded in fragment props. The `capability://`
+ * scheme ties a data binding to a published view; the host resolves it through
+ * `ProjectionHost`, never through a direct query.
+ */
+interface SduiCapabilityRef {
+    $ref: `capability://${string}`;
+}
+/**
+ * A value that may appear in fragment props: a JSON literal, an array, an
+ * object, or a `capability://` read reference. Direct mutation endpoints,
+ * API URLs, or code strings are not valid fragment values.
+ */
+type SduiFragmentValue = string | number | boolean | null | SduiFragmentValue[] | SduiCapabilityRef | {
+    [key: string]: SduiFragmentValue;
+};
+/**
+ * An action declared on a fragment. The `intent` must be a `capability://`
+ * reference to a published action intent; the host dispatches it through
+ * `PlatformHost`, preserving governance. A bare endpoint URL, function name,
+ * or inline script is a mutation bypass and is rejected.
+ */
+interface SduiActionRef {
+    intent: `capability://${string}`;
+    params?: Record<string, SduiFragmentValue>;
+}
+/**
+ * A node in an SDUI document tree. A fragment either renders a component from
+ * a declared pack, binds data from a capability view, or both. Actions on a
+ * fragment are always capability action-intent references — never direct
+ * mutations.
+ */
+interface SduiFragment {
+    /** Unique identifier within the document. */
+    id: string;
+    /** Namespaced component (`pack.Component`) or a core component name. */
+    component?: string;
+    /** Props for the component; values may be literals or capability refs. */
+    props?: Record<string, SduiFragmentValue>;
+    /** Named slot this fragment fills in its parent component. */
+    slot?: string;
+    /** A capability view reference for data-driven fragments. */
+    dataRef?: `capability://${string}`;
+    /** Action handlers; every entry must be a capability action-intent reference. */
+    actions?: Record<string, SduiActionRef>;
+    /** Child fragments. */
+    children?: SduiFragment[];
+}
+type SduiTokenType = "color" | "spacing" | "fontSize" | "fontWeight" | "radius" | "border" | "shadow";
+interface SduiToken {
+    type: SduiTokenType;
+    value: string;
+    description?: string;
+}
+/**
+ * A versioned set of design tokens. Tokens are semantic, not literal CSS — a
+ * renderer maps them to its own platform. Two channels consuming the same
+ * token set apply the same visual intent through different renderings.
+ */
+interface SduiTokenSet {
+    formatVersion: typeof SDUI_TOKEN_SET_FORMAT_VERSION;
+    name: string;
+    version: string;
+    tokens: Record<string, SduiToken>;
+}
+interface SduiComponentDefinition {
+    /** Roles this component implements (for adoption-binding validation). */
+    implements?: string[];
+    /** JSON Schema for component props. */
+    propsSchema?: PortableJsonSchema;
+    /** Named slots this component accepts. */
+    slots?: string[];
+}
+/**
+ * A versioned pack of SDUI components. Compatible with the adoption-bindings
+ * `ComponentPackManifest` but adds prop schemas and slot declarations so a
+ * document can be validated without a renderer.
+ */
+interface SduiComponentPack {
+    formatVersion: typeof SDUI_COMPONENT_PACK_FORMAT_VERSION;
+    pack: string;
+    namespace: string;
+    version: string;
+    /** SHA-256 digest of the published component-pack artifact. */
+    artifactDigest: string;
+    /**
+     * Where this pack is loaded from when it is delivered as a federated
+     * remote. The artifact digest identifies the pack that was reviewed; this
+     * is what a shell actually executes, so validation requires the two to be
+     * locked together or the review covers something other than what runs.
+     */
+    remote?: SduiComponentPackRemote;
+    components: Record<string, SduiComponentDefinition>;
+}
+/** Delivery binding for a federated component pack. */
+interface SduiComponentPackRemote {
+    /** Remote entry URL the shell loads. */
+    entry: string;
+    /** Subresource-integrity value for that entry, e.g. `sha384-…`. */
+    integrity: string;
+    /** Exposed module path keyed by the component name it provides. */
+    exposes: Record<string, string>;
+}
+interface SduiComponentPackReference {
+    pack: string;
+    namespace: string;
+    /** Semver range, e.g. `^1.0.0`. */
+    range: string;
+}
+interface SduiTokenSetReference {
+    name: string;
+    version: string;
+}
+/**
+ * A versioned SDUI document: a tree of fragments, a token-set reference, and
+ * the component packs it depends on. This is the build-time input; the release
+ * is the validated, resolved output.
+ */
+interface SduiDocument {
+    formatVersion: typeof SDUI_DOCUMENT_FORMAT_VERSION;
+    name: string;
+    version: string;
+    /** The tree rendered when no variant is selected. */
+    root: SduiFragment;
+    /**
+     * Alternative trees a compositor may select at request time, for experiment
+     * arms and personalization. Every variant is enumerated here and validated
+     * against the same grants as `root`, and all of them are covered by the
+     * release digest.
+     *
+     * Enumeration is what makes selection safe. A selector that can produce a
+     * tree outside this set cannot be validated at promotion, so "selection may
+     * never widen grants" would be unenforceable rather than merely unenforced.
+     */
+    variants?: SduiVariant[];
+    tokenSet: SduiTokenSetReference;
+    componentPacks: SduiComponentPackReference[];
+}
+/** One selectable alternative to a document's default tree. */
+interface SduiVariant {
+    /** Stable key the compositor matches on. Unique within the document. */
+    id: string;
+    /** The audience or experiment arm this arm serves. */
+    description?: string;
+    root: SduiFragment;
+}
+interface ResolvedSduiComponentPack {
+    pack: string;
+    namespace: string;
+    version: string;
+    range: string;
+    artifactDigest: string;
+    /**
+     * The locked delivery binding, carried onto the release so the digest
+     * identifies which remote a channel is expected to load. Omitting it would
+     * let two releases differing only in their remote share a digest.
+     */
+    remote?: SduiComponentPackRemote;
+}
+/**
+ * A promoted, validated, immutable SDUI release. It bundles a document, a
+ * resolved token set, and locked component packs. Two channels (web, mobile,
+ * CLI) can consume the same release and render it through their own renderers
+ * while reads and actions remain capability references.
+ */
+interface SduiRelease {
+    formatVersion: typeof SDUI_RELEASE_FORMAT_VERSION;
+    /** SHA-256 of the canonical document, token set, resolved packs, grants, and assembly identity. */
+    releaseDigest: string;
+    /** Approved application assembly this release was validated against. */
+    assemblyDigest: string;
+    document: SduiDocument;
+    tokenSet: SduiTokenSet;
+    componentPacks: ResolvedSduiComponentPack[];
+    grants: SduiAuthorizationGrants;
+}
+type SduiFindingCode = "unknown_component" | "incompatible_pack" | "unauthorized_data_ref" | "denied_view_ref" | "mutation_bypass" | "denied_intent_ref" | "intent_action_not_found" | "invalid_fragment" | "invalid_action_ref" | "unknown_token" | "duplicate_fragment_id" | "invalid_token_set" | "invalid_component_pack" | "invalid_document" | "missing_token_set" | "missing_component_pack" | "component_pack_not_in_assembly" | "capability_contract_not_in_assembly" | "duplicate_variant_id" | "fragment_grant_exceeds_release" | "remote_not_locked";
+interface SduiFinding {
+    code: SduiFindingCode;
+    path: string;
+    message: string;
+}
+interface SduiValidationResult {
+    valid: boolean;
+    findings: SduiFinding[];
+    release: SduiRelease | undefined;
+}
+/**
+ * Explicit capability references authorized for an SDUI release.
+ *
+ * The presence of a view or action in a supplied usage contract proves that
+ * the capability publishes it, not that this document may use it. The
+ * experience host must therefore provide both grant lists explicitly.
+ */
+interface SduiAuthorizationGrants {
+    /** Full `capability://namespace/view` references allowed in data bindings. */
+    views: readonly string[];
+    /** Full `capability://namespace/intent` references allowed in actions. */
+    intents: readonly string[];
+    /**
+     * Per-fragment narrowing, keyed by fragment id.
+     *
+     * The release-wide lists above are the ceiling. A listed fragment may use
+     * only the references named for it, and the narrowing is inherited by that
+     * fragment's children, so a page assembled from several teams' fragments
+     * gets least privilege rather than the union of everything any of them
+     * needs. A fragment entry can only ever narrow: naming a reference outside
+     * the release-wide list is an authoring error and is reported rather than
+     * silently granted.
+     *
+     * Keys are fragment ids, which are unique within a tree but may repeat
+     * across variants, so two variants using the same fragment id share one
+     * entry. Give them distinct ids when they need distinct narrowing. This
+     * cannot widen either fragment, since narrowing stays an intersection.
+     */
+    fragments?: Record<string, SduiFragmentGrants>;
+}
+/** References one fragment subtree may use, drawn from the release-wide lists. */
+interface SduiFragmentGrants {
+    views?: readonly string[];
+    intents?: readonly string[];
+}
+interface SduiValidationInput {
+    document: SduiDocument;
+    tokenSet: SduiTokenSet;
+    /** Available component packs for version resolution. */
+    componentPacks: SduiComponentPack[];
+    /** Capability contracts available for data-ref and action validation. */
+    contracts: UsageContractDocument[];
+    /**
+     * Explicit authorization grants for every capability view and action
+     * reference used by the document. Contract membership alone never grants
+     * access.
+     */
+    grants: SduiAuthorizationGrants;
+    /** Approved resolved application composition. */
+    assembly: AssemblyLockfile;
+    /** Core component vocabulary every renderer implements. */
+    coreComponents?: readonly string[];
+}
+
+declare function assertSduiTokenSet(value: unknown, path?: string): asserts value is SduiTokenSet;
+declare function assertSduiComponentPack(value: unknown, path?: string): asserts value is SduiComponentPack;
+declare function assertSduiFragment(value: unknown, path?: string): asserts value is SduiFragment;
+declare function assertSduiDocument(value: unknown, path?: string): asserts value is SduiDocument;
+/**
+ * Validate the grant envelope before semantic release checks. Grants are
+ * intentionally references rather than capability names: a capability may
+ * publish several views and intents with different authorization decisions.
+ */
+declare function assertSduiAuthorizationGrants(value: unknown, path?: string): asserts value is SduiAuthorizationGrants;
+/** Validate a promoted release loaded from an untyped persistence or network seam. */
+declare function assertSduiRelease(value: unknown, path?: string): asserts value is SduiRelease;
+
+/**
+ * Validate an SDUI document and its dependencies, producing a promoted release
+ * when every check passes. This is the single build gate: it rejects unknown
+ * components, incompatible packs, unauthorized data references, and mutation
+ * bypasses. Returns every finding rather than throwing, so one CI run tells a
+ * vertical everything it has to change. Use {@link assertSduiReleaseValid} to
+ * throw on the first invalid result.
+ */
+declare function validateSduiRelease(input: SduiValidationInput): SduiValidationResult;
+/**
+ * Throw with every finding listed, for use as a build step. Returns the
+ * promoted release when valid.
+ */
+declare function assertSduiReleaseValid(input: SduiValidationInput): SduiRelease;
+
+/**
+ * Compute the canonical release digest for a valid release. Two releases with
+ * the same document, token set, and resolved packs produce the same digest,
+ * so a channel can verify it is consuming the exact release it was built for.
+ */
+declare function computeReleaseDigest(document: SduiDocument, tokenSet: SduiTokenSet, componentPacks: ResolvedSduiComponentPack[], grants: SduiAuthorizationGrants, assemblyDigest: string): string;
+/** Reject promoted release content that no longer matches its immutable digest. */
+declare function assertSduiReleaseIntegrity(release: SduiRelease): void;
+
+/**
+ * A channel is a rendering target (web, mobile, CLI). A channel consumes a
+ * validated release and resolves capability references through its own host
+ * adapters. Reads go through `ProjectionHost`; actions go through
+ * `PlatformHost`. The channel never interprets or bypasses capability
+ * references — it renders fragments and forwards action intents.
+ */
+interface SduiChannel {
+    id: string;
+    /** Core components this channel renderer implements. */
+    coreComponents: readonly string[];
+    /** Consume a validated release; returns the release if the channel's core
+     *  vocabulary covers every core component the document uses. */
+    consume(release: SduiRelease): SduiChannelConsumptionResult;
+}
+interface SduiChannelConsumptionResult {
+    /** The release the channel consumed. */
+    release: SduiRelease;
+    /** Whether the channel's core vocabulary covers the document. */
+    compatible: boolean;
+    /** Core components the document uses that the channel does not implement. */
+    missingCoreComponents: string[];
+}
+/**
+ * Create a channel that consumes a release. The channel verifies that every
+ * core component the document references is in its vocabulary; pack-namespaced
+ * components are resolved from the release's locked packs, not the channel.
+ */
+declare function createSduiChannel(id: string, coreComponents: readonly string[]): SduiChannel;
+
+declare const SDUI_DOCUMENT_JSON_SCHEMA: PortableJsonSchema;
+declare const SDUI_RELEASE_JSON_SCHEMA: PortableJsonSchema;
+
+export { type ResolvedSduiComponentPack, SDUI_COMPONENT_PACK_FORMAT_VERSION, SDUI_DOCUMENT_FORMAT_VERSION, SDUI_DOCUMENT_JSON_SCHEMA, SDUI_RELEASE_FORMAT_VERSION, SDUI_RELEASE_JSON_SCHEMA, SDUI_TOKEN_SET_FORMAT_VERSION, type SduiActionRef, type SduiAuthorizationGrants, type SduiCapabilityRef, type SduiChannel, type SduiChannelConsumptionResult, type SduiComponentDefinition, type SduiComponentPack, type SduiComponentPackReference, type SduiDocument, type SduiFinding, type SduiFindingCode, type SduiFragment, type SduiFragmentValue, type SduiRelease, type SduiToken, type SduiTokenSet, type SduiTokenSetReference, type SduiTokenType, type SduiValidationInput, type SduiValidationResult, assertSduiAuthorizationGrants, assertSduiComponentPack, assertSduiDocument, assertSduiFragment, assertSduiRelease, assertSduiReleaseIntegrity, assertSduiReleaseValid, assertSduiTokenSet, computeReleaseDigest, createSduiChannel, validateSduiRelease };