@wp-typia/project-tools 0.19.3 → 0.20.0

package/README.md

@@ -17,6 +17,8 @@ Supported public imports:
 
 - `@wp-typia/project-tools`
 - `@wp-typia/project-tools/schema-core`
+- `@wp-typia/project-tools/ai-artifacts`
+- `@wp-typia/project-tools/typia-llm`
 
 Implementation note:
 
@@ -48,6 +50,20 @@ import {
 import { normalizeEndpointAuthDefinition } from '@wp-typia/project-tools/schema-core';
 ```
 
+```ts
+import {
+  syncWordPressAiArtifacts,
+  type AbilitySpecCatalog,
+} from '@wp-typia/project-tools/ai-artifacts';
+```
+
+```ts
+import {
+  syncTypiaLlmAdapterModule,
+  projectTypiaLlmApplicationArtifact,
+} from '@wp-typia/project-tools/typia-llm';
+```
+
 `BlockGeneratorService` is the additive typed orchestration boundary for built-in
 block scaffolds. Built-in templates no longer ship structural, TS/TSX, style,
 or block-local `render.php` Mustache files for built-in `types.ts`,
@@ -81,3 +97,10 @@ and `inspectBlockGeneration(...)`. The layer contract record lives in
 [`docs/external-template-layer-composition.md`](https://imjlk.github.io/wp-typia/architecture/external-template-layer-composition/).
 
 If you need metadata sync, editor helpers, validation helpers, or other generated-project runtime utilities, import them directly from `@wp-typia/block-runtime/*`.
+
+`@wp-typia/project-tools/typia-llm` is an opt-in build-time adapter target for
+downstream TypeScript-first tool/function consumers. It renders the generated
+`typia.llm` TypeScript module from endpoint manifests and canonical contract
+types, and exposes JSON-friendly projection helpers for compiled
+`typia.llm.application(...)` and `typia.llm.structuredOutput(...)` results. It
+does not add a generated-project runtime dependency on `typia.llm`.

package/dist/runtime/ability-spec.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Marks behavioral flags that shape how an ability should be exposed to
+ * WordPress-native AI and workflow consumers.
+ */
+export interface AbilityAnnotationSpec {
+    /** Indicates that invoking the ability mutates persisted state. */
+    destructive?: boolean;
+    /** Indicates that repeated invocations with the same input are safe. */
+    idempotent?: boolean;
+    /** Indicates that the ability only reads data and does not mutate state. */
+    readonly?: boolean;
+}
+/**
+ * Describes a shared category bucket that multiple projected abilities can
+ * reference.
+ */
+export interface AbilityCategorySpec {
+    /** Stable category identifier written into the generated abilities document. */
+    id: string;
+    /** Human-readable label presented by downstream discovery surfaces. */
+    label: string;
+}
+/**
+ * Defines optional metadata that an adapter can use when exposing abilities to
+ * MCP-aware consumers.
+ */
+export interface AbilityMcpProjectionSpec {
+    /** Marks an ability as safe to expose through an opt-in public MCP adapter. */
+    public?: boolean;
+}
+/**
+ * Carries WordPress-specific metadata that should survive ability projection
+ * without taking ownership away from the endpoint manifest.
+ */
+export interface AbilityMetaSpec {
+    /** Allows forward-compatible metadata keys owned by the ability layer. */
+    [key: string]: unknown;
+    /** Namespaces optional MCP adapter hints away from core WordPress metadata. */
+    mcp?: AbilityMcpProjectionSpec;
+}
+/**
+ * Describes WordPress-owned metadata that merges with an endpoint manifest when
+ * building projected ability artifacts.
+ */
+export interface AbilitySpec {
+    /** Behavioral annotations that describe how the ability should be treated. */
+    annotations?: AbilityAnnotationSpec;
+    /** Category identifier that must resolve inside the shared catalog map. */
+    categoryId: string;
+    /** PHP callback that executes the ability on the server. */
+    executeCallback: string;
+    /** Human-readable label shown to downstream discovery clients. */
+    label: string;
+    /** Optional WordPress-owned metadata preserved in the projected document. */
+    meta?: AbilityMetaSpec;
+    /** PHP callback that gates access before execution. */
+    permissionCallback: string;
+    /** Controls whether the projected ability stays visible to REST discovery. */
+    showInRest?: boolean;
+}
+/**
+ * Groups all WordPress-owned ability specs and category definitions for a
+ * projection unit.
+ */
+export interface AbilitySpecCatalog {
+    /** Ability definitions keyed by the endpoint operationId they augment. */
+    abilities: Record<string, AbilitySpec>;
+    /** Shared category definitions keyed by category id. */
+    categories: Record<string, AbilityCategorySpec>;
+}
+/**
+ * Documents which fields remain owned by AbilitySpec metadata versus the
+ * endpoint manifest when the two surfaces are merged.
+ */
+export declare const ABILITY_SPEC_MERGE_BOUNDARY: {
+    /** Property paths that must come from the AbilitySpec layer. */
+    readonly abilitySpecOwns: readonly ["categoryId", "category.label", "label", "executeCallback", "permissionCallback", "annotations.readonly", "annotations.destructive", "annotations.idempotent", "meta.mcp.public", "showInRest"];
+    readonly endpointManifestOwns: readonly ["operationId", "method", "path", "summary", "queryContract", "bodyContract", "responseContract", "auth", "authMode", "wordpressAuth"];
+};
+/**
+ * Resolves and validates the category referenced by an AbilitySpec.
+ *
+ * @param abilitySpec Ability definition that references a shared category id.
+ * @param categories Available category map for the current projection scope.
+ * @param operationId Endpoint identifier used in validation errors.
+ * @returns The resolved category definition.
+ * @throws When the category id is missing from the catalog.
+ * @throws When the resolved category definition reports a different id.
+ */
+export declare function resolveAbilityCategorySpec(abilitySpec: AbilitySpec, categories: Record<string, AbilityCategorySpec>, operationId: string): AbilityCategorySpec;

package/dist/runtime/ability-spec.js

@@ -0,0 +1,51 @@
+/**
+ * Documents which fields remain owned by AbilitySpec metadata versus the
+ * endpoint manifest when the two surfaces are merged.
+ */
+export const ABILITY_SPEC_MERGE_BOUNDARY = {
+    /** Property paths that must come from the AbilitySpec layer. */
+    abilitySpecOwns: [
+        'categoryId',
+        'category.label',
+        'label',
+        'executeCallback',
+        'permissionCallback',
+        'annotations.readonly',
+        'annotations.destructive',
+        'annotations.idempotent',
+        'meta.mcp.public',
+        'showInRest',
+    ],
+    endpointManifestOwns: [
+        'operationId',
+        'method',
+        'path',
+        'summary',
+        'queryContract',
+        'bodyContract',
+        'responseContract',
+        'auth',
+        'authMode',
+        'wordpressAuth',
+    ],
+};
+/**
+ * Resolves and validates the category referenced by an AbilitySpec.
+ *
+ * @param abilitySpec Ability definition that references a shared category id.
+ * @param categories Available category map for the current projection scope.
+ * @param operationId Endpoint identifier used in validation errors.
+ * @returns The resolved category definition.
+ * @throws When the category id is missing from the catalog.
+ * @throws When the resolved category definition reports a different id.
+ */
+export function resolveAbilityCategorySpec(abilitySpec, categories, operationId) {
+    const category = categories[abilitySpec.categoryId];
+    if (!category) {
+        throw new Error(`Operation "${operationId}" references unknown AbilitySpec category "${abilitySpec.categoryId}".`);
+    }
+    if (category.id !== abilitySpec.categoryId) {
+        throw new Error(`AbilitySpec category "${abilitySpec.categoryId}" resolves to category id "${category.id}".`);
+    }
+    return category;
+}

package/dist/runtime/ai-artifacts.d.ts

@@ -0,0 +1,39 @@
+import type { ArtifactSyncExecutionOptions } from '@wp-typia/block-runtime/metadata-core';
+import { buildWordPressAiArtifacts, type ProjectedWordPressAbilitiesDocument } from './wordpress-ai.js';
+export { buildWordPressAiArtifacts, buildWordPressAbilitiesDocument, projectWordPressAiSchema, } from './wordpress-ai.js';
+export type { AbilityAnnotationSpec, AbilityCategorySpec, AbilityMcpProjectionSpec, AbilityMetaSpec, AbilitySpec, AbilitySpecCatalog, ProjectedWordPressAbilityDefinition, ProjectedWordPressAbilitiesDocument, WordPressAiInputSchemaTransformContext, } from './wordpress-ai.js';
+type BuildWordPressAiArtifactsParameters = Parameters<typeof buildWordPressAiArtifacts>[0];
+/**
+ * Configures where the generated WordPress AI artifacts should be written or
+ * verified on disk.
+ */
+export interface SyncWordPressAiArtifactsOptions extends ArtifactSyncExecutionOptions, BuildWordPressAiArtifactsParameters {
+    /** Destination path for the generated `*.abilities.json` document. */
+    abilitiesDocumentFile: string;
+    /** Destination path for the generated `*.ai.schema.json` document. */
+    aiSchemaFile: string;
+}
+/**
+ * Describes the generated artifact payloads and the file paths they were
+ * written to or verified against.
+ */
+export interface SyncWordPressAiArtifactsResult {
+    /** Generated abilities document content. */
+    abilitiesDocument: ProjectedWordPressAbilitiesDocument;
+    /** Destination path for the generated abilities document. */
+    abilitiesDocumentPath: string;
+    /** Generated AI response schema content. */
+    aiResponseSchema: Record<string, unknown>;
+    /** Destination path for the generated AI response schema. */
+    aiSchemaPath: string;
+    /** True when files were only verified, false when they were written. */
+    check: boolean;
+}
+/**
+ * Builds WordPress AI artifact documents from a manifest-first contract surface
+ * and then writes or verifies the generated JSON files on disk.
+ *
+ * @param options Artifact destinations plus the same manifest/category/schema inputs used by `buildWordPressAiArtifacts()`.
+ * @returns Generated documents and the output file paths that were checked or written.
+ */
+export declare function syncWordPressAiArtifacts({ abilitiesDocumentFile, aiSchemaFile, check, ...buildOptions }: SyncWordPressAiArtifactsOptions): Promise<SyncWordPressAiArtifactsResult>;

package/dist/runtime/ai-artifacts.js

@@ -0,0 +1,68 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { buildWordPressAiArtifacts, } from './wordpress-ai.js';
+export { buildWordPressAiArtifacts, buildWordPressAbilitiesDocument, projectWordPressAiSchema, } from './wordpress-ai.js';
+function normalizeGeneratedArtifactContent(content) {
+    return content.replace(/\r\n?/g, '\n');
+}
+async function reconcileGeneratedAiArtifacts(artifacts, check) {
+    if (!check) {
+        for (const artifact of artifacts) {
+            await mkdir(path.dirname(artifact.filePath), {
+                recursive: true,
+            });
+            await writeFile(artifact.filePath, artifact.content, 'utf8');
+        }
+        return;
+    }
+    const issues = [];
+    for (const artifact of artifacts) {
+        try {
+            const current = normalizeGeneratedArtifactContent(await readFile(artifact.filePath, 'utf8'));
+            const expected = normalizeGeneratedArtifactContent(artifact.content);
+            if (current !== expected) {
+                issues.push(`- ${artifact.filePath} (stale)`);
+            }
+        }
+        catch (error) {
+            const code = error && typeof error === 'object' && 'code' in error
+                ? error.code
+                : undefined;
+            if (code === 'ENOENT') {
+                issues.push(`- ${artifact.filePath} (missing)`);
+                continue;
+            }
+            issues.push(`- ${artifact.filePath} (unreadable: ${error instanceof Error ? error.message : code ?? 'unknown'})`);
+        }
+    }
+    if (issues.length > 0) {
+        throw new Error(`Generated WordPress AI artifacts are missing or stale:\n${issues.join('\n')}`);
+    }
+}
+/**
+ * Builds WordPress AI artifact documents from a manifest-first contract surface
+ * and then writes or verifies the generated JSON files on disk.
+ *
+ * @param options Artifact destinations plus the same manifest/category/schema inputs used by `buildWordPressAiArtifacts()`.
+ * @returns Generated documents and the output file paths that were checked or written.
+ */
+export async function syncWordPressAiArtifacts({ abilitiesDocumentFile, aiSchemaFile, check = false, ...buildOptions }) {
+    const { abilitiesDocument, aiResponseSchema } = await buildWordPressAiArtifacts(buildOptions);
+    await reconcileGeneratedAiArtifacts([
+        {
+            content: `${JSON.stringify(aiResponseSchema, null, 2)}\n`,
+            filePath: aiSchemaFile,
+        },
+        {
+            content: `${JSON.stringify(abilitiesDocument, null, 2)}\n`,
+            filePath: abilitiesDocumentFile,
+        },
+    ], check);
+    return {
+        abilitiesDocument,
+        abilitiesDocumentPath: abilitiesDocumentFile,
+        aiResponseSchema,
+        aiSchemaPath: aiSchemaFile,
+        check,
+    };
+}

package/dist/runtime/ai-feature-artifacts.d.ts

@@ -0,0 +1,85 @@
+import { type ArtifactSyncExecutionOptions } from "@wp-typia/block-runtime/metadata-core";
+import type { JsonSchemaDocument } from "./schema-core.js";
+interface AiFeatureTemplateVariablesLike {
+    namespace: string;
+    pascalCase: string;
+    slugKebabCase: string;
+    title: string;
+}
+interface SyncAiFeatureRestArtifactsOptions {
+    clientFile: string;
+    executionOptions?: ArtifactSyncExecutionOptions;
+    outputDir: string;
+    projectDir: string;
+    typesFile: string;
+    validatorsFile: string;
+    variables: AiFeatureTemplateVariablesLike;
+}
+/**
+ * Configures the AI-safe schema projection for one scaffolded AI feature.
+ */
+export interface SyncAiFeatureSchemaArtifactOptions extends ArtifactSyncExecutionOptions {
+    aiSchemaFile: string;
+    outputDir: string;
+    projectDir: string;
+}
+/**
+ * Carries the generated AI schema document and the file paths touched on disk.
+ */
+export interface SyncAiFeatureSchemaArtifactResult {
+    aiSchema: JsonSchemaDocument & Record<string, unknown>;
+    aiSchemaPath: string;
+    check: boolean;
+    sourceSchemaPath: string;
+}
+/**
+ * Build the endpoint manifest for a workspace-level AI feature scaffold.
+ *
+ * The endpoint response wraps a typed AI result payload together with provider,
+ * model, and token-usage telemetry. The nested `feature-result` contract is
+ * also kept in the manifest so `sync-rest` can emit the canonical JSON Schema
+ * that `sync-ai` later projects into the AI structured-output profile.
+ *
+ * @param variables Template naming data used for type names, routes, and docs.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export declare function buildAiFeatureEndpointManifest(variables: AiFeatureTemplateVariablesLike): import("@wp-typia/block-runtime/metadata-core").EndpointManifestDefinition<{
+    readonly "feature-request": {
+        readonly sourceTypeName: `${string}AiFeatureRequest`;
+    };
+    readonly "feature-response": {
+        readonly sourceTypeName: `${string}AiFeatureResponse`;
+    };
+    readonly "feature-result": {
+        readonly sourceTypeName: `${string}AiFeatureResult`;
+    };
+}, readonly [{
+    readonly auth: "authenticated";
+    readonly bodyContract: "feature-request";
+    readonly method: "POST";
+    readonly operationId: `run${string}AiFeature`;
+    readonly path: `/${string}/ai/${string}`;
+    readonly responseContract: "feature-response";
+    readonly summary: `Run the ${string} AI feature endpoint.`;
+    readonly tags: readonly [`${string} AI`];
+    readonly wordpressAuth: {
+        readonly mechanism: "rest-nonce";
+    };
+}]>;
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for
+ * a workspace-level AI feature scaffold.
+ *
+ * @param options Feature file paths and naming variables.
+ * @returns A promise that resolves after every generated REST artifact has been refreshed.
+ */
+export declare function syncAiFeatureRestArtifacts({ clientFile, executionOptions, outputDir, projectDir, typesFile, validatorsFile, variables, }: SyncAiFeatureRestArtifactsOptions): Promise<void>;
+/**
+ * Project the canonical AI result contract for one scaffolded feature into the
+ * AI structured-output schema profile consumed by `wp_ai_client_prompt()`.
+ *
+ * @param options Artifact destination plus the feature output directory.
+ * @returns The projected AI schema and the source schema path it derived from.
+ */
+export declare function syncAiFeatureSchemaArtifact({ aiSchemaFile, check, outputDir, projectDir, }: SyncAiFeatureSchemaArtifactOptions): Promise<SyncAiFeatureSchemaArtifactResult>;
+export {};

package/dist/runtime/ai-feature-artifacts.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { defineEndpointManifest, syncEndpointClient, syncRestOpenApi, syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+import { projectWordPressAiSchema } from "./ai-artifacts.js";
+function normalizeGeneratedArtifactContent(content) {
+    return content.replace(/\r\n?/g, "\n");
+}
+async function reconcileGeneratedArtifact(options) {
+    if (!options.check) {
+        await mkdir(path.dirname(options.filePath), {
+            recursive: true,
+        });
+        await writeFile(options.filePath, options.content, "utf8");
+        return;
+    }
+    try {
+        const current = normalizeGeneratedArtifactContent(await readFile(options.filePath, "utf8"));
+        const expected = normalizeGeneratedArtifactContent(options.content);
+        if (current !== expected) {
+            throw new Error(`Generated AI feature artifact is stale: ${options.label} (${options.filePath}).`);
+        }
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT") {
+            throw new Error(`Generated AI feature artifact is missing: ${options.label} (${options.filePath}).`);
+        }
+        throw error;
+    }
+}
+function assertJsonObject(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Expected ${label} to decode to a JSON object.`);
+    }
+    return value;
+}
+/**
+ * Build the endpoint manifest for a workspace-level AI feature scaffold.
+ *
+ * The endpoint response wraps a typed AI result payload together with provider,
+ * model, and token-usage telemetry. The nested `feature-result` contract is
+ * also kept in the manifest so `sync-rest` can emit the canonical JSON Schema
+ * that `sync-ai` later projects into the AI structured-output profile.
+ *
+ * @param variables Template naming data used for type names, routes, and docs.
+ * @returns Endpoint manifest consumed by schema, OpenAPI, and client generators.
+ */
+export function buildAiFeatureEndpointManifest(variables) {
+    return defineEndpointManifest({
+        contracts: {
+            "feature-request": {
+                sourceTypeName: `${variables.pascalCase}AiFeatureRequest`,
+            },
+            "feature-response": {
+                sourceTypeName: `${variables.pascalCase}AiFeatureResponse`,
+            },
+            "feature-result": {
+                sourceTypeName: `${variables.pascalCase}AiFeatureResult`,
+            },
+        },
+        endpoints: [
+            {
+                auth: "authenticated",
+                bodyContract: "feature-request",
+                method: "POST",
+                operationId: `run${variables.pascalCase}AiFeature`,
+                path: `/${variables.namespace}/ai/${variables.slugKebabCase}`,
+                responseContract: "feature-response",
+                summary: `Run the ${variables.title} AI feature endpoint.`,
+                tags: [`${variables.title} AI`],
+                wordpressAuth: {
+                    mechanism: "rest-nonce",
+                },
+            },
+        ],
+        info: {
+            title: `${variables.title} AI Feature API`,
+            version: "1.0.0",
+        },
+    });
+}
+/**
+ * Synchronize generated schemas, OpenAPI output, and endpoint client code for
+ * a workspace-level AI feature scaffold.
+ *
+ * @param options Feature file paths and naming variables.
+ * @returns A promise that resolves after every generated REST artifact has been refreshed.
+ */
+export async function syncAiFeatureRestArtifacts({ clientFile, executionOptions, outputDir, projectDir, typesFile, validatorsFile, variables, }) {
+    const manifest = buildAiFeatureEndpointManifest(variables);
+    for (const [baseName, contract] of Object.entries(manifest.contracts)) {
+        await syncTypeSchemas({
+            jsonSchemaFile: path.join(outputDir, "api-schemas", `${baseName}.schema.json`),
+            openApiFile: path.join(outputDir, "api-schemas", `${baseName}.openapi.json`),
+            projectRoot: projectDir,
+            sourceTypeName: contract.sourceTypeName,
+            typesFile,
+        }, executionOptions);
+    }
+    await syncRestOpenApi({
+        manifest,
+        openApiFile: path.join(outputDir, "api.openapi.json"),
+        projectRoot: projectDir,
+        typesFile,
+    }, executionOptions);
+    await syncEndpointClient({
+        clientFile,
+        manifest,
+        projectRoot: projectDir,
+        typesFile,
+        validatorsFile,
+    }, executionOptions);
+}
+/**
+ * Project the canonical AI result contract for one scaffolded feature into the
+ * AI structured-output schema profile consumed by `wp_ai_client_prompt()`.
+ *
+ * @param options Artifact destination plus the feature output directory.
+ * @returns The projected AI schema and the source schema path it derived from.
+ */
+export async function syncAiFeatureSchemaArtifact({ aiSchemaFile, check = false, outputDir, projectDir, }) {
+    const sourceSchemaPath = path.join(projectDir, outputDir, "api-schemas", "feature-result.schema.json");
+    const responseSchema = assertJsonObject(JSON.parse(await readFile(sourceSchemaPath, "utf8")), sourceSchemaPath);
+    const aiSchema = projectWordPressAiSchema(responseSchema);
+    await reconcileGeneratedArtifact({
+        check,
+        content: `${JSON.stringify(aiSchema, null, 2)}\n`,
+        filePath: path.join(projectDir, aiSchemaFile),
+        label: "AI feature schema",
+    });
+    return {
+        aiSchema,
+        aiSchemaPath: path.join(projectDir, aiSchemaFile),
+        check,
+        sourceSchemaPath,
+    };
+}

package/dist/runtime/ai-feature-capability.d.ts

@@ -0,0 +1,114 @@
+/** Declares whether a generated feature is optional or required at runtime. */
+export type AiFeatureCapabilityMode = 'optional' | 'required';
+/** Describes the minimum compatible platform versions for a feature. */
+export interface AiFeatureCompatibilityFloor {
+    /** Minimum supported PHP version, when a feature depends on PHP behavior. */
+    php?: string;
+    /** Minimum supported WordPress version, when a feature depends on core APIs. */
+    wordpress?: string;
+}
+/** Identifies a concrete runtime signal that a feature depends on. */
+export interface AiFeatureRuntimeGate {
+    /** The kind of runtime dependency or capability being checked. */
+    kind: 'adapter' | 'php-function' | 'script-package' | 'wordpress-core-feature';
+    /** The concrete symbol, package, or adapter name required at runtime. */
+    value: string;
+}
+/** Defines a single AI-related feature that scaffold compatibility can target. */
+export interface AiFeatureDefinition {
+    /** Human-readable summary for docs, onboarding, and generated notices. */
+    description: string;
+    /** Stable machine-readable identifier used in capability selections. */
+    id: string;
+    /** Display label presented to maintainers and downstream tooling. */
+    label: string;
+    /** Optional minimum platform versions required by the feature. */
+    minimumVersions?: AiFeatureCompatibilityFloor;
+    /** Optional runtime gates that explain what the feature depends on. */
+    runtimeGates?: readonly AiFeatureRuntimeGate[];
+}
+/** Selects a feature and whether it is required or merely optional. */
+export interface AiFeatureCapabilitySelection {
+    /** Feature identifier that must exist in the active registry. */
+    featureId: string;
+    /** Required selections take precedence over optional duplicates. */
+    mode: AiFeatureCapabilityMode;
+}
+/** Feature definition resolved together with its selected mode. */
+export interface ResolvedAiFeatureCapability extends AiFeatureDefinition {
+    /** Final selected mode after duplicate feature ids are normalized. */
+    mode: AiFeatureCapabilityMode;
+}
+/** Groups the normalized feature plan used by scaffold compatibility logic. */
+export interface ResolvedAiFeatureCapabilityPlan {
+    /** Highest required PHP and WordPress version floors across required features. */
+    hardMinimums: AiFeatureCompatibilityFloor;
+    /** Optional features that do not raise the minimum platform floor. */
+    optionalFeatures: ResolvedAiFeatureCapability[];
+    /** Required features that downstream projects must treat as mandatory. */
+    requiredFeatures: ResolvedAiFeatureCapability[];
+}
+/** Canonical registry of AI-related features supported by wp-typia today. */
+export declare const AI_FEATURE_DEFINITIONS: {
+    readonly wordpressAiClient: {
+        readonly description: "WordPress 7.0 AI Client surface used by AI-capable feature endpoints.";
+        readonly id: "wordpress-ai-client";
+        readonly label: "WordPress AI Client";
+        readonly minimumVersions: {
+            readonly wordpress: "7.0";
+        };
+        readonly runtimeGates: readonly [{
+            readonly kind: "wordpress-core-feature";
+            readonly value: "WordPress AI Client";
+        }];
+    };
+    readonly wordpressCoreAbilities: {
+        readonly description: "Client-side ability discovery surface for editor and admin flows.";
+        readonly id: "wordpress-core-abilities";
+        readonly label: "@wordpress/core-abilities";
+        readonly minimumVersions: {
+            readonly wordpress: "7.0";
+        };
+        readonly runtimeGates: readonly [{
+            readonly kind: "script-package";
+            readonly value: "@wordpress/core-abilities";
+        }];
+    };
+    readonly wordpressMcpPublicMetadata: {
+        readonly description: "Optional MCP exposure metadata consumed by a separate adapter path rather than core alone.";
+        readonly id: "wordpress-mcp-public-metadata";
+        readonly label: "MCP public metadata";
+        readonly runtimeGates: readonly [{
+            readonly kind: "adapter";
+            readonly value: "MCP adapter";
+        }];
+    };
+    readonly wordpressServerAbilities: {
+        readonly description: "Server-side ability registration and execution surface for WordPress-native abilities.";
+        readonly id: "wordpress-server-abilities";
+        readonly label: "WordPress Abilities API";
+        readonly minimumVersions: {
+            readonly wordpress: "6.9";
+        };
+        readonly runtimeGates: readonly [{
+            readonly kind: "php-function";
+            readonly value: "wp_register_ability";
+        }, {
+            readonly kind: "php-function";
+            readonly value: "wp_register_ability_category";
+        }];
+    };
+};
+/**
+ * Resolves a normalized AI feature capability plan from a list of selections.
+ *
+ * Required selections win when the same feature id appears multiple times, and
+ * the resulting hard minimum platform floor is computed from required features
+ * only.
+ *
+ * @param selections Desired feature selections for a scaffold or projection.
+ * @param registry Feature registry to resolve against. Defaults to the built-in registry.
+ * @returns The normalized capability plan plus required version floors.
+ * @throws When a selection references an unknown feature id.
+ */
+export declare function resolveAiFeatureCapabilityPlan(selections: readonly AiFeatureCapabilitySelection[], registry?: Readonly<Record<string, AiFeatureDefinition>>): ResolvedAiFeatureCapabilityPlan;