@topik/core 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/index.d.mts

@@ -1,20 +1,39 @@
+import { CourseReferenceContext, ResolvedCourseContentLink, ResolvedCourseContentReference, ResolvedCourseNavigation, ResolvedCoursePage, resolveCourseContentHref, resolveCourseContentReference, resolveCourseNavigation } from "./course-navigation.mjs";
+import { $ as TopikAssetPathDiagnosticReason, A as AssetBlobUri, B as parseGeneratedAssetName, C as TopikMaterializationResourceV1, D as digestTopikAssetSemanticRecord, E as createTopikMaterializationRecord, F as generateAutomaticAssetName, G as validateProjectNamespace, H as topikAssetNameDescriptor, I as isAssetBlobUri, J as TOPIK_ASSET_DIAGNOSTIC_IDS, K as TOPIK_ASSET_CORRELATION_ID_PATTERN, L as isGeneratedAssetName, M as GenerateAutomaticAssetNameOptions, N as GeneratedAssetName, O as digestTopikMaterializationRecord, P as ParsedAsset, Q as TopikAssetDiagnosticLocation, R as parseAsset, S as TopikMaterializationResourceInput, T as createTopikAssetSemanticRecord, U as validateAssetBlobUri, V as serializeAsset, W as validateAssetValue, X as TopikAssetDiagnostic, Y as TopikAssetCorrelationId, Z as TopikAssetDiagnosticId, _ as TopikAssetReferenceMappingV1, a as PreviewState, at as ASSET_TYPE, b as TopikMaterializationPayloadV1, c as AssetCompilationOptions, ct as TOPIK_ASSET_REFERENCE_VERSION, d as AssetNameInput, dt as TOPIK_MATERIALIZATION_VERSION, et as TopikAssetRecoveryCategory, f as AssetPayload, ft as TOPIK_PATH_V1_DESCRIPTOR, g as compileAssetResources, gt as SourceResource, h as ContentBearingResource, ht as ResourceType, i as PreviewPayloadDescriptor, it as ASSET_SCHEMA_ID, j as CompiledAsset, k as validateTopikMaterializationRecord, l as AssetCompilationResult, lt as TOPIK_BLOB_OUTPUT_PREFIX, m as CompiledResource, mt as Resource, n as CourseNavigationModule, nt as correlateTopikAssetResult, o as TOPIK_PREVIEW_PROTOCOL, ot as TOPIK_ASSET_LIMITS, p as CompileAssetResourcesInput, pt as TOPIK_PATH_VERSION, q as TOPIK_ASSET_DEFAULT_CORRELATION_ID, r as PreviewDiagnostic, rt as ASSET_API_VERSION, s as AssetCompilationError, st as TOPIK_ASSET_NAME_VERSION, t as CourseNavigationIndex, tt as TopikAssetResult, u as AssetNameGenerator, ut as TOPIK_JSON_VERSION, v as TopikAssetSemanticRecordV1, w as compareTopikAssetIdentities, x as TopikMaterializationRecordV1, y as TopikMaterializationPayloadInput, z as parseAssetBlobUri } from "./preview-C_3OnNUi.mjs";
+import { ExternalWikiDropdown, ExternalWikiTab, InternalWikiDropdown, InternalWikiTab, ResolvedWikiContentLink, ResolvedWikiContentReference, ResolvedWikiNavigation, ResolvedWikiPage, WikiSwitcherNode, findFirstWikiPage, findWikiPageAncestors, hasWikiNavChildren, isExternalWikiDropdown, isExternalWikiTab, isInternalWikiDropdown, isInternalWikiTab, joinWikiPath, resolveWikiContentHref, resolveWikiContentReference, resolveWikiNavigation } from "./wiki-navigation.mjs";
 import { z } from "zod";
