@topik/core 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/index.d.mts

@@ -1,6 +1,13 @@
 import { z } from "zod";
-import { Asset, Guide, Wiki, WikiPage } from "@topik/schema";
-
+import { TopikContentDiagnostic, TopikGeneratedAssetName } from "@topik/content-schema";
+import { CoursePage } from "@topik/schema/course-page/v1";
+import { Guide } from "@topik/schema/guide/v1";
+import { WikiPage } from "@topik/schema/wiki-page/v1";
+import { Asset } from "@topik/schema/asset/v1";
+import { Course } from "@topik/schema/course/v1";
+import { CourseModule } from "@topik/schema/course-module/v1";
+import { Person } from "@topik/schema/person/v1";
+import { Wiki, WikiDropdownNavNode, WikiExternalDropdownNavNode, WikiExternalTabNavNode, WikiInternalDropdownNavNode, WikiInternalTabNavNode, WikiNavContainerNode, WikiNavNode, WikiNavigation, WikiPageNavNode, WikiTabNavNode } from "@topik/schema/wiki/v1";
 //#region src/config/collection.d.ts
 declare const collectionConfigSchema: z.ZodObject<{
   id: z.ZodString;
@@ -11,25 +18,49 @@ type CollectionConfig = z.infer<typeof collectionConfigSchema>;
 declare function parseCollectionConfig(raw: unknown): CollectionConfig;
 //#endregion
 //#region src/config/wiki.d.ts
-type WikiNavNode = string | {
-  group: string;
+type WikiPageNavNode$1 = {
+  type: "page";
+  slug: string;
+  icon?: string;
+  hidden?: boolean;
+};
+type WikiGroupNavNode = {
+  type: "group";
+  title: string;
   slug?: string;
   icon?: string;
-  children: WikiNavNode[];
-} | {
-  tab: string;
+  expanded?: boolean;
+  hidden?: boolean;
+  children: WikiNavNode$1[];
+};
+type WikiInternalSwitcherNavNode = {
+  type: "tab" | "dropdown";
+  title: string;
   slug?: string;
   icon?: string;
-  children: WikiNavNode[];
-} | {
+  hidden?: boolean;
+  children: WikiNavNode$1[];
+};
+type WikiExternalSwitcherNavNode = {
+  type: "tab" | "dropdown";
+  title: string;
   href: string;
+  icon?: string;
+  hidden?: boolean;
+};
+type WikiLinkNavNode = {
+  type: "link";
   title: string;
+  href: string;
   icon?: string;
+  hidden?: boolean;
 };
+type WikiNavNode$1 = string | WikiPageNavNode$1 | WikiGroupNavNode | WikiInternalSwitcherNavNode | WikiExternalSwitcherNavNode | WikiLinkNavNode;
 declare const wikiConfigSchema: z.ZodObject<{
   id: z.ZodString;
   title: z.ZodString;
-  navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode, unknown, z.core.$ZodTypeInternals<WikiNavNode, unknown>>>>;
+  description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
+  navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode$1, unknown, z.core.$ZodTypeInternals<WikiNavNode$1, unknown>>>>;
   theme: z.ZodOptional<z.ZodObject<{
     colors: z.ZodOptional<z.ZodObject<{
       primary: z.ZodString;
@@ -49,34 +80,294 @@ type WikiConfig = z.infer<typeof wikiConfigSchema>;
 declare function parseWikiConfig(raw: unknown): WikiConfig;
 //#endregion
 //#region src/resource.d.ts
-type Resource = Asset | Guide | Wiki | WikiPage;
+type Resource = Asset | Course | CourseModule | CoursePage | Guide | Person | Wiki | WikiPage;
+/** Resources accepted as compiler input. `Asset` exists only in compiler output. */
+type SourceResource = Exclude<Resource, Asset>;
 type ResourceType = Resource["type"];
 //#endregion
+//#region src/assets/constants.d.ts
+declare const ASSET_API_VERSION: "v1";
+declare const ASSET_TYPE: "Asset";
+declare const ASSET_SCHEMA_ID: "https://topik.dev/schemas/asset/v1.json";
+declare const TOPIK_JSON_VERSION: "topik-json-v1";
+declare const TOPIK_PATH_VERSION: "topik-path-v1";
+declare const TOPIK_ASSET_REFERENCE_VERSION: "topik-asset-reference-v1";
+declare const TOPIK_MATERIALIZATION_VERSION: "topik-materialization-v1";
+declare const TOPIK_ASSET_NAME_VERSION: "topik-asset-name-v1";
+declare const TOPIK_BLOB_OUTPUT_PREFIX: "blobs";
+declare const TOPIK_PATH_V1_DESCRIPTOR: {
+  readonly collisionNormalization: "toNFKC_Casefold";
+  readonly id: "topik-path-v1";
+  readonly localReferenceEncoding: "rfc3986-utf8-upper-v1";
+  readonly maxComponentUtf8Bytes: 255;
+  readonly maxComponents: 64;
+  readonly maxRepositoryPathUtf8Bytes: 768;
+  readonly normalizationSensitiveExclusion: "unicode-17-new-marks";
+  readonly storageNormalization: "NFC";
+  readonly unicodeVersion: "17.0.0";
+};
+declare const TOPIK_ASSET_LIMITS: {
+  readonly maxDescriptorBytes: 1048576;
+  readonly maxAssetBytes: 268435456;
+  readonly maxAssets: 10000;
+  readonly maxJsonDepth: 8;
+  readonly maxComponentUtf8Bytes: 255;
+  readonly maxComponents: 64;
+  readonly maxRepositoryPathUtf8Bytes: 768;
+};
+//#endregion
+//#region src/assets/diagnostics.d.ts
+declare const TOPIK_ASSET_DIAGNOSTIC_IDS: readonly ["TOPIK_ASSET_UNSUPPORTED_VERSION", "TOPIK_ASSET_DUPLICATE_MEMBER", "TOPIK_ASSET_SCHEMA_INVALID", "TOPIK_ASSET_NON_CANONICAL", "TOPIK_ASSET_NAME_INVALID", "TOPIK_ASSET_NAME_COLLISION", "TOPIK_ASSET_SOURCE_NAMESPACE_REQUIRED", "TOPIK_ASSET_SOURCE_NAMESPACE_INVALID", "TOPIK_ASSET_PATH_INVALID", "TOPIK_ASSET_PATH_COLLISION", "TOPIK_ASSET_REFERENCE_AMBIGUOUS", "TOPIK_ASSET_REFERENCE_MALFORMED", "TOPIK_ASSET_REFERENCE_MISSING", "TOPIK_ASSET_FILE_MISSING", "TOPIK_ASSET_DIGEST_MISMATCH", "TOPIK_ASSET_SIZE_MISMATCH", "TOPIK_ASSET_MEDIA_TYPE_MISMATCH", "TOPIK_ASSET_FILE_TYPE_UNSUPPORTED", "TOPIK_ASSET_ACTIVE_CONTENT_UNSUPPORTED", "TOPIK_ASSET_REFERENCE_ACCESSIBILITY_INVALID", "TOPIK_EXTERNAL_REFERENCE_UNSAFE", "TOPIK_ASSET_INVENTORY_INCOMPLETE", "TOPIK_ASSET_VERSION_INCOMPARABLE"];
+declare const TOPIK_ASSET_DEFAULT_CORRELATION_ID: "cor_00000000000000000000000000";
+declare const TOPIK_ASSET_CORRELATION_ID_PATTERN: RegExp;
+type TopikAssetCorrelationId = `cor_${string}`;
+type TopikAssetDiagnosticId = (typeof TOPIK_ASSET_DIAGNOSTIC_IDS)[number];
+type TopikAssetPathDiagnosticReason = "invalid_utf8" | "capability_invalid" | "unicode_version_unsupported" | "not_nfc" | "absolute" | "separator_alias" | "dot_segment" | "percent_noncanonical" | "forbidden_character" | "reserved_name" | "too_long" | "casefold_collision";
+type TopikAssetRecoveryCategory = "upgrade-reader" | "repair-source" | "restore-file" | "verify-bytes" | "preserve-read-only";
+interface TopikAssetDiagnosticLocation {
+  jsonPointer?: string;
+  contentPosition?: string;
+  path?: string;
+  key?: string;
+  commit?: string;
+}
+interface TopikAssetDiagnostic {
+  id: TopikAssetDiagnosticId;
+  /** Safe opaque operation correlation; callers may replace the deterministic default. */
+  correlationId: TopikAssetCorrelationId;
+  severity: "error";
+  consequence: "block-resource" | "block-identity-and-writes" | "block-mutation";
+  descriptorVersion: string;
+  location: TopikAssetDiagnosticLocation;
+  recovery: TopikAssetRecoveryCategory;
+  reason?: TopikAssetPathDiagnosticReason;
+  /** Human wording is intentionally not a stable compatibility surface. */
+  message: string;
+}
+type TopikAssetResult<T> = {
+  ok: true;
+  value: T;
+  diagnostics: readonly [];
+  source?: Uint8Array;
+} | {
+  ok: false;
+  value?: T;
+  diagnostics: readonly TopikAssetDiagnostic[];
+  /** Exact caller bytes are non-loggable evidence; never copy them into diagnostics/telemetry. */
+  source?: Uint8Array;
+};
+declare function correlateTopikAssetResult<T>(result: TopikAssetResult<T>, correlationId: TopikAssetCorrelationId): TopikAssetResult<T>;
+//#endregion
+//#region src/assets/asset.d.ts
+interface ParsedAsset {
+  asset: Asset;
+  canonicalBytes: Uint8Array;
+}
+/** Compiler-generated name used by automatic Asset compilation. */
+type GeneratedAssetName = TopikGeneratedAssetName;
+declare const assetBlobUriBrand: unique symbol;
+/** Opaque compiler output path for one SHA-256-addressed Asset blob. */
+type AssetBlobUri = string & {
+  readonly [assetBlobUriBrand]: "AssetBlobUri";
+};
+declare function isAssetBlobUri(value: unknown): value is AssetBlobUri;
+declare function parseAssetBlobUri(value: string): AssetBlobUri;
+declare function parseGeneratedAssetName(value: string): GeneratedAssetName;
+/** Asset descriptor emitted by the compiler with a materialized payload. */
+interface CompiledAsset extends Asset {
+  name: GeneratedAssetName;
+  spec: {
+    uri: AssetBlobUri;
+    integrity: `sha256:${string}`;
+    size: number;
+    mediaType: string;
+  };
+}
+declare function parseAsset(input: string | Uint8Array): TopikAssetResult<ParsedAsset>;
+declare function validateAssetValue(value: unknown): TopikAssetResult<Asset>;
+/** Serialize one Asset to deterministic UTF-8 canonical JSON and prove its round trip. */
+declare function serializeAsset(value: unknown): TopikAssetResult<Uint8Array>;
+/** Admit a compiler-materialized blob path; Asset resources may use other URI forms. */
+declare function validateAssetBlobUri(value: string): TopikAssetResult<{
+  uri: AssetBlobUri;
+}>;
+declare function isGeneratedAssetName(value: unknown): value is GeneratedAssetName;
+declare function validateStableSourceNamespace(value: string): TopikAssetResult<string>;
+interface GenerateAutomaticAssetNameOptions {
+  stableSourceNamespace: string;
+  normalizedPath: string;
+}
+declare function generateAutomaticAssetName(options: GenerateAutomaticAssetNameOptions): TopikAssetResult<GeneratedAssetName>;
+declare function topikAssetNameDescriptor(): {
+  id: typeof TOPIK_ASSET_NAME_VERSION;
+};
+//#endregion
+//#region src/assets/identity.d.ts
+interface TopikAssetReferenceMappingV1 {
+  resource: string;
+  position: string;
+  slot: string;
+  name: string;
+}
+interface TopikAssetSemanticRecordV1 {
+  descriptor: "topik-asset-semantic-v1";
+  assetNames: readonly string[];
+  references: readonly TopikAssetReferenceMappingV1[];
+}
+interface TopikMaterializationResourceV1 {
+  resource: string;
+  path: string;
+  size: number;
+  sha256: string;
+}
+interface TopikMaterializationPayloadV1 {
+  path: string;
+  size: number;
+  sha256: string;
+  assetNames: readonly string[];
+}
+interface TopikMaterializationRecordV1 {
+  descriptor: "topik-materialization-v1";
+  resources: readonly TopikMaterializationResourceV1[];
+  payloads: readonly TopikMaterializationPayloadV1[];
+}
+interface TopikMaterializationResourceInput {
+  resource: {
+    type: string;
+    name: string;
+  };
+  bytes: Uint8Array;
+}
+interface TopikMaterializationPayloadInput {
+  path: string;
+  bytes: Uint8Array;
+  assetNames: readonly string[];
+}
+declare function createTopikAssetSemanticRecord(assets: readonly Asset[], references: readonly TopikAssetReferenceMappingV1[]): TopikAssetSemanticRecordV1;
+declare function createTopikMaterializationRecord(resources: readonly TopikMaterializationResourceInput[], payloads: readonly TopikMaterializationPayloadInput[]): TopikMaterializationRecordV1;
+declare function validateTopikMaterializationRecord(record: unknown, resources: readonly Resource[], semantic: unknown): TopikAssetResult<TopikMaterializationRecordV1>;
+declare function digestTopikAssetSemanticRecord(record: TopikAssetSemanticRecordV1): string;
+declare function digestTopikMaterializationRecord(record: TopikMaterializationRecordV1): string;
+declare function compareTopikAssetIdentities(left: {
+  semantic: TopikAssetSemanticRecordV1;
+  materialization: TopikMaterializationRecordV1;
+}, right: {
+  semantic: TopikAssetSemanticRecordV1;
+  materialization: TopikMaterializationRecordV1;
+}): TopikAssetResult<{
+  semanticEqual: boolean;
+  exactEqual: boolean;
+}>;
+//#endregion
+//#region src/compile/assets.d.ts
+type ContentBearingResource = CoursePage | Guide | WikiPage;
+interface AssetCompilationOptions {
+  /** Required only when supported local references are discovered automatically. */
+  sourceNamespace?: string;
+}
+interface CompileAssetResourcesInput extends AssetCompilationOptions {
+  rootDir: string;
+  resources: readonly SourceResource[];
+  /** Compilation-root-relative source paths keyed by `Type/name`. */
+  sourcePathsByResource: Readonly<Record<string, string>>;
+  /** Other consumed compiler inputs that cannot be owned as Asset bytes. */
+  protectedSourcePaths?: readonly string[];
+}
+interface AssetPayload {
+  path: AssetBlobUri;
+  integrity: `sha256:${string}`;
+  mediaType: string;
+  size: number;
+  bytes: Uint8Array;
+  assetNames: readonly string[];
+}
+interface AssetCompilationResult {
+  resources: CompiledResource[];
+  payloads: AssetPayload[];
+  semantic: TopikAssetSemanticRecordV1;
+  materialization: TopikMaterializationRecordV1;
+}
+type CompiledResource = SourceResource | CompiledAsset;
+declare class AssetCompilationError extends Error {
+  readonly diagnostics: readonly TopikAssetDiagnostic[];
+  constructor(message: string, diagnostics?: readonly TopikAssetDiagnostic[]);
+}
+/** Discover and resolve one compilation-wide Asset set and deduplicated payload inventory. */
+declare function compileAssetResources(input: CompileAssetResourcesInput): Promise<AssetCompilationResult>;
+//#endregion
 //#region src/compile/shared.d.ts
 interface CompileResult {
-  resources: Resource[];
+  diagnostics: TopikContentDiagnostic[];
+  resources: CompiledResource[];
+  payloads: AssetPayload[];
+  semantic: TopikAssetSemanticRecordV1;
+  materialization: TopikMaterializationRecordV1;
+}
+type LinkValidationPolicy = "error" | "warning" | "off";
+interface CompileValidationOptions {
+  /** How unresolved wiki page links and same-page guide fragments are handled. */
+  links?: LinkValidationPolicy;
 }
+declare class CompileError extends Error {
+  readonly diagnostics: TopikContentDiagnostic[];
+  constructor(diagnostics: TopikContentDiagnostic[]);
+}
+declare function isErrorDiagnostic(diagnostic: TopikContentDiagnostic): boolean;
+//#endregion
+//#region src/compile/guide.d.ts
+interface CompileGuidesOptions {
+  dir: string;
+  validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
+}
+declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
 //#endregion
 //#region src/compile/wiki.d.ts
 interface CompileWikiOptions {
   dir: string;
+  validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
 }
 declare function compileWiki(options: CompileWikiOptions): Promise<CompileResult>;
+declare function pagePathToName(wikiId: string, pagePath: string): string;
 //#endregion
-//#region src/compile/guide.d.ts
-interface CompileGuidesOptions {
-  dir: string;
+//#region src/compile/public-errors.d.ts
+declare const PUBLIC_COMPILE_ERROR_MESSAGES: {
+  readonly "config-access-failed": "Configuration file could not be accessed.";
+  readonly "config-invalid": "Configuration is invalid.";
+  readonly "config-not-found": "Required configuration file was not found.";
+  readonly "config-parse-failed": "Configuration file could not be parsed.";
+  readonly "config-read-failed": "Configuration file could not be read safely.";
+  readonly "file-not-regular": "Compilation input must be a regular file.";
+  readonly "file-outside-compilation-root": "Compilation input resolves outside the source root.";
+  readonly "frontmatter-invalid": "Document frontmatter is invalid.";
+  readonly "reference-list-invalid": "Document resource references are invalid.";
+  readonly "wiki-page-not-found": "A configured Wiki page file was not found.";
+};
+type PublicCompileErrorId = keyof typeof PUBLIC_COMPILE_ERROR_MESSAGES;
+declare function publicCompileErrorMessage(id: unknown): string | undefined;
+/** Public compiler failure with fixed wording, stable ID, and optional safe relative location. */
+declare class PublicCompileError extends Error {
+  readonly id: PublicCompileErrorId;
+  readonly location?: string;
+  constructor(id: PublicCompileErrorId, location?: string);
 }
-declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
 //#endregion
 //#region src/compile/index.d.ts
 interface CompileOptions {
   dir: string;
+  validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
 }
 declare function compile(options: CompileOptions): Promise<CompileResult>;
+interface LintResult {
+  diagnostics: CompileResult["diagnostics"];
+}
+declare function lint(options: CompileOptions): Promise<LintResult>;
 //#endregion
 //#region src/validate.d.ts
 interface ValidationError {
+  id?: "resource-invalid" | "resource-unsupported-type" | "resource-unsupported-version" | TopikAssetDiagnosticId;
   resource: string;
   path: string;
   message: string;
@@ -88,16 +379,63 @@ interface ValidationResult {
 /** Validate the resources produced by `compile` and the CLI export. */
 declare function validateResources(resources: readonly unknown[]): ValidationResult;
 //#endregion
+//#region src/wiki-navigation.d.ts
+type ResolvedWikiPage = {
+  /** The compiled WikiPage resource name. */
+  page: string;
+  /** The page navigation node from the Wiki resource. */
+  node: WikiPageNavNode;
+  /** Public path without a leading slash. */
+  route: string;
+  /** Logical Markdown source path without an extension. */
+  sourcePath: string;
+  /** Internal navigation containers from outermost to innermost. */
+  ancestors: readonly WikiNavContainerNode[];
+};
+type ResolvedWikiNavigation = {
+  pages: readonly ResolvedWikiPage[];
+  pageByName: ReadonlyMap<string, ResolvedWikiPage>;
+  pageByRoute: ReadonlyMap<string, ResolvedWikiPage>;
+};
+type ResolvedWikiContentLink = {
+  page: ResolvedWikiPage;
+  route: string;
+  hash: string;
+};
+/** Returns true for tab, dropdown, and group nodes containing navigation children. */
+declare function hasWikiNavChildren(node: WikiNavNode): node is WikiNavContainerNode;
+declare function isInternalWikiTab(node: WikiNavNode): node is WikiInternalTabNavNode;
+declare function isExternalWikiTab(node: WikiNavNode): node is WikiExternalTabNavNode;
+declare function isInternalWikiDropdown(node: WikiNavNode): node is WikiInternalDropdownNavNode;
+declare function isExternalWikiDropdown(node: WikiNavNode): node is WikiExternalDropdownNavNode;
+/** Resolves page routes, source paths, and navigation ancestry from a compiled Wiki tree. */
+declare function resolveWikiNavigation(navigation: WikiNavigation | readonly WikiNavNode[]): ResolvedWikiNavigation;
+/** Finds the first page node in navigation order, ignoring external destinations. */
+declare function findFirstWikiPage(navigation: WikiNavigation | readonly WikiNavNode[]): WikiPageNavNode | null;
+/** Returns the internal containers owning a page, or an empty array for an unknown page. */
+declare function findWikiPageAncestors(resolved: ResolvedWikiNavigation, pageName: string): readonly WikiNavContainerNode[];
+/** Resolves an internal Markdown link against the logical source path of its current page. */
+declare function resolveWikiContentHref(href: string, currentPageName: string, resolved: ResolvedWikiNavigation): ResolvedWikiContentLink | null;
+declare function joinWikiPath(prefix: string, slug?: string): string;
+type InternalWikiTab = WikiInternalTabNavNode;
+type ExternalWikiTab = WikiExternalTabNavNode;
+type InternalWikiDropdown = WikiInternalDropdownNavNode;
+type ExternalWikiDropdown = WikiExternalDropdownNavNode;
+type WikiSwitcherNode = WikiTabNavNode | WikiDropdownNavNode;
+//#endregion
 //#region src/watch.d.ts
 interface WatchOptions {
   dir: string;
   signal?: AbortSignal;
+  assets?: AssetCompilationOptions;
 }
 type UpdateListener = (key: string, resource: Resource) => void;
 type ErrorListener = (error: Error) => void;
 interface Watcher {
   /** Current compiled resources, keyed by `Type/name`. */
   resources: Map<string, Resource>;
+  /** Current deduplicated local payloads, keyed by compilation-relative output path. */
+  payloads: Map<string, AssetPayload>;
   on(event: "update", listener: UpdateListener): this;
   on(event: "error", listener: ErrorListener): this;
   off(event: "update", listener: UpdateListener): this;
@@ -106,4 +444,68 @@ interface Watcher {
 }
 declare function watch(options: WatchOptions): Promise<Watcher>;
 //#endregion
-export { type CollectionConfig, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileWikiOptions, type Resource, type ResourceType, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, compile, compileGuides, compileWiki, parseCollectionConfig, parseWikiConfig, validateResources, watch };
+//#region src/assets/path.d.ts
+interface ValidateTopikPathOptions {
+  bindingRoot?: string;
+  capabilities?: {
+    maxComponentUtf8Bytes?: number;
+    maxComponents?: number;
+    maxRepositoryPathUtf8Bytes?: number;
+  };
+}
+interface ValidTopikPath {
+  path: string;
+  collisionKey: string;
+  utf8Bytes: number;
+}
+declare function validateTopikPath(input: string | Uint8Array, options?: ValidateTopikPathOptions): TopikAssetResult<ValidTopikPath>;
+declare function computeTopikPathCollisionKey(path: string, options?: ValidateTopikPathOptions): TopikAssetResult<string>;
+declare function validateTopikPathSet(paths: readonly string[], options?: ValidateTopikPathOptions): TopikAssetResult<Map<string, string>>;
+/** Unicode 17 NFKC casefold for topik-path-v1-admitted input. */
+declare function toNfkcCasefold(value: string): string;
+//#endregion
+//#region src/assets/json.d.ts
+declare class TopikJsonSyntaxError extends SyntaxError {
+  readonly offset: number;
+  readonly duplicatePointer?: string | undefined;
+  constructor(message: string, offset: number, duplicatePointer?: string | undefined);
+}
+declare function parseStrictTopikJson(source: string, maxDepth?: number): unknown;
+/** RFC 8785 scalar/member rules with Topik's two-space layout and final LF. */
+declare function serializeTopikJson(value: unknown): string;
+declare function topikJsonDescriptor(): {
+  id: typeof TOPIK_JSON_VERSION;
+};
+//#endregion
+//#region src/assets/files.d.ts
+type PortableAssetFileType = "regular" | "symlink" | "hardlink" | "gitlink" | "device" | "fifo" | "socket" | "special" | "sparse" | "archive-link";
+interface PortableAssetFileDescriptor {
+  path: string;
+  type: PortableAssetFileType;
+  source?: "git" | "archive" | "filesystem";
+  /** Git mode (`100644`) or archive mode (`0644`). */
+  mode: string;
+  bytes?: Uint8Array;
+  linkCount?: number;
+  hasAlternateDataStream?: boolean;
+  contentFilter?: string;
+  workingTreeEncoding?: string;
+}
+declare function validatePortableAssetFile(file: PortableAssetFileDescriptor): TopikAssetResult<PortableAssetFileDescriptor>;
+declare function validatePortableAssetTree(files: readonly PortableAssetFileDescriptor[]): TopikAssetResult<readonly PortableAssetFileDescriptor[]>;
+interface ReadPortableAssetFileOptions {
+  root: string;
+  path: string;
+}
+/** Filesystem reader using no-follow traversal and stable same-handle identity checks. */
+declare function readPortableAssetFile(options: ReadPortableAssetFileOptions): Promise<TopikAssetResult<PortableAssetFileDescriptor>>;
+declare function looksLikeGitLfsPointer(bytes: Uint8Array): boolean;
+//#endregion
+//#region src/assets/media.d.ts
+declare const TOPIK_UNRESOLVED_ACTIVE_CONTENT_TYPE: "application/x-topik-active-content";
+/** Sniff exact bytes conservatively. Unknown safe bytes remain opaque downloads. */
+declare function sniffPortableMediaType(bytes: Uint8Array): string;
+declare function isTopikActiveMediaType(mediaType: string): boolean;
+declare function isInlineMediaCompatible(mediaType: string, role: string): boolean;
+//#endregion
+export { ASSET_API_VERSION, ASSET_SCHEMA_ID, ASSET_TYPE, type AssetBlobUri, AssetCompilationError, type AssetCompilationOptions, type AssetCompilationResult, type AssetPayload, type CollectionConfig, type CompileAssetResourcesInput, CompileError, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileValidationOptions, type CompileWikiOptions, type CompiledAsset, type CompiledResource, type ContentBearingResource, type ExternalWikiDropdown, type ExternalWikiTab, type GenerateAutomaticAssetNameOptions, type GeneratedAssetName, type InternalWikiDropdown, type InternalWikiTab, type LinkValidationPolicy, type LintResult, type ParsedAsset, type PortableAssetFileDescriptor, type PortableAssetFileType, PublicCompileError, type PublicCompileErrorId, type ReadPortableAssetFileOptions, type ResolvedWikiContentLink, type ResolvedWikiNavigation, type ResolvedWikiPage, type Resource, type ResourceType, type SourceResource, TOPIK_ASSET_CORRELATION_ID_PATTERN, TOPIK_ASSET_DEFAULT_CORRELATION_ID, TOPIK_ASSET_DIAGNOSTIC_IDS, TOPIK_ASSET_LIMITS, TOPIK_ASSET_NAME_VERSION, TOPIK_ASSET_REFERENCE_VERSION, TOPIK_BLOB_OUTPUT_PREFIX, TOPIK_JSON_VERSION, TOPIK_MATERIALIZATION_VERSION, TOPIK_PATH_V1_DESCRIPTOR, TOPIK_PATH_VERSION, TOPIK_UNRESOLVED_ACTIVE_CONTENT_TYPE, type TopikAssetCorrelationId, type TopikAssetDiagnostic, type TopikAssetDiagnosticId, type TopikAssetDiagnosticLocation, type TopikAssetPathDiagnosticReason, type TopikAssetRecoveryCategory, type TopikAssetReferenceMappingV1, type TopikAssetResult, type TopikAssetSemanticRecordV1, TopikJsonSyntaxError, type TopikMaterializationPayloadInput, type TopikMaterializationPayloadV1, type TopikMaterializationRecordV1, type TopikMaterializationResourceInput, type TopikMaterializationResourceV1, type ValidTopikPath, type ValidateTopikPathOptions, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, type WikiSwitcherNode, compareTopikAssetIdentities, compile, compileAssetResources, compileGuides, compileWiki, computeTopikPathCollisionKey, correlateTopikAssetResult, createTopikAssetSemanticRecord, createTopikMaterializationRecord, digestTopikAssetSemanticRecord, digestTopikMaterializationRecord, findFirstWikiPage, findWikiPageAncestors, generateAutomaticAssetName, hasWikiNavChildren, isAssetBlobUri, isErrorDiagnostic, isExternalWikiDropdown, isExternalWikiTab, isGeneratedAssetName, isInlineMediaCompatible, isInternalWikiDropdown, isInternalWikiTab, isTopikActiveMediaType, joinWikiPath, lint, looksLikeGitLfsPointer, pagePathToName, parseAsset, parseAssetBlobUri, parseCollectionConfig, parseGeneratedAssetName, parseStrictTopikJson, parseWikiConfig, publicCompileErrorMessage, readPortableAssetFile, resolveWikiContentHref, resolveWikiNavigation, serializeAsset, serializeTopikJson, sniffPortableMediaType, toNfkcCasefold, topikAssetNameDescriptor, topikJsonDescriptor, validateAssetBlobUri, validateAssetValue, validatePortableAssetFile, validatePortableAssetTree, validateResources, validateStableSourceNamespace, validateTopikMaterializationRecord, validateTopikPath, validateTopikPathSet, watch };