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

package/dist/index.d.mts

@@ -1,26 +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 { TopikContentDiagnostic, TopikGeneratedAssetName } 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";
-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/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$1 = {
   type: "page";
   slug: string;
+  source?: string;
   icon?: string;
   hidden?: boolean;
 };
@@ -59,6 +72,11 @@ type WikiNavNode$1 = string | WikiPageNavNode$1 | WikiGroupNavNode | WikiInterna
 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$1, unknown, z.core.$ZodTypeInternals<WikiNavNode$1, unknown>>>>;
   theme: z.ZodOptional<z.ZodObject<{
@@ -76,294 +94,288 @@ 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;
-//#endregion
-//#region src/resource.d.ts
-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;
+type WikiConfig = Omit<z.infer<typeof wikiConfigSchema>, "labels"> & {
+  labels?: Record<string, string>;
 };
+export declare function parseWikiConfig(raw: unknown): WikiConfig;
 //#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;
+//#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>;
 };
-declare function correlateTopikAssetResult<T>(result: TopikAssetResult<T>, correlationId: TopikAssetCorrelationId): TopikAssetResult<T>;
+type CourseModuleConfig = z.infer<typeof moduleSchema>;
+export declare function parseCourseConfig(raw: unknown): CourseConfig;
 //#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;
+//#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/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;
-}>;
+//#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/assets.d.ts
-type ContentBearingResource = CoursePage | Guide | WikiPage;
-interface AssetCompilationOptions {
-  /** Required only when supported local references are discovered automatically. */
-  sourceNamespace?: string;
+//#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);
 }
-interface CompileAssetResourcesInput extends AssetCompilationOptions {
-  rootDir: string;
-  resources: readonly SourceResource[];
-  /** Compilation-root-relative source paths keyed by `Type/name`. */
+//#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>>;
-  /** 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;
+interface ManifestCompileResult extends CompileResult {
+  provenance: ManifestSourceProvenance[];
 }
-type CompiledResource = SourceResource | CompiledAsset;
-declare class AssetCompilationError extends Error {
-  readonly diagnostics: readonly TopikAssetDiagnostic[];
-  constructor(message: string, diagnostics?: readonly TopikAssetDiagnostic[]);
+export declare class ManifestSourceError extends PublicCompileError {
+  readonly sourceIndex: number;
+  readonly kind?: TopikManifestSource["kind"];
+  constructor(id: PublicCompileErrorId, sourceIndex: number, kind?: TopikManifestSource["kind"], config?: string);
 }
-/** Discover and resolve one compilation-wide Asset set and deduplicated payload inventory. */
-declare function compileAssetResources(input: CompileAssetResourcesInput): Promise<AssetCompilationResult>;
+/** 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: 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[];
 }
-declare function compileGuides(options: CompileGuidesOptions): Promise<CompileResult>;
+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/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);
+//#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[];
 }
+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;
-  assets?: AssetCompilationOptions;
+  /** 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 {
@@ -377,72 +389,31 @@ interface ValidationResult {
   errors: ValidationError[];
 }
 /** 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;
+export declare function validateResources(resources: readonly unknown[]): ValidationResult;
 //#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;
+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>;
-  /** Current deduplicated local payloads, keyed by compilation-relative output path. */
   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 {
@@ -458,22 +429,22 @@ interface ValidTopikPath {
   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>>;
+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. */
-declare function toNfkcCasefold(value: string): string;
+export declare function toNfkcCasefold(value: string): string;
 //#endregion
 //#region src/assets/json.d.ts
-declare class TopikJsonSyntaxError extends SyntaxError {
+export 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;
+export 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(): {
+export declare function serializeTopikJson(value: unknown): string;
+export declare function topikJsonDescriptor(): {
   id: typeof TOPIK_JSON_VERSION;
 };
 //#endregion
@@ -491,21 +462,297 @@ interface PortableAssetFileDescriptor {
   contentFilter?: string;
   workingTreeEncoding?: string;
 }
-declare function validatePortableAssetFile(file: PortableAssetFileDescriptor): TopikAssetResult<PortableAssetFileDescriptor>;
-declare function validatePortableAssetTree(files: readonly PortableAssetFileDescriptor[]): TopikAssetResult<readonly PortableAssetFileDescriptor[]>;
+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. */
-declare function readPortableAssetFile(options: ReadPortableAssetFileOptions): Promise<TopikAssetResult<PortableAssetFileDescriptor>>;
-declare function looksLikeGitLfsPointer(bytes: Uint8Array): boolean;
+export declare function readPortableAssetFile(options: ReadPortableAssetFileOptions): Promise<TopikAssetResult<PortableAssetFileDescriptor>>;
+export 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";
+export 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;
+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 { 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 };
+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 };