-import { Asset, Guide, Wiki, WikiPage } from "@topik/schema";
-import { TopikContentDiagnostic } from "@topik/content-schema";
-
+import { TopikContentDiagnostic, TopikNavigationReference, TopikResourceReference } from "@topik/content";
+import "yaml";
+import { Person } from "@topik/schema/person/v1";
+import { CoursePage } from "@topik/schema/course-page/v1";
+import { Guide } from "@topik/schema/guide/v1";
+import { Wiki, WikiNavNode } from "@topik/schema/wiki/v1";
+import { WikiPage } from "@topik/schema/wiki-page/v1";
+//#region src/config/source-version.d.ts
+/** The public resource validator owns Person fields, including future schema additions. */
+declare function parseSourcePersons(value: unknown): Person[];
+//#endregion
 //#region src/config/collection.d.ts
 declare const collectionConfigSchema: z.ZodObject<{
   id: z.ZodString;
   title: z.ZodString;
+  sourceVersion: z.ZodOptional<z.ZodLiteral<1>>;
+  persons: z.ZodOptional<z.ZodUnknown>;
+  assets: z.ZodDefault<z.ZodObject<{
+    directory: z.ZodDefault<z.ZodString>;
+  }, z.core.$strict>>;
   tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
-type CollectionConfig = z.infer<typeof collectionConfigSchema>;
-declare function parseCollectionConfig(raw: unknown): CollectionConfig;
+type CollectionConfig = Omit<z.infer<typeof collectionConfigSchema>, "persons"> & {
+  persons?: ReturnType<typeof parseSourcePersons>;
+};
+export declare function parseCollectionConfig(raw: unknown): CollectionConfig;
 //#endregion
 //#region src/config/wiki.d.ts
-type WikiPageNavNode = {
+type WikiPageNavNode$1 = {
   type: "page";
   slug: string;
+  source?: string;
   icon?: string;
   hidden?: boolean;
 };
@@ -25,7 +44,7 @@ type WikiGroupNavNode = {
   icon?: string;
   expanded?: boolean;
   hidden?: boolean;
-  children: WikiNavNode[];
+  children: WikiNavNode$1[];
 };
 type WikiInternalSwitcherNavNode = {
   type: "tab" | "dropdown";
@@ -33,7 +52,7 @@ type WikiInternalSwitcherNavNode = {
   slug?: string;
   icon?: string;
   hidden?: boolean;
-  children: WikiNavNode[];
+  children: WikiNavNode$1[];
 };
 type WikiExternalSwitcherNavNode = {
   type: "tab" | "dropdown";
@@ -49,12 +68,17 @@ type WikiLinkNavNode = {
   icon?: string;
   hidden?: boolean;
 };
-type WikiNavNode = string | WikiPageNavNode | WikiGroupNavNode | WikiInternalSwitcherNavNode | WikiExternalSwitcherNavNode | WikiLinkNavNode;
+type WikiNavNode$1 = string | WikiPageNavNode$1 | WikiGroupNavNode | WikiInternalSwitcherNavNode | WikiExternalSwitcherNavNode | WikiLinkNavNode;
 declare const wikiConfigSchema: z.ZodObject<{
   id: z.ZodString;
   title: z.ZodString;
+  sourceVersion: z.ZodOptional<z.ZodLiteral<1>>;
+  labels: z.ZodOptional<z.ZodUnknown>;
+  assets: z.ZodDefault<z.ZodObject<{
+    directory: z.ZodDefault<z.ZodString>;
+  }, z.core.$strict>>;
   description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNull]>>;
-  navigation: z.ZodOptional<z.ZodArray<z.ZodType<WikiNavNode, unknown, z.core.$ZodTypeInternals<WikiNavNode, unknown>>>>;
+  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;
@@ -70,57 +94,292 @@ declare const wikiConfigSchema: z.ZodObject<{
     }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
-type WikiConfig = z.infer<typeof wikiConfigSchema>;
-declare function parseWikiConfig(raw: unknown): WikiConfig;
+type WikiConfig = Omit<z.infer<typeof wikiConfigSchema>, "labels"> & {
+  labels?: Record<string, string>;
+};
+export declare function parseWikiConfig(raw: unknown): WikiConfig;
 //#endregion
-//#region src/resource.d.ts
-type Resource = Asset | Guide | Wiki | WikiPage;
-type ResourceType = Resource["type"];
+//#region src/config/course.d.ts
+declare const moduleSchema: z.ZodObject<{
+  id: z.ZodString;
+  title: z.ZodString;
+  slug: z.ZodString;
+  order: z.ZodNumber;
+  description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  pages: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const courseConfigSchema: z.ZodObject<{
+  sourceVersion: z.ZodLiteral<1>;
+  id: z.ZodString;
+  title: z.ZodString;
+  slug: z.ZodString;
+  description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  persons: z.ZodOptional<z.ZodUnknown>;
+  assets: z.ZodDefault<z.ZodObject<{
+    directory: z.ZodDefault<z.ZodString>;
+  }, z.core.$strict>>;
+  modules: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    slug: z.ZodString;
+    order: z.ZodNumber;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    pages: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type CourseConfig = Omit<z.infer<typeof courseConfigSchema>, "persons"> & {
+  persons?: ReturnType<typeof parseSourcePersons>;
+};
+type CourseModuleConfig = z.infer<typeof moduleSchema>;
+export declare function parseCourseConfig(raw: unknown): CourseConfig;
+//#endregion
+//#region src/config/manifest.d.ts
+export declare const TOPIK_MANIFEST_FILENAME = ".topik.yaml";
+export declare const TOPIK_MANIFEST_LIMITS: {
+  readonly maxBytes: 1048576;
+  readonly maxSources: 1000;
+  readonly maxDepth: 32;
+};
+export declare const topikManifestSourceSchema: z.ZodObject<{
+  kind: z.ZodEnum<{
+    collection: "collection";
+    course: "course";
+    wiki: "wiki";
+  }>;
+  config: z.ZodString;
+}, z.core.$strict>;
+export declare const topikManifestSchema: z.ZodObject<{
+  version: z.ZodLiteral<1>;
+  namespace: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+  sources: z.ZodArray<z.ZodObject<{
+    kind: z.ZodEnum<{
+      collection: "collection";
+      course: "course";
+      wiki: "wiki";
+    }>;
+    config: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strict>;
+type TopikManifest = z.infer<typeof topikManifestSchema>;
+type TopikManifestSource = z.infer<typeof topikManifestSourceSchema>;
+export declare function parseTopikManifest(raw: unknown): TopikManifest;
+//#endregion
+//#region src/config/assets.d.ts
+export declare const DEFAULT_ASSET_DIRECTORY = "_assets";
+/** Source-local destination for new synced media; not an input scan or compiler output path. */
+export declare const sourceAssetsConfigSchema: z.ZodObject<{
+  directory: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+type SourceAssetsConfig = z.infer<typeof sourceAssetsConfigSchema>;
+//#endregion
+//#region src/compile/public-errors.d.ts
+declare const PUBLIC_COMPILE_ERROR_MESSAGES: {
+  readonly "manifest-required": 'Project compilation requires .topik.yaml in the selected directory. Add a manifest such as: {"version":1,"namespace":"owner/project","sources":[{"kind":"wiki","config":"wiki.yaml"}]}';
+  readonly "manifest-invalid": "Root manifest is invalid.";
+  readonly "manifest-source-failed": "Manifest source could not be compiled.";
+  readonly "manifest-resource-conflict": "Manifest sources produce conflicting resource identities.";
+  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-safe-read-unsupported": "This platform cannot safely open compilation inputs.";
+  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 "reference-targets-invalid": "Resource reference target catalogue is invalid.";
+  readonly "wiki-page-not-found": "A configured Wiki page file was not found.";
+  readonly "wiki-page-ambiguous": "A Wiki source path matches more than one Markdown file. Keep exactly one source file.";
+  readonly "course-page-not-found": "A configured Course page file was not found.";
+  readonly "course-page-ambiguous": "A Course source path matches more than one Markdown file. Keep exactly one source file.";
+  readonly "author-not-found": "An author must reference a Person in the declared project.";
+};
+type PublicCompileErrorId = keyof typeof PUBLIC_COMPILE_ERROR_MESSAGES;
+export declare function publicCompileErrorMessage(id: unknown): string | undefined;
+/** Public compiler failure with fixed wording, stable ID, and optional safe relative location. */
+export declare class PublicCompileError extends Error {
+  readonly id: PublicCompileErrorId;
+  readonly location?: string;
+  constructor(id: PublicCompileErrorId, location?: string);
+}
+//#endregion
+//#region src/compile/manifest.d.ts
+interface ManifestSourceDescriptor extends TopikManifestSource {
+  /** Zero-based declaration index, used only for provenance and diagnostics. */
+  sourceIndex: number;
+  /** Canonical root-relative directory; empty for the project root. */
+  directory: string;
+  /** Project namespace declared in the manifest. */
+  namespace: string;
+}
+interface ManifestSourceProvenance extends ManifestSourceDescriptor {
+  /** Root-relative destination for new synced media. Compilation does not write here. */
+  assetDirectory: string;
+  /** Authored resource keys mapped to root-relative content/config paths. */
+  sourcePathsByResource: Readonly<Record<string, string>>;
+}
+interface ManifestCompileResult extends CompileResult {
+  provenance: ManifestSourceProvenance[];
+}
+export declare class ManifestSourceError extends PublicCompileError {
+  readonly sourceIndex: number;
+  readonly kind?: TopikManifestSource["kind"];
+  constructor(id: PublicCompileErrorId, sourceIndex: number, kind?: TopikManifestSource["kind"], config?: string);
+}
+/** Explicit loading requires the canonical file in exactly the supplied root. */
+export declare function loadTopikManifest(dir: string): Promise<TopikManifest>;
+export declare function discoverManifestSources(options: CompileOptions): Promise<ManifestSourceDescriptor[]>;
+/** Compile only declared sources, sharing the existing local compiler and Asset pipeline. */
+export declare function compileManifest(options: CompileOptions): Promise<ManifestCompileResult>;
 //#endregion
 //#region src/compile/shared.d.ts
 interface CompileResult {
+  courseNavigation: CourseNavigationIndex;
+  /** Present for manifest compilation, in declaration order. */
+  provenance?: ManifestSourceProvenance[];
   diagnostics: TopikContentDiagnostic[];
-  resources: Resource[];
+  resources: CompiledResource[];
+  payloads: AssetPayload[];
+  semantic: TopikAssetSemanticRecordV1;
+  materialization: TopikMaterializationRecordV1;
+  /** Portable document references and their compilation-time validation state. */
+  references: CompiledResourceReference[];
 }
 type LinkValidationPolicy = "error" | "warning" | "off";
 interface CompileValidationOptions {
-  /** How unresolved wiki page links and same-page guide fragments are handled. */
+  /** How unresolved document targets and invalid destination fragments are handled. */
   links?: LinkValidationPolicy;
 }
-declare class CompileError extends Error {
+export declare class CompileError extends Error {
   readonly diagnostics: TopikContentDiagnostic[];
   constructor(diagnostics: TopikContentDiagnostic[]);
 }
-declare function isErrorDiagnostic(diagnostic: TopikContentDiagnostic): boolean;
+export declare function isErrorDiagnostic(diagnostic: TopikContentDiagnostic): boolean;
+//#endregion
+//#region src/compile/links.d.ts
+/** Optional application-provided catalogue; Topik never fetches targets. */
+interface CompileResourceReferenceTarget {
+  type: TopikResourceReference["type"];
+  name: string;
+  /** Published heading IDs, when known. Without them a fragment remains deferred. */
+  headings?: readonly string[];
+}
+interface CompiledResourceReference {
+  resource: string;
+  sourcePath: string;
+  kind: "link" | "card";
+  position: string;
+  /** The original authored destination, retained for source round trips. */
+  href: string;
+  reference: TopikResourceReference;
+  status: "verified" | "deferred" | "invalid";
+}
+interface CompileResourceLinksInput {
+  rootDir: string;
+  resources: readonly SourceResource[];
+  sourcePathsByResource: Readonly<Record<string, string>>;
+  sourceDirectoriesByResource?: Readonly<Record<string, string>>;
+  referenceTargets?: readonly CompileResourceReferenceTarget[];
+  /** @internal Source round-trip comparison may already contain compiled Asset locators. */
+  allowCompiledAssetReferences?: boolean;
+  validation?: CompileValidationOptions;
+}
+/** Resolve document identity after all declared sources have been discovered, before Assets. */
+export declare function compileResourceLinks(input: CompileResourceLinksInput): Promise<{
+  resources: SourceResource[];
+  diagnostics: TopikContentDiagnostic[];
+  references: CompiledResourceReference[];
+}>;
+//#endregion
+//#region src/compile/guide.d.ts
+interface CompileGuidesOptions {
+  dir: string;
+  /** Exact config path relative to dir; content is relative to the config directory. */
+  configFile?: string;
+  validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
+  referenceTargets?: readonly CompileResourceReferenceTarget[];
+}
+interface CompileResourceDiscovery {
+  courseNavigation?: CourseNavigationIndex;
+  sourceVersion?: 1;
+  /** Destination relative to the selected configuration directory, if a config was loaded. */
+  assetDirectory?: string;
+  diagnostics: CompileResult["diagnostics"];
+  resources: SourceResource[];
+  sourcePathsByResource: Record<string, string>;
+  consumedSourcePaths: string[];
+}
+export declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
+//#endregion
+//#region src/compile/discovery.d.ts
+interface DiscoverResourceOptions {
+  dir: string;
+  /** Exact config path relative to dir; content is relative to its directory. */
+  configFile?: string;
+}
+type SourceResourceDiscovery = CompileResourceDiscovery;
+/** Read authoring metadata and paths before combining a caller-owned source inventory. */
+export declare function discoverGuideResources(options: DiscoverResourceOptions): Promise<SourceResourceDiscovery>;
+/** Read authoring metadata and paths before combining a caller-owned source inventory. */
+export declare function discoverWikiResources(options: DiscoverResourceOptions): Promise<SourceResourceDiscovery>;
+/** Read Course membership, metadata and paths without compiling links or Assets. */
+export declare function discoverCourseResources(options: DiscoverResourceOptions): Promise<SourceResourceDiscovery>;
 //#endregion
 //#region src/compile/wiki.d.ts
 interface CompileWikiOptions {
   dir: string;
+  /** Exact config path relative to dir; content is relative to the config directory. */
+  configFile?: string;
   validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
+  referenceTargets?: readonly CompileResourceReferenceTarget[];
 }
-declare function compileWiki(options: CompileWikiOptions): Promise<CompileResult>;
-declare function pagePathToName(wikiId: string, pagePath: string): string;
+export declare function compileWiki(options: CompileWikiOptions): Promise<CompileResult>;
+export declare function pagePathToName(wikiId: string, pagePath: string): string;
 //#endregion
-//#region src/compile/guide.d.ts
-interface CompileGuidesOptions {
+//#region src/compile/course.d.ts
+interface CompileCourseOptions {
   dir: string;
+  /** Exact configuration path relative to dir; page sources are relative to its directory. */
+  configFile?: string;
   validation?: CompileValidationOptions;
+  assets?: AssetCompilationOptions;
+  referenceTargets?: readonly CompileResourceReferenceTarget[];
 }
-declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
+export declare function compileCourse(options: CompileCourseOptions): Promise<CompileResult>;
+//#endregion
+//#region src/compile/asset-names.d.ts
+interface ProjectAssetNameOptions {
+  /** Directory containing the manifest, or an explicitly chosen root for standalone use. */
+  projectRoot: string;
+  projectNamespace: string;
+}
+/** Create the project's naming policy without reading or requiring a manifest. */
+export declare function createProjectAssetNameGenerator(options: ProjectAssetNameOptions): AssetNameGenerator;
 //#endregion
 //#region src/compile/index.d.ts
 interface CompileOptions {
   dir: string;
   validation?: CompileValidationOptions;
+  /** Optional application-supplied inventory for explicit resource references. */
+  referenceTargets?: readonly CompileResourceReferenceTarget[];
 }
-declare function compile(options: CompileOptions): Promise<CompileResult>;
+/** Compile exactly the project declared by .topik.yaml in dir. */
+export declare function compile(options: CompileOptions): Promise<CompileResult>;
 interface LintResult {
   diagnostics: CompileResult["diagnostics"];
 }
-declare function lint(options: CompileOptions): Promise<LintResult>;
+export 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;
@@ -130,7 +389,7 @@ interface ValidationResult {
   errors: ValidationError[];
 }
 /** Validate the resources produced by `compile` and the CLI export. */
-declare function validateResources(resources: readonly unknown[]): ValidationResult;
+export declare function validateResources(resources: readonly unknown[]): ValidationResult;
 //#endregion
 //#region src/watch.d.ts
 interface WatchOptions {
@@ -139,15 +398,361 @@ interface WatchOptions {
 }
 type UpdateListener = (key: string, resource: Resource) => void;
 type ErrorListener = (error: Error) => void;
+type PreviewStateListener = (state: PreviewState) => void;
 interface Watcher {
-  /** Current compiled resources, keyed by `Type/name`. */
+  /** Compatibility inventory; replaced completely before any success notification. */
   resources: Map<string, Resource>;
+  payloads: Map<string, AssetPayload>;
+  /** Immutable, complete authoritative state. Treat resources/order/payloads as one commit. */
+  readonly state: PreviewState;
+  on(event: "preview-state", listener: PreviewStateListener): this;
   on(event: "update", listener: UpdateListener): this;
   on(event: "error", listener: ErrorListener): this;
+  off(event: "preview-state", listener: PreviewStateListener): this;
   off(event: "update", listener: UpdateListener): this;
   off(event: "error", listener: ErrorListener): this;
   close(): Promise<void>;
 }
-declare function watch(options: WatchOptions): Promise<Watcher>;
+export declare function watch(options: WatchOptions): Promise<Watcher>;
+//#endregion
+//#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;
+}
+export declare function validateTopikPath(input: string | Uint8Array, options?: ValidateTopikPathOptions): TopikAssetResult<ValidTopikPath>;
+export declare function computeTopikPathCollisionKey(path: string, options?: ValidateTopikPathOptions): TopikAssetResult<string>;
+export declare function validateTopikPathSet(paths: readonly string[], options?: ValidateTopikPathOptions): TopikAssetResult<Map<string, string>>;
+/** Unicode 17 NFKC casefold for topik-path-v1-admitted input. */
+export declare function toNfkcCasefold(value: string): string;
+//#endregion
+//#region src/assets/json.d.ts
+export declare class TopikJsonSyntaxError extends SyntaxError {
+  readonly offset: number;
+  readonly duplicatePointer?: string | undefined;
+  constructor(message: string, offset: number, duplicatePointer?: string | undefined);
+}
+export declare function parseStrictTopikJson(source: string, maxDepth?: number): unknown;
+/** RFC 8785 scalar/member rules with Topik's two-space layout and final LF. */
+export declare function serializeTopikJson(value: unknown): string;
+export 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;
+}
+export declare function validatePortableAssetFile(file: PortableAssetFileDescriptor): TopikAssetResult<PortableAssetFileDescriptor>;
+export declare function validatePortableAssetTree(files: readonly PortableAssetFileDescriptor[]): TopikAssetResult<readonly PortableAssetFileDescriptor[]>;
+interface ReadPortableAssetFileOptions {
+  root: string;
+  path: string;
+  /** Optional tighter read limit; cannot exceed the portable asset maximum. */
+  maxBytes?: number;
+}
+/** Filesystem reader using no-follow traversal and stable same-handle identity checks. */
+export declare function readPortableAssetFile(options: ReadPortableAssetFileOptions): Promise<TopikAssetResult<PortableAssetFileDescriptor>>;
+export declare function looksLikeGitLfsPointer(bytes: Uint8Array): boolean;
+//#endregion
+//#region src/assets/media.d.ts
+export declare const TOPIK_UNRESOLVED_ACTIVE_CONTENT_TYPE: "application/x-topik-active-content";
+/** Sniff exact bytes conservatively. Unknown safe bytes remain opaque downloads. */
+export declare function sniffPortableMediaType(bytes: Uint8Array): string;
+export declare function isTopikActiveMediaType(mediaType: string): boolean;
+export declare function isInlineMediaCompatible(mediaType: string, role: string): boolean;
+//#endregion
+//#region src/source/syntax.d.ts
+interface SourceByteRange {
+  start: number;
+  end: number;
+}
+interface SourceFieldEvidence {
+  selector: string;
+  value?: SourceByteRange;
+  entry?: SourceByteRange;
+  insertion: number;
+}
+interface SourceByteEdit extends SourceByteRange {
+  selector: string;
+  oldSha256: string;
+  replacement: Uint8Array;
+}
+//#endregion
+//#region src/source/project.d.ts
+export declare const SOURCE_WRITER_VERSION: "topik-source-writer-v1";
+export declare const SOURCE_PROJECT_LIMITS: {
+  readonly maxFiles: 10000;
+  readonly maxFileBytes: 268435456;
+  readonly maxTreeBytes: 536870912;
+};
+export declare const SOURCE_WRITER_DESCRIPTOR: {
+  readonly writer: "topik-source-writer-v1";
+  readonly manifest: 1;
+  readonly sourceVersions: readonly [0, 1];
+  readonly formatter: 1;
+  readonly contentSchema: "0.2.2";
+  readonly resourceSchema: "v1";
+  readonly references: "source-links-v5";
+  readonly provenance: 7;
+  readonly graph: "authored-resource-bytes-v1";
+  readonly packageVersion: string;
+};
+interface SourceTreeFile {
+  path: string;
+  mode: "100644" | "100755";
+  bytes: Uint8Array;
+}
+interface SourceDocumentProvenance {
+  resource: string;
+  apiVersion: Resource["apiVersion"];
+  type: Resource["type"];
+  name: string;
+  path: string;
+  config: string;
+  kind: ManifestSourceProvenance["kind"];
+  directory: string;
+  sourceVersion?: 1;
+  sha256: string;
+  mode: SourceTreeFile["mode"];
+  body?: SourceByteRange;
+  frontmatter?: SourceByteRange;
+  fields: readonly SourceFieldEvidence[];
+  fieldOrigins: readonly SourceFieldOrigin[];
+  /** Recognized legacy metadata whose compiled value would lose authored meaning. */
+  lossyMetadata?: readonly string[];
+  /** Context travels with immutable saved source; a later source move must not reinterpret it. */
+  sourceContext: {
+    path: string;
+    extension: string;
+    /** Key in SourceProject.wikiContexts; retain that snapshot with saved content. */
+    wiki?: string;
+    /** Key in SourceProject.courseContexts for a Course page's immutable saved links. */
+    course?: string;
+  };
+  references: readonly (TopikNavigationReference & {
+    target?: string;
+    search?: string;
+    hash?: string;
+  })[];
+  /** Complete derived Asset identity closure for this compiled resource. */
+  assetReferences: readonly string[];
+}
+interface SourceFieldOrigin {
+  field: string;
+  origin: "explicit" | "derived" | "inherited" | "default";
+  path?: string;
+  selector?: string;
+  range?: SourceByteRange;
+}
+interface SourceConfigurationProvenance {
+  path: string;
+  sha256: string;
+  mode: SourceTreeFile["mode"];
+  fields: readonly SourceFieldEvidence[];
+  insertion: number;
+}
+interface SourceProject {
+  tree: readonly SourceTreeFile[];
+  treeDigest: string;
+  manifest: TopikManifest;
+  manifestSha256: string;
+  compilation: ManifestCompileResult;
+  documents: readonly SourceDocumentProvenance[];
+  configurations: readonly SourceConfigurationProvenance[];
+  wikiContexts: Readonly<Record<string, Wiki>>;
+  courseContexts: Readonly<Record<string, CourseReferenceContext>>;
+  descriptor: typeof SOURCE_WRITER_DESCRIPTOR;
+}
+export declare function digestSourceTree(tree: readonly SourceTreeFile[]): string;
+/** Seal the exact desired authoring graph without parsing or formatting its content. */
+export declare function digestSourceResourceGraph(resources: readonly Resource[]): string;
+/** Inspection compiles exactly the manifest tree and retains original documents and byte ranges. */
+export declare function readSourceProject(input: {
+  tree: readonly SourceTreeFile[];
+}): Promise<SourceProject>;
+//#endregion
+//#region src/source/asset-context.d.ts
+type SourceAssetReferenceContexts = Readonly<Record<string, Readonly<Record<string, string>>>>;
+//#endregion
+//#region src/source/initialize.d.ts
+interface SourceInitializationIntent {
+  namespace: string;
+  source: TopikManifestSource & {
+    id: string;
+    title: string;
+    assetDirectory?: string;
+  };
+}
+interface SourceMediaSelection {
+  name: string;
+  filename: string;
+  sha256: string;
+  bytes: Uint8Array;
+}
+interface InitializeSourceProjectInput {
+  /** Full occupied-path inventory; missing/invalid manifests are never admitted as empty projects. */
+  tree: readonly SourceTreeFile[];
+  expectedTreeDigest: string;
+  packageCohort: string;
+  /** This explicit reviewed intent is sealed by the application before planning. */
+  intent: SourceInitializationIntent;
+  resources: readonly Resource[];
+  media?: readonly SourceMediaSelection[];
+  /** Immutable Wiki context retained with each saved page body. */
+  referenceContexts?: Readonly<Record<string, Wiki>>;
+  courseReferenceContexts?: Readonly<Record<string, CourseReferenceContext>>;
+  /** Explicit new Guide or CoursePage file paths, independently admitted in createPaths. */
+  documentPaths?: Readonly<Record<string, string>>;
+  assetReferenceContexts?: SourceAssetReferenceContexts;
+  /** Exact expected-absence paths admitted from the complete inventory. */
+  createPaths: readonly string[];
+}
+/** Initialization is distinct from adding a source to a valid existing manifest. */
+export declare function initializeSourceProject(input: InitializeSourceProjectInput): Promise<SourcePlanResult>;
+interface AddSourceToProjectInput {
+  project: SourceProject;
+  expectedTreeDigest: string;
+  packageCohort: string;
+  source: SourceInitializationIntent["source"];
+  resources: readonly Resource[];
+  media?: readonly SourceMediaSelection[];
+  referenceContexts?: Readonly<Record<string, Wiki>>;
+  courseReferenceContexts?: Readonly<Record<string, CourseReferenceContext>>;
+  documentPaths?: Readonly<Record<string, string>>;
+  assetReferenceContexts?: SourceAssetReferenceContexts;
+  createPaths: readonly string[];
+  manifestAuthority: SourceSharedAuthority;
+}
+/** Adding a declaration preserves the existing namespace, order and every original source. */
+export declare function addSourceToProject(input: AddSourceToProjectInput): Promise<SourcePlanResult>;
+//#endregion
+//#region src/source/diagnostics.d.ts
+interface SourcePlanDiagnostic {
+  code: string;
+  message: string;
+  resource?: string;
+  path?: string;
+  /** One-based lines in the compiled document body, excluding frontmatter. */
+  lines?: readonly number[];
+  sourceIndex?: number;
+  kind?: "wiki" | "collection" | "course";
+  config?: string;
+}
+//#endregion
+//#region src/source/plan.d.ts
+type SourceResourceOperation = {
+  kind: "update" | "delete";
+  resource: string;
+} | {
+  kind: "move";
+  resource: string;
+  path: string;
+} | {
+  kind: "create";
+  resource: string;
+  config: string;
+  path?: string;
+};
+interface SourceExclusiveAuthority {
+  path: string;
+  sha256: string;
+  mode: SourceTreeFile["mode"];
+}
+interface SourceSharedAuthority extends SourceExclusiveAuthority {
+  fields: readonly SourceFieldEvidence[];
+}
+interface SourceWriteAuthority {
+  /** Resources whose authored or shared referenced facts may change, admitted independently. */
+  resources: readonly string[];
+  exclusive: readonly SourceExclusiveAuthority[];
+  shared: readonly SourceSharedAuthority[];
+  create: readonly string[];
+}
+interface SourceFileChange {
+  kind: "create" | "update" | "delete";
+  path: string;
+  base: {
+    sha256: string;
+    mode: SourceTreeFile["mode"];
+  } | null;
+  candidate: {
+    sha256: string;
+    mode: SourceTreeFile["mode"];
+    bytes: Uint8Array;
+  } | null;
+  sharedEdits?: readonly SourceByteEdit[];
+}
+interface SourceUpdatePlan {
+  assetMappings: readonly {
+    from: string;
+    to: string;
+    path: string;
+  }[];
+  descriptor: typeof SOURCE_WRITER_DESCRIPTOR;
+  packageCohort: string;
+  baseTreeDigest: string;
+  desiredGraphDigest: string;
+  candidateTreeDigest: string;
+  planDigest: string;
+  changes: readonly SourceFileChange[];
+  candidate: SourceProject;
+  affectedResources: readonly string[];
+  derivedRepairs: readonly {
+    resource: string;
+    kind: "navigation" | "reference";
+    position?: string;
+    before?: string;
+    after?: string;
+    target?: string;
+  }[];
+}
+type SourcePlanResult = {
+  ok: true;
+  plan: SourceUpdatePlan;
+} | {
+  ok: false;
+  diagnostics: readonly SourcePlanDiagnostic[];
+};
+interface PlanSourceUpdatesInput {
+  project: SourceProject;
+  expectedTreeDigest: string;
+  packageCohort: string;
+  /** Complete project graph, including untouched declarations and derived Assets. */
+  desiredResources: readonly Resource[];
+  operations: readonly SourceResourceOperation[];
+  authority: SourceWriteAuthority;
+  /** Explicit reviewed opt-in; reserved legacy keys still block it. */
+  optInConfigs?: readonly string[];
+  /** Retained portable context of saved authoring content, before previous source repairs. */
+  referenceContexts?: Readonly<Record<string, Wiki>>;
+  /** Retained Course route/source snapshots keyed by CoursePage identity. */
+  courseReferenceContexts?: Readonly<Record<string, CourseReferenceContext>>;
+  assetReferenceContexts?: SourceAssetReferenceContexts;
+  media?: readonly (SourceMediaSelection & {
+    config: string;
+  })[];
+}
+/** The complete candidate is compiled before any applicable file changes are returned. */
+export declare function planSourceUpdates(input: PlanSourceUpdatesInput): Promise<SourcePlanResult>;
 //#endregion
-export { type CollectionConfig, CompileError, type CompileGuidesOptions, type CompileOptions, type CompileResult, type CompileValidationOptions, type CompileWikiOptions, type LinkValidationPolicy, type LintResult, type Resource, type ResourceType, type ValidationError, type ValidationResult, type WatchOptions, type Watcher, type WikiConfig, compile, compileGuides, compileWiki, isErrorDiagnostic, lint, pagePathToName, parseCollectionConfig, parseWikiConfig, validateResources, watch };
+export { ASSET_API_VERSION, ASSET_SCHEMA_ID, ASSET_TYPE, type AddSourceToProjectInput, type AssetBlobUri, AssetCompilationError, type AssetCompilationOptions, type AssetCompilationResult, type AssetNameGenerator, type AssetNameInput, type AssetPayload, type CollectionConfig, type CompileAssetResourcesInput, type CompileCourseOptions, type CompileGuidesOptions, type CompileOptions, type CompileResourceLinksInput, type CompileResourceReferenceTarget, type CompileResult, type CompileValidationOptions, type CompileWikiOptions, type CompiledAsset, type CompiledResource, type CompiledResourceReference, type ContentBearingResource, type CourseConfig, type CourseModuleConfig, CourseNavigationIndex, CourseNavigationModule, type CourseReferenceContext, type DiscoverResourceOptions, type ExternalWikiDropdown, type ExternalWikiTab, type GenerateAutomaticAssetNameOptions, type GeneratedAssetName, type InitializeSourceProjectInput, type InternalWikiDropdown, type InternalWikiTab, type LinkValidationPolicy, type LintResult, type ManifestCompileResult, type ManifestSourceDescriptor, type ManifestSourceProvenance, type ParsedAsset, type PlanSourceUpdatesInput, type PortableAssetFileDescriptor, type PortableAssetFileType, PreviewDiagnostic, PreviewPayloadDescriptor, PreviewState, type ProjectAssetNameOptions, type PublicCompileErrorId, type ReadPortableAssetFileOptions, type ResolvedCourseContentLink, type ResolvedCourseContentReference, type ResolvedCourseNavigation, type ResolvedCoursePage, type ResolvedWikiContentLink, type ResolvedWikiContentReference, type ResolvedWikiNavigation, type ResolvedWikiPage, type Resource, type ResourceType, type SourceAssetsConfig, type SourceByteEdit, type SourceByteRange, type SourceConfigurationProvenance, type SourceDocumentProvenance, type SourceExclusiveAuthority, type SourceFieldEvidence, type SourceFieldOrigin, type SourceFileChange, type SourceInitializationIntent, type SourceMediaSelection, type SourcePlanDiagnostic, type SourcePlanResult, type SourceProject, type SourceResource, type SourceResourceDiscovery, type SourceResourceOperation, type SourceSharedAuthority, type SourceTreeFile, type SourceUpdatePlan, type SourceWriteAuthority, 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_PREVIEW_PROTOCOL, type TopikAssetCorrelationId, type TopikAssetDiagnostic, type TopikAssetDiagnosticId, type TopikAssetDiagnosticLocation, type TopikAssetPathDiagnosticReason, type TopikAssetRecoveryCategory, type TopikAssetReferenceMappingV1, type TopikAssetResult, type TopikAssetSemanticRecordV1, type TopikManifest, type TopikManifestSource, 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, compileAssetResources, correlateTopikAssetResult, createTopikAssetSemanticRecord, createTopikMaterializationRecord, digestTopikAssetSemanticRecord, digestTopikMaterializationRecord, findFirstWikiPage, findWikiPageAncestors, generateAutomaticAssetName, hasWikiNavChildren, isAssetBlobUri, isExternalWikiDropdown, isExternalWikiTab, isGeneratedAssetName, isInternalWikiDropdown, isInternalWikiTab, joinWikiPath, parseAsset, parseAssetBlobUri, parseGeneratedAssetName, resolveCourseContentHref, resolveCourseContentReference, resolveCourseNavigation, resolveWikiContentHref, resolveWikiContentReference, resolveWikiNavigation, serializeAsset, topikAssetNameDescriptor, validateAssetBlobUri, validateAssetValue, validateProjectNamespace, validateTopikMaterializationRecord };