@takuhon/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1843 @@
+var $schema = "https://json-schema.org/draft/2020-12/schema";
+var $id = "https://takuhon.example/schemas/0.1.0/takuhon.schema.json";
+var title = "Takuhon Profile";
+var description = "Portable profile data format consumed by @takuhon/core. The canonical contract for profile content authored as takuhon.json.";
+var type = "object";
+var additionalProperties = false;
+var required = [
+	"schemaVersion",
+	"profile",
+	"links",
+	"careers",
+	"projects",
+	"skills",
+	"contact",
+	"settings",
+	"meta"
+];
+var properties = {
+	schemaVersion: {
+		type: "string",
+		pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.-]+)?$",
+		description: "Semantic version of the takuhon schema this document conforms to."
+	},
+	profile: {
+		$ref: "#/$defs/Profile"
+	},
+	links: {
+		type: "array",
+		maxItems: 100,
+		items: {
+			$ref: "#/$defs/Link"
+		}
+	},
+	careers: {
+		type: "array",
+		maxItems: 50,
+		items: {
+			$ref: "#/$defs/Career"
+		}
+	},
+	projects: {
+		type: "array",
+		maxItems: 100,
+		items: {
+			$ref: "#/$defs/Project"
+		}
+	},
+	skills: {
+		type: "array",
+		maxItems: 200,
+		items: {
+			$ref: "#/$defs/Skill"
+		}
+	},
+	contact: {
+		$ref: "#/$defs/Contact"
+	},
+	settings: {
+		$ref: "#/$defs/Settings"
+	},
+	meta: {
+		$ref: "#/$defs/Meta"
+	}
+};
+var $defs = {
+	LocaleTag: {
+		type: "string",
+		minLength: 2,
+		maxLength: 35,
+		pattern: "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$",
+		description: "BCP-47 language tag (e.g., 'en', 'ja', 'zh-Hant', 'pt-BR')."
+	},
+	Iso3166Alpha2: {
+		type: "string",
+		pattern: "^[A-Z]{2}$",
+		description: "ISO 3166-1 alpha-2 country code (uppercase, two letters)."
+	},
+	YearMonth: {
+		type: "string",
+		pattern: "^[0-9]{4}-(0[1-9]|1[0-2])$",
+		description: "Year-month in 'YYYY-MM' format (Gregorian calendar)."
+	},
+	IsoDateTime: {
+		type: "string",
+		format: "date-time",
+		description: "ISO 8601 date-time (e.g., 2026-05-11T12:34:56Z)."
+	},
+	Url: {
+		type: "string",
+		format: "uri",
+		maxLength: 2048
+	},
+	Email: {
+		type: "string",
+		format: "email",
+		maxLength: 254
+	},
+	Slug: {
+		type: "string",
+		minLength: 1,
+		maxLength: 64,
+		pattern: "^[a-z0-9][a-z0-9-]*$",
+		description: "URL-safe identifier (lowercase alphanumerics and hyphens, must start with alphanumeric)."
+	},
+	LocalizedTitle: {
+		type: "object",
+		minProperties: 1,
+		propertyNames: {
+			type: "string",
+			pattern: "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$"
+		},
+		additionalProperties: {
+			type: "string",
+			minLength: 1,
+			maxLength: 200
+		},
+		description: "Map of BCP-47 locale tag to short title-like string (max 200 chars per value)."
+	},
+	LocalizedBody: {
+		type: "object",
+		minProperties: 1,
+		propertyNames: {
+			type: "string",
+			pattern: "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$"
+		},
+		additionalProperties: {
+			type: "string",
+			minLength: 1,
+			maxLength: 5000
+		},
+		description: "Map of BCP-47 locale tag to body-length string (max 5000 chars per value)."
+	},
+	LinkType: {
+		type: "string",
+		"enum": [
+			"website",
+			"blog",
+			"github",
+			"gitlab",
+			"linkedin",
+			"x",
+			"mastodon",
+			"bluesky",
+			"instagram",
+			"youtube",
+			"threads",
+			"facebook",
+			"email",
+			"rss",
+			"custom"
+		],
+		description: "Identifies the kind of link. 'custom' requires iconUrl."
+	},
+	Profile: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"displayName"
+		],
+		properties: {
+			displayName: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			tagline: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			bio: {
+				$ref: "#/$defs/LocalizedBody"
+			},
+			avatar: {
+				$ref: "#/$defs/Avatar"
+			},
+			location: {
+				$ref: "#/$defs/Address"
+			}
+		}
+	},
+	Avatar: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"url"
+		],
+		properties: {
+			url: {
+				type: "string",
+				format: "uri-reference",
+				maxLength: 2048,
+				description: "URL or path to the avatar image."
+			},
+			alt: {
+				$ref: "#/$defs/LocalizedTitle"
+			}
+		}
+	},
+	Address: {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			country: {
+				$ref: "#/$defs/Iso3166Alpha2"
+			},
+			region: {
+				type: "string",
+				maxLength: 100
+			},
+			locality: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			display: {
+				$ref: "#/$defs/LocalizedTitle"
+			}
+		}
+	},
+	Link: {
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"id",
+			"type",
+			"url"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			type: {
+				$ref: "#/$defs/LinkType"
+			},
+			label: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			url: {
+				$ref: "#/$defs/Url"
+			},
+			featured: {
+				type: "boolean"
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			},
+			iconUrl: {
+				$ref: "#/$defs/Url"
+			}
+		},
+		allOf: [
+			{
+				"if": {
+					properties: {
+						type: {
+							"const": "custom"
+						}
+					},
+					required: [
+						"type"
+					]
+				},
+				then: {
+					properties: {
+						iconUrl: {
+							$ref: "#/$defs/Url"
+						}
+					},
+					required: [
+						"iconUrl"
+					]
+				}
+			}
+		]
+	},
+	Career: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"id",
+			"organization",
+			"role",
+			"startDate"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			organization: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			role: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			description: {
+				$ref: "#/$defs/LocalizedBody"
+			},
+			startDate: {
+				$ref: "#/$defs/YearMonth"
+			},
+			endDate: {
+				anyOf: [
+					{
+						$ref: "#/$defs/YearMonth"
+					},
+					{
+						type: "null"
+					}
+				]
+			},
+			isCurrent: {
+				type: "boolean"
+			},
+			url: {
+				$ref: "#/$defs/Url"
+			},
+			location: {
+				$ref: "#/$defs/Address"
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			}
+		}
+	},
+	Project: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"id",
+			"title"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			title: {
+				$ref: "#/$defs/LocalizedTitle"
+			},
+			description: {
+				$ref: "#/$defs/LocalizedBody"
+			},
+			url: {
+				$ref: "#/$defs/Url"
+			},
+			tags: {
+				type: "array",
+				maxItems: 30,
+				items: {
+					type: "string",
+					minLength: 1,
+					maxLength: 50
+				}
+			},
+			relatedCareerId: {
+				$ref: "#/$defs/Slug"
+			},
+			startDate: {
+				$ref: "#/$defs/YearMonth"
+			},
+			endDate: {
+				anyOf: [
+					{
+						$ref: "#/$defs/YearMonth"
+					},
+					{
+						type: "null"
+					}
+				]
+			},
+			highlighted: {
+				type: "boolean"
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			}
+		}
+	},
+	Skill: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"id",
+			"label"
+		],
+		properties: {
+			id: {
+				$ref: "#/$defs/Slug"
+			},
+			label: {
+				type: "string",
+				minLength: 1,
+				maxLength: 100
+			},
+			category: {
+				type: "string",
+				minLength: 1,
+				maxLength: 64,
+				description: "Recommended values (extensible): programming, design, business, communication, language, music, art, sports, other."
+			},
+			order: {
+				type: "integer",
+				minimum: 0
+			}
+		}
+	},
+	Contact: {
+		type: "object",
+		additionalProperties: true,
+		properties: {
+			email: {
+				$ref: "#/$defs/Email"
+			},
+			showEmail: {
+				type: "boolean",
+				"default": false
+			},
+			formUrl: {
+				$ref: "#/$defs/Url"
+			}
+		}
+	},
+	Settings: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"defaultLocale",
+			"availableLocales"
+		],
+		properties: {
+			defaultLocale: {
+				$ref: "#/$defs/LocaleTag"
+			},
+			fallbackLocale: {
+				$ref: "#/$defs/LocaleTag"
+			},
+			availableLocales: {
+				type: "array",
+				minItems: 1,
+				maxItems: 50,
+				uniqueItems: true,
+				items: {
+					$ref: "#/$defs/LocaleTag"
+				}
+			},
+			theme: {
+				type: "string",
+				minLength: 1,
+				maxLength: 64,
+				description: "UI theme identifier. 'default' is the built-in theme; adapters may add more."
+			},
+			showPoweredBy: {
+				type: "boolean",
+				"default": true,
+				description: "Display the 'Powered by takuhon' attribution in the rendered profile."
+			},
+			enableJsonLd: {
+				type: "boolean",
+				"default": true,
+				description: "Emit Schema.org JSON-LD on the rendered profile page."
+			},
+			enableApi: {
+				type: "boolean",
+				"default": true,
+				description: "Expose the public read API endpoints (GET /api/profile, /api/jsonld, /api/schema, /takuhon.json)."
+			},
+			enableAnalytics: {
+				type: "boolean",
+				"default": false,
+				description: "Opt-in flag for first-party analytics. Default is false to keep takuhon privacy-respecting by default."
+			}
+		}
+	},
+	Meta: {
+		type: "object",
+		additionalProperties: true,
+		required: [
+			"contentLicense"
+		],
+		properties: {
+			createdAt: {
+				$ref: "#/$defs/IsoDateTime"
+			},
+			updatedAt: {
+				$ref: "#/$defs/IsoDateTime"
+			},
+			generator: {
+				type: "string",
+				minLength: 1,
+				maxLength: 100,
+				description: "Tool that produced this document (e.g. 'Takuhon', 'create-takuhon@0.1.0')."
+			},
+			contentLicense: {
+				$ref: "#/$defs/ContentLicense"
+			}
+		}
+	},
+	ContentLicense: {
+		type: "object",
+		additionalProperties: false,
+		required: [
+			"spdxId"
+		],
+		properties: {
+			spdxId: {
+				type: "string",
+				minLength: 1,
+				maxLength: 64,
+				description: "SPDX identifier (e.g., 'CC-BY-4.0', 'CC0-1.0') or 'Proprietary'. No default; the profile owner must choose explicitly."
+			},
+			url: {
+				$ref: "#/$defs/Url"
+			},
+			attribution: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					name: {
+						type: "string",
+						minLength: 1,
+						maxLength: 200
+					},
+					url: {
+						$ref: "#/$defs/Url"
+					}
+				}
+			},
+			rights: {
+				type: "string",
+				minLength: 1,
+				maxLength: 1000,
+				description: "Free-form rights statement (used when spdxId='Proprietary' or for additional notices)."
+			}
+		}
+	}
+};
+var schemaJson = {
+	$schema: $schema,
+	$id: $id,
+	title: title,
+	description: description,
+	type: type,
+	additionalProperties: additionalProperties,
+	required: required,
+	properties: properties,
+	$defs: $defs
+};
+
+/**
+ * Re-exports the canonical JSON Schema for takuhon profiles.
+ *
+ * The schema source of truth lives at `packages/core/takuhon.schema.json`
+ * (also distributed via the `@takuhon/core/schema.json` sub-path). This module
+ * is the convenient ESM-side entry point for consumers that want to feed it
+ * directly to a JSON Schema validator (e.g. Ajv) without a filesystem read.
+ */
+
+declare const schema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: string;
+    additionalProperties: boolean;
+    required: string[];
+    properties: {
+        schemaVersion: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        profile: {
+            $ref: string;
+        };
+        links: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        careers: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        projects: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        skills: {
+            type: string;
+            maxItems: number;
+            items: {
+                $ref: string;
+            };
+        };
+        contact: {
+            $ref: string;
+        };
+        settings: {
+            $ref: string;
+        };
+        meta: {
+            $ref: string;
+        };
+    };
+    $defs: {
+        LocaleTag: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+            description: string;
+        };
+        Iso3166Alpha2: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        YearMonth: {
+            type: string;
+            pattern: string;
+            description: string;
+        };
+        IsoDateTime: {
+            type: string;
+            format: string;
+            description: string;
+        };
+        Url: {
+            type: string;
+            format: string;
+            maxLength: number;
+        };
+        Email: {
+            type: string;
+            format: string;
+            maxLength: number;
+        };
+        Slug: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+            pattern: string;
+            description: string;
+        };
+        LocalizedTitle: {
+            type: string;
+            minProperties: number;
+            propertyNames: {
+                type: string;
+                pattern: string;
+            };
+            additionalProperties: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            description: string;
+        };
+        LocalizedBody: {
+            type: string;
+            minProperties: number;
+            propertyNames: {
+                type: string;
+                pattern: string;
+            };
+            additionalProperties: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            description: string;
+        };
+        LinkType: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        Profile: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                displayName: {
+                    $ref: string;
+                };
+                tagline: {
+                    $ref: string;
+                };
+                bio: {
+                    $ref: string;
+                };
+                avatar: {
+                    $ref: string;
+                };
+                location: {
+                    $ref: string;
+                };
+            };
+        };
+        Avatar: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                url: {
+                    type: string;
+                    format: string;
+                    maxLength: number;
+                    description: string;
+                };
+                alt: {
+                    $ref: string;
+                };
+            };
+        };
+        Address: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                country: {
+                    $ref: string;
+                };
+                region: {
+                    type: string;
+                    maxLength: number;
+                };
+                locality: {
+                    $ref: string;
+                };
+                display: {
+                    $ref: string;
+                };
+            };
+        };
+        Link: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                type: {
+                    $ref: string;
+                };
+                label: {
+                    $ref: string;
+                };
+                url: {
+                    $ref: string;
+                };
+                featured: {
+                    type: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+                iconUrl: {
+                    $ref: string;
+                };
+            };
+            allOf: {
+                if: {
+                    properties: {
+                        type: {
+                            const: string;
+                        };
+                    };
+                    required: string[];
+                };
+                then: {
+                    properties: {
+                        iconUrl: {
+                            $ref: string;
+                        };
+                    };
+                    required: string[];
+                };
+            }[];
+        };
+        Career: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                organization: {
+                    $ref: string;
+                };
+                role: {
+                    $ref: string;
+                };
+                description: {
+                    $ref: string;
+                };
+                startDate: {
+                    $ref: string;
+                };
+                endDate: {
+                    anyOf: ({
+                        $ref: string;
+                        type?: undefined;
+                    } | {
+                        type: string;
+                        $ref?: undefined;
+                    })[];
+                };
+                isCurrent: {
+                    type: string;
+                };
+                url: {
+                    $ref: string;
+                };
+                location: {
+                    $ref: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        Project: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                title: {
+                    $ref: string;
+                };
+                description: {
+                    $ref: string;
+                };
+                url: {
+                    $ref: string;
+                };
+                tags: {
+                    type: string;
+                    maxItems: number;
+                    items: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                };
+                relatedCareerId: {
+                    $ref: string;
+                };
+                startDate: {
+                    $ref: string;
+                };
+                endDate: {
+                    anyOf: ({
+                        $ref: string;
+                        type?: undefined;
+                    } | {
+                        type: string;
+                        $ref?: undefined;
+                    })[];
+                };
+                highlighted: {
+                    type: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        Skill: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                id: {
+                    $ref: string;
+                };
+                label: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+                category: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                order: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        Contact: {
+            type: string;
+            additionalProperties: boolean;
+            properties: {
+                email: {
+                    $ref: string;
+                };
+                showEmail: {
+                    type: string;
+                    default: boolean;
+                };
+                formUrl: {
+                    $ref: string;
+                };
+            };
+        };
+        Settings: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                defaultLocale: {
+                    $ref: string;
+                };
+                fallbackLocale: {
+                    $ref: string;
+                };
+                availableLocales: {
+                    type: string;
+                    minItems: number;
+                    maxItems: number;
+                    uniqueItems: boolean;
+                    items: {
+                        $ref: string;
+                    };
+                };
+                theme: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                showPoweredBy: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                enableJsonLd: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                enableApi: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+                enableAnalytics: {
+                    type: string;
+                    default: boolean;
+                    description: string;
+                };
+            };
+        };
+        Meta: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                createdAt: {
+                    $ref: string;
+                };
+                updatedAt: {
+                    $ref: string;
+                };
+                generator: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                contentLicense: {
+                    $ref: string;
+                };
+            };
+        };
+        ContentLicense: {
+            type: string;
+            additionalProperties: boolean;
+            required: string[];
+            properties: {
+                spdxId: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+                url: {
+                    $ref: string;
+                };
+                attribution: {
+                    type: string;
+                    additionalProperties: boolean;
+                    properties: {
+                        name: {
+                            type: string;
+                            minLength: number;
+                            maxLength: number;
+                        };
+                        url: {
+                            $ref: string;
+                        };
+                    };
+                };
+                rights: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                    description: string;
+                };
+            };
+        };
+    };
+};
+type Schema = typeof schemaJson;
+
+/**
+ * TypeScript types for takuhon profile data.
+ *
+ * These mirror the canonical contract defined in `takuhon.schema.json`. The
+ * published shape is sanity-checked at commit 1 by `__tests__/schema.test.ts`
+ * (top-level keys, `$defs`, required fields, hybrid `additionalProperties`
+ * splits, Spec §6 invariants) and by `__tests__/example.test.ts` (the bundled
+ * fixture is assigned to `Takuhon` via a boundary cast, and per-Spec invariants
+ * are asserted at runtime). Those tests catch the kind of drift that changes
+ * the published shape, but they do not enforce field-by-field parity between
+ * JSON Schema `properties` and TypeScript members — that stronger guarantee
+ * arrives with the Ajv-backed validator in commit 2.
+ *
+ * When the schema changes, update these types accordingly and add a migration
+ * entry under `src/migrations/` for the next minor version.
+ *
+ * Public surface scope (hybrid `additionalProperties` strategy):
+ *
+ * - **Closed** in the schema (no forward-compatible extras): the document
+ *   root, `ContentLicense`, and every `Link` variant.
+ * - **Open** in the schema (`additionalProperties: true`): `Profile`,
+ *   `Settings`, `Meta`, `Career`, `Project`, `Skill`, `Contact`, `Avatar`,
+ *   `Address`, and the locale-keyed map shapes `LocalizedTitle` /
+ *   `LocalizedBody`.
+ *
+ * The public TypeScript surface intentionally omits an `[key: string]: unknown`
+ * index signature on the open containers. Declared properties stay accurately
+ * typed regardless of the choice — what such a signature would change is
+ * access to *undeclared* keys: it would let consumers spell arbitrary property
+ * names without an error and force `unknown` narrowing for those reads, and it
+ * would dilute IDE autocomplete on every dotted access. Keeping the types
+ * focused on the canonical members preserves that ergonomics. Consumers that
+ * need to attach custom fields should extend the relevant interface locally:
+ *
+ *     interface MyProfile extends Profile {
+ *       customField: string;
+ *     }
+ */
+/** BCP-47 language tag, e.g. 'en', 'ja', 'zh-Hant', 'pt-BR'. */
+type LocaleTag = string;
+/** ISO 3166-1 alpha-2 country code, uppercase, two letters (e.g. 'JP', 'PT'). */
+type Iso3166Alpha2 = string;
+/** Year-month in `YYYY-MM` format. */
+type YearMonth = string;
+/** ISO 8601 date-time string (e.g. `2026-05-12T12:34:56Z`). */
+type IsoDateTime = string;
+/** Identifier matching `^[a-z0-9][a-z0-9-]*$`, max 64 chars. */
+type Slug = string;
+/** Map from BCP-47 locale tag to a short localized string (≤200 chars). */
+type LocalizedTitle = Record<LocaleTag, string>;
+/** Map from BCP-47 locale tag to a body-length localized string (≤5000 chars). */
+type LocalizedBody = Record<LocaleTag, string>;
+type LinkType = 'website' | 'blog' | 'github' | 'gitlab' | 'linkedin' | 'x' | 'mastodon' | 'bluesky' | 'instagram' | 'youtube' | 'threads' | 'facebook' | 'email' | 'rss' | 'custom';
+interface Avatar {
+    url: string;
+    alt?: LocalizedTitle;
+}
+interface Address {
+    country?: Iso3166Alpha2;
+    region?: string;
+    locality?: LocalizedTitle;
+    display?: LocalizedTitle;
+}
+interface Profile {
+    displayName: LocalizedTitle;
+    tagline?: LocalizedTitle;
+    bio?: LocalizedBody;
+    avatar?: Avatar;
+    location?: Address;
+}
+interface LinkCommon {
+    id: Slug;
+    label?: LocalizedTitle;
+    url: string;
+    featured?: boolean;
+    order?: number;
+}
+/**
+ * A link of a built-in `type` (anything other than `'custom'`). The schema
+ * permits an optional `iconUrl` on these entries — for example, to override
+ * the default platform icon.
+ */
+interface LinkBuiltin extends LinkCommon {
+    type: Exclude<LinkType, 'custom'>;
+    iconUrl?: string;
+}
+/**
+ * A user-defined link (`type: 'custom'`). The schema requires `iconUrl` for
+ * these entries; modelling that constraint as a discriminated union here lets
+ * TypeScript reject `{ type: 'custom', ... }` literals that forget the icon
+ * before Ajv validation runs in commit 2.
+ */
+interface LinkCustom extends LinkCommon {
+    type: 'custom';
+    iconUrl: string;
+}
+/** A profile link. Discriminated on `type`; see `LinkBuiltin` / `LinkCustom`. */
+type Link = LinkBuiltin | LinkCustom;
+interface Career {
+    id: Slug;
+    organization: LocalizedTitle;
+    role: LocalizedTitle;
+    description?: LocalizedBody;
+    startDate: YearMonth;
+    /** `null` denotes an unbounded current position; omit if not applicable. */
+    endDate?: YearMonth | null;
+    isCurrent?: boolean;
+    url?: string;
+    location?: Address;
+    order?: number;
+}
+interface Project {
+    id: Slug;
+    title: LocalizedTitle;
+    description?: LocalizedBody;
+    url?: string;
+    tags?: string[];
+    relatedCareerId?: Slug;
+    startDate?: YearMonth;
+    endDate?: YearMonth | null;
+    highlighted?: boolean;
+    order?: number;
+}
+interface Skill {
+    id: Slug;
+    label: string;
+    /**
+     * Recommended values (extensible): programming, design, business, communication,
+     * language, music, art, sports, other.
+     */
+    category?: string;
+    order?: number;
+}
+interface Contact {
+    email?: string;
+    showEmail?: boolean;
+    formUrl?: string;
+}
+interface Settings {
+    defaultLocale: LocaleTag;
+    fallbackLocale?: LocaleTag;
+    availableLocales: LocaleTag[];
+    /** UI theme identifier. `'default'` is the built-in theme. */
+    theme?: string;
+    /** Display the 'Powered by takuhon' attribution on the rendered profile. */
+    showPoweredBy?: boolean;
+    /** Emit Schema.org JSON-LD on the rendered profile page. */
+    enableJsonLd?: boolean;
+    /** Expose the public read API endpoints. */
+    enableApi?: boolean;
+    /** Opt-in flag for first-party analytics. Default is false. */
+    enableAnalytics?: boolean;
+}
+interface ContentLicenseAttribution {
+    name?: string;
+    url?: string;
+}
+interface ContentLicense {
+    /** SPDX identifier (e.g. 'CC-BY-4.0', 'CC0-1.0') or 'Proprietary'. No default. */
+    spdxId: string;
+    url?: string;
+    attribution?: ContentLicenseAttribution;
+    rights?: string;
+}
+interface Meta {
+    createdAt?: IsoDateTime;
+    updatedAt?: IsoDateTime;
+    /** Tool that produced this document (e.g. `'Takuhon'`, `'create-takuhon@0.1.0'`). */
+    generator?: string;
+    contentLicense: ContentLicense;
+}
+/** A complete takuhon profile document. */
+interface Takuhon {
+    schemaVersion: string;
+    profile: Profile;
+    links: Link[];
+    careers: Career[];
+    projects: Project[];
+    skills: Skill[];
+    contact: Contact;
+    settings: Settings;
+    meta: Meta;
+}
+/**
+ * A {@link Takuhon} document that has been canonicalized by `normalize()`:
+ * arrays sorted by `order`, and empty localized-field entries removed.
+ *
+ * Structurally identical to {@link Takuhon}; the alias is a documentation hook
+ * for downstream consumers that want to express "must run through normalize
+ * first". A nominal branded form may replace this alias in a later phase if
+ * OSS adopters need the static guarantee.
+ */
+type NormalizedTakuhon = Takuhon;
+/**
+ * Address with localized fields collapsed to single strings — the shape
+ * `resolveLocale()` produces for `profile.location`.
+ */
+interface LocalizedAddress {
+    country?: Iso3166Alpha2;
+    region?: string;
+    locality?: string;
+    display?: string;
+}
+/** Avatar with `alt` collapsed to a single string. */
+interface LocalizedAvatar {
+    url: string;
+    alt?: string;
+}
+/** Profile with every localized field collapsed to a single string. */
+interface LocalizedProfile {
+    displayName: string;
+    tagline?: string;
+    bio?: string;
+    avatar?: LocalizedAvatar;
+    location?: LocalizedAddress;
+}
+interface LocalizedLinkCommon {
+    id: Slug;
+    label?: string;
+    url: string;
+    featured?: boolean;
+    order?: number;
+}
+interface LocalizedLinkBuiltin extends LocalizedLinkCommon {
+    type: Exclude<LinkType, 'custom'>;
+    iconUrl?: string;
+}
+interface LocalizedLinkCustom extends LocalizedLinkCommon {
+    type: 'custom';
+    iconUrl: string;
+}
+/** Link with `label` collapsed to a single string. */
+type LocalizedLink = LocalizedLinkBuiltin | LocalizedLinkCustom;
+/** Career with `organization`, `role`, `description` collapsed to single strings. */
+interface LocalizedCareer {
+    id: Slug;
+    organization: string;
+    role: string;
+    description?: string;
+    startDate: YearMonth;
+    endDate?: YearMonth | null;
+    isCurrent?: boolean;
+    url?: string;
+    location?: LocalizedAddress;
+    order?: number;
+}
+/** Project with `title`, `description` collapsed to single strings. */
+interface LocalizedProject {
+    id: Slug;
+    title: string;
+    description?: string;
+    url?: string;
+    tags?: string[];
+    relatedCareerId?: Slug;
+    startDate?: YearMonth;
+    endDate?: YearMonth | null;
+    highlighted?: boolean;
+    order?: number;
+}
+/**
+ * A takuhon document with every localized map flattened to a single string,
+ * plus a `resolvedLocale` field recording which tag was actually used as the
+ * head of the fallback chain. `resolveLocale()` returns this shape.
+ *
+ * `Skill`, `Contact`, `Settings`, and `Meta` carry no localized fields and
+ * pass through unchanged.
+ */
+interface LocalizedTakuhon {
+    schemaVersion: string;
+    profile: LocalizedProfile;
+    links: LocalizedLink[];
+    careers: LocalizedCareer[];
+    projects: LocalizedProject[];
+    skills: Skill[];
+    contact: Contact;
+    settings: Settings;
+    meta: Meta;
+    /**
+     * The locale tag that was matched first by the fallback chain and used as
+     * the head of per-field resolution. Equals one of the candidates derived
+     * from the request arguments or `settings`; an empty string only when no
+     * candidate was usable (theoretical — `validate()` rejects such inputs).
+     */
+    resolvedLocale: LocaleTag;
+}
+
+/**
+ * Schema validation for takuhon profile documents.
+ *
+ * Compiles the canonical {@link import('../takuhon.schema.json')} once at module
+ * load and exposes a Result-style {@link validate} that returns either the
+ * narrowed {@link Takuhon} value or a list of structured {@link ValidationError}s.
+ * The validator is the canonical correctness boundary inside `@takuhon/core`:
+ * `normalize` (commit 3) and the API layer (commit 11+) both rely on this
+ * function to know the shape they are working with.
+ *
+ * Design notes:
+ * - Returns a discriminated union rather than throwing so callers (CLI,
+ *   normalize, RFC 7807 Problem Details adapters) can route errors however they
+ *   like without paying for stack capture on every failure.
+ * - Errors carry the RFC 6901 JSON Pointer of the offending value plus the
+ *   failing Ajv keyword, so consumers can render messages or look up the
+ *   relevant Spec section without leaking Ajv-specific types.
+ * - The Ajv 2020 build is used because the schema declares
+ *   `$schema: "https://json-schema.org/draft/2020-12/schema"`.
+ */
+
+/**
+ * Schema versions this build of `@takuhon/core` accepts directly.
+ *
+ * The migration registry (Phase 1 commit 6+) will translate older `schemaVersion`
+ * values into the current one before validation runs, so this list reflects the
+ * versions whose JSON Schema this package literally bundles, not the full
+ * support window seen by end users.
+ */
+declare const SUPPORTED_SCHEMA_VERSIONS: readonly ["0.1.0"];
+/**
+ * A single validation failure.
+ *
+ * The shape is intentionally schema-agnostic: an API layer can adapt it into an
+ * RFC 7807 Problem Details payload, a CLI can render the message, and a future
+ * spec-section lookup table can join on {@link pointer} to surface
+ * documentation references. A `specSection` field will be added in a later
+ * commit; this minimal surface is what commit 2 ships.
+ */
+interface ValidationError {
+    /** RFC 6901 JSON Pointer to the offending value, e.g. `"/links/4/iconUrl"`. */
+    pointer: string;
+    /** Human-readable failure description (sourced from Ajv when available). */
+    message: string;
+    /**
+     * The schema keyword that failed: `'required'`, `'enum'`, `'pattern'`,
+     * `'additionalProperties'`, `'format'`, `'maxItems'`, `'maxLength'`, etc.
+     * The value `'schemaVersion'` is reserved for documents whose
+     * `schemaVersion` lies outside {@link SUPPORTED_SCHEMA_VERSIONS}.
+     */
+    keyword: string;
+    /** JSON Pointer into the schema for the failing rule, e.g. `"#/$defs/Link/required"`. */
+    schemaPointer?: string;
+}
+/** Result of {@link validate}. Narrow on `ok` to access `data` or `errors`. */
+type ValidationResult = {
+    ok: true;
+    data: Takuhon;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+/**
+ * Validate an arbitrary value against the bundled takuhon schema.
+ *
+ * @param data unknown JSON-like value (typically parsed from a `takuhon.json` file)
+ * @returns A discriminated result. On success `data` is narrowed to {@link Takuhon};
+ *          on failure `errors` is a non-empty list of {@link ValidationError}s.
+ */
+declare function validate(data: unknown): ValidationResult;
+
+/**
+ * Canonicalize a {@link Takuhon} document into the form downstream consumers
+ * (`@takuhon/api`, `@takuhon/ui`, `@takuhon/jsonld`) can rely on without
+ * re-checking shape invariants.
+ *
+ * Two transformations only:
+ * - **Empty-entry cleanup** on every localized field (`LocalizedTitle` /
+ *   `LocalizedBody`): entries whose string value is empty or whitespace-only
+ *   are removed so that locale fallback works field-by-field. When the
+ *   cleanup leaves an optional localized map empty, the map itself is
+ *   removed (the schema requires `minProperties: 1`).
+ * - **Stable sort by `order`** on every list field (`links`, `careers`,
+ *   `projects`, `skills`). Items without an `order` move to the end while
+ *   preserving their original relative position (ES2019 stable sort).
+ *
+ * Design notes:
+ * - The input is deep-cloned via `structuredClone`; the original is never
+ *   mutated. Callers may safely keep a reference to the value they passed in.
+ * - `normalize` does *not* canonicalize BCP-47 tag casing nor trim string
+ *   content. The first is covered by the schema's `propertyNames` pattern and
+ *   `resolveLocale`'s case-insensitive lookup; the second would silently rewrite
+ *   author input and is out of scope for Phase 1.
+ * - `normalize(normalize(x))` deep-equals `normalize(x)` (idempotent), and the
+ *   output re-validates against `takuhon.schema.json`. Both invariants are
+ *   enforced by the unit tests.
+ */
+
+/**
+ * Return a normalized copy of `data`.
+ *
+ * @param data A takuhon document that has already passed {@link validate}.
+ * @returns A new {@link NormalizedTakuhon} with localized empties dropped and
+ *          list fields sorted by `order`.
+ */
+declare function normalize(data: Takuhon): NormalizedTakuhon;
+
+/**
+ * Reduce a multi-locale {@link Takuhon} document to a single requested locale.
+ *
+ * Builds a flat candidate chain from the function arguments and `data.settings`,
+ * expanding each entry's regional subtag (e.g. `'en-US' → ['en-US', 'en']`),
+ * deduplicating case-insensitively, then walks the chain **per field**. The
+ * first candidate whose value is non-blank wins for that field; an empty entry
+ * (`""` / whitespace-only) falls through to the next candidate just like a
+ * missing entry. This matches the spec semantics in [api.md §3.4] where empty
+ * values are equivalent to absence.
+ *
+ * Design notes:
+ * - Function arguments (`locale`, `fallbackLocale`) take precedence over
+ *   `settings.*`, in line with the spec's 7-tier list: HTTP-derived locales
+ *   (#1-#4) are resolved upstream by `@takuhon/api` and arrive here as
+ *   `locale` / `fallbackLocale`; `settings.defaultLocale` (#5),
+ *   `settings.fallbackLocale` (#6), and `settings.availableLocales[0]` (#7)
+ *   fill the tail.
+ * - Invalid tags (`'zz_invalid'`, `'_'`, etc.) are silently dropped rather
+ *   than throwing. Resolution is best-effort: throwing on a malformed
+ *   `?lang=` query would push error handling responsibilities back into the
+ *   API layer for a recoverable case.
+ * - A final rescue step appends every `availableLocales` entry so a request
+ *   with no matching candidate still produces a populated document. If even
+ *   that fails (only possible for hand-crafted inputs that bypassed
+ *   `validate`), required strings fall back to `''` and the caller's tests
+ *   catch the document-level regression.
+ * - `resolvedLocale` records the tag that produced `profile.displayName`,
+ *   which is the field most consumers expose as the canonical locale of the
+ *   response (e.g. `meta.locale` in API responses, `<html lang>` in UI).
+ */
+
+/**
+ * Resolve a takuhon document to a single locale.
+ *
+ * @param data    A takuhon document (validated; ideally normalized first).
+ * @param locale  Caller-resolved request locale (e.g. from `?lang=` or
+ *                `Accept-Language`). Invalid tags are ignored.
+ * @param fallbackLocale Caller-supplied secondary candidate when `locale`
+ *                misses. Invalid tags are ignored.
+ */
+declare function resolveLocale(data: Takuhon, locale?: string, fallbackLocale?: string): LocalizedTakuhon;
+
+/**
+ * Generate Schema.org JSON-LD from a {@link LocalizedTakuhon} document.
+ *
+ * Emits a `ProfilePage` whose `mainEntity` is the `Person` described by the
+ * input. Mapping rules follow the published schema.org mapping spec; the
+ * relevant invariants are exercised by the unit tests.
+ *
+ * Design notes:
+ * - Input is the output of `resolveLocale()`, so every localized field is
+ *   already a single string. No locale fallback happens here.
+ * - All optional keys are omitted (not set to `null` / `undefined`) when their
+ *   source value is absent or empty, so consumers can shallow-merge or
+ *   `JSON.stringify` the result without post-processing.
+ * - The canonical URL surfaced as `ProfilePage.url`, `Person.@id`, and
+ *   `Person.url` is derived from a single `links[]` entry: `type: 'website'`
+ *   with `featured: true`. The first match wins (stable after `normalize()`).
+ *   When no such link exists the three URL-bearing keys are omitted entirely;
+ *   no placeholder is fabricated.
+ * - `profile.tagline` is intentionally not surfaced. `description` carries
+ *   `profile.bio` only, matching the spec exemplar. Phase 2 may revisit.
+ * - `contact.email` is surfaced only when `contact.showEmail === true`
+ *   (privacy by default).
+ * - URLs pass through verbatim. Relative paths in the input remain relative
+ *   in the output; absolutization is the API/UI layer's responsibility.
+ * - Field insertion order on each emitted object is fixed so
+ *   `JSON.stringify(result)` is deterministic for a given input.
+ */
+
+/**
+ * Build the `Person` JSON-LD object for `data`.
+ *
+ * @param data A locale-resolved takuhon document.
+ * @returns A Schema.org `Person` object. `@context` is included so the
+ *          returned object is valid as a standalone JSON-LD document.
+ */
+declare function generatePersonJsonLd(data: LocalizedTakuhon): object;
+/**
+ * Build the `ProfilePage` JSON-LD object for `data`, with `Person` inlined
+ * as `mainEntity`.
+ *
+ * @param data A locale-resolved takuhon document.
+ */
+declare function generateProfilePageJsonLd(data: LocalizedTakuhon): object;
+/**
+ * Build the array of JSON-LD objects to embed in a single
+ * `<script type="application/ld+json">` tag.
+ *
+ * Phase 1 emits a single-element array containing the `ProfilePage`; the
+ * `Person` is inlined there as `mainEntity`. The array shape leaves room
+ * for later additions (e.g. `WebSite`) without changing the public surface.
+ */
+declare function generateJsonLd(data: LocalizedTakuhon): object[];
+
+/**
+ * Export and import for takuhon profile documents.
+ *
+ * {@link exportTakuhon} serialises a {@link Takuhon} document into a transport
+ * form ({@link ExportedTakuhon}) that can be persisted to a file, an API
+ * response, or any other byte-oriented sink. {@link importTakuhon} is the
+ * inverse: it validates the input and returns a {@link Takuhon}.
+ *
+ * Scope of these helpers (deliberately narrow):
+ * - Pure, in-memory data transforms — no I/O, no storage adapter coupling.
+ * - {@link importTakuhon} **does not** auto-migrate older `schemaVersion`
+ *   values. Cross-version handling belongs to the CLI / API layer, which
+ *   composes `importTakuhon` + {@link migrateTakuhon} + storage adapters as
+ *   spelled out in operational-lifecycle §5.3.
+ * - Round-trip equivalence (operational-lifecycle §5.1) is preserved up to
+ *   the documented `meta.updatedAt` exception.
+ *
+ * Asset embedding (Base64) and backup creation are out of scope here; both
+ * are the storage / API layer's responsibility.
+ */
+
+/**
+ * Structural alias of {@link Takuhon}: the transport form is the document
+ * itself. A wrapping envelope (e.g. `{ format, version, data, hash }`) is
+ * intentionally avoided in Phase 1 — adding one later would be a breaking
+ * change to the `GET /api/export` response shape and would require a major
+ * version bump of `@takuhon/core`.
+ */
+type ExportedTakuhon = Takuhon;
+/** Options for {@link exportTakuhon}. */
+interface ExportOptions {
+    /**
+     * When `true` (default), `meta.updatedAt` is overwritten with the current
+     * ISO-8601 timestamp. Set to `false` for byte-for-byte reproducible
+     * exports (e.g. roundtrip tests).
+     *
+     * Round-trip equivalence per operational-lifecycle §5.1 explicitly lists
+     * `meta.updatedAt` as the allowed exception.
+     */
+    updateTimestamp?: boolean;
+}
+/**
+ * Thrown by {@link importTakuhon} when the input fails schema validation
+ * (including an unsupported `schemaVersion`). The `errors` field carries
+ * the same {@link ValidationError} list that `validate()` would have
+ * returned, so the API layer can map them onto RFC 7807.
+ */
+declare class ImportError extends Error {
+    readonly errors?: ValidationError[];
+    constructor(message: string, options?: {
+        cause?: unknown;
+        errors?: ValidationError[];
+    });
+}
+/**
+ * Serialise a {@link Takuhon} into its transport form. The input is
+ * deep-cloned via `JSON.parse(JSON.stringify(...))`; the original is never
+ * mutated.
+ */
+declare function exportTakuhon(data: Takuhon, options?: ExportOptions): ExportedTakuhon;
+/**
+ * Validate an {@link ExportedTakuhon} and return it as a {@link Takuhon}.
+ *
+ * On schema validation failure (including an unsupported `schemaVersion`)
+ * throws an {@link ImportError} with the structured `errors` attached. The
+ * input is not mutated. The return value is a deep clone, so subsequent
+ * caller mutations cannot reach back into the supplied document.
+ *
+ * Cross-version inputs (older `schemaVersion`) are out of scope: callers
+ * (CLI / API layer) should run {@link migrateTakuhon} before calling this.
+ */
+declare function importTakuhon(data: ExportedTakuhon): Takuhon;
+
+/**
+ * Forward migration entry point for takuhon documents.
+ *
+ * {@link migrateTakuhon} composes a chain of {@link Migration} entries from
+ * the registry (`./migrations`) and applies them in order. Phase 1 ships
+ * with an empty registry, so any non-identity migration currently throws
+ * {@link MigrationError}; the first concrete entry will land alongside
+ * the v0.2.0 schema bump.
+ *
+ * Scope (deliberately narrow, mirroring `export.ts`):
+ * - Pure data transform — no I/O, no backup creation, no storage write.
+ * - Backup-before-migrate (operational-lifecycle §3.1) is the storage /
+ *   API layer's responsibility; this function only transforms the
+ *   in-memory document.
+ * - Forward only (operational-lifecycle §2.4); downgrade is via restore.
+ */
+
+/**
+ * Thrown by {@link migrateTakuhon} when no forward chain connects the
+ * source `schemaVersion` to `targetVersion`. The message includes both
+ * versions so the API layer can surface an actionable RFC 7807 problem.
+ */
+declare class MigrationError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Migrate a takuhon document forward to `targetVersion`. Returns a deep
+ * clone; the input is never mutated, even when a migration throws.
+ *
+ * @throws {MigrationError} when no forward chain exists from
+ *         `data.schemaVersion` to `targetVersion`.
+ */
+declare function migrateTakuhon(data: Takuhon, targetVersion: string): Takuhon;
+
+/**
+ * Forward migration registry for `@takuhon/core`.
+ *
+ * Each migration is a pure function from a takuhon document at version `from`
+ * to one at version `to`. The registry is consulted by {@link migrateTakuhon}
+ * to build a chain when the requested target is more than one step away
+ * (`0.1.0 → 0.3.0` is composed of `0.1.0→0.2.0` and `0.2.0→0.3.0`).
+ *
+ * Authoring conventions:
+ * - File name: `vX.Y.Z-to-vA.B.C.ts`
+ * - Pure function: must not mutate input, must not perform I/O
+ * - Forward only: downgrades are not provided; recovery is via the backup
+ *   restore path (operational-lifecycle §4)
+ * - Each entry ships with a unit test: sample input/output, idempotency
+ *   when applicable, and schema-pass against the target version's schema
+ *
+ * The chain-building algorithm lives in `_chain.ts` and is intentionally
+ * not re-exported from `@takuhon/core` — it is an implementation detail of
+ * {@link migrateTakuhon}.
+ */
+
+/**
+ * A forward migration entry. `from` and `to` are semver strings matching
+ * the `schemaVersion` field of the input and output documents. `migrate`
+ * is pure: it must not mutate `data`.
+ */
+interface Migration<From, To> {
+    from: string;
+    to: string;
+    migrate(data: From): To;
+}
+/**
+ * Forward migrations bundled with this build of `@takuhon/core`. Empty in
+ * Phase 1; the first entry will land alongside the v0.2.0 schema bump.
+ */
+declare const migrations: readonly Migration<Takuhon, Takuhon>[];
+
+/**
+ * Persistence contracts for takuhon profile documents and binary assets.
+ *
+ * Adapters (KV / R2 / filesystem / SQLite / …) implement these interfaces to
+ * plug into `@takuhon/api`. All methods are async; failures surface as
+ * exceptions in the {@link StorageError} family so the API layer can map them
+ * onto RFC 7807 problem details.
+ *
+ * Design notes:
+ * - `version` is an opaque ETag-like token (UUID, hash, monotonic counter —
+ *   the adapter chooses). It powers HTTP `If-Match` style optimistic locking
+ *   and is unrelated to {@link Takuhon.schemaVersion}, which describes the
+ *   document's data-model version.
+ * - `getProfile()` returns a raw {@link Takuhon}, not a normalized or
+ *   locale-resolved one. Normalization and locale resolution belong to the
+ *   API / render layer; storage only persists.
+ * - `saveProfile(data, ifMatch?)` rejects with {@link ConflictError} when
+ *   `ifMatch` is supplied and does not equal the current stored version.
+ *   When `ifMatch` is omitted, the adapter's policy decides whether to
+ *   overwrite unconditionally; per-implementation docs spell this out.
+ * - `TakuhonAssetStorage` is intentionally a separate interface so deployments
+ *   that don't host user-uploaded media (e.g. static export) can omit it.
+ * - The naming standardises on the lowercase "Takuhon" word (cf.
+ *   {@link Takuhon}, {@link LocalizedTakuhon}, `normalize`, `validate`) even
+ *   where upstream documents write "Takuhon".
+ */
+
+/**
+ * Persistence contract for the single profile document of a takuhon instance.
+ *
+ * Implementations: Cloudflare KV (Phase 3), filesystem (Phase 3+), in-memory
+ * test doubles, and future SQL adapters.
+ */
+interface TakuhonStorage {
+    /**
+     * Read the current profile document and its opaque version token.
+     *
+     * @throws {NotFoundError} when no profile has been saved yet.
+     */
+    getProfile(): Promise<{
+        data: Takuhon;
+        version: string;
+    }>;
+    /**
+     * Replace the profile document. The returned `version` is the new opaque
+     * token to supply as the next `ifMatch`.
+     *
+     * @param data    the document to persist (raw, not normalized)
+     * @param ifMatch when set, the adapter rejects the write unless the
+     *                current stored version equals this token
+     * @throws {ConflictError} when `ifMatch` is supplied and does not equal
+     *                         the current stored version
+     */
+    saveProfile(data: Takuhon, ifMatch?: string): Promise<{
+        version: string;
+    }>;
+    /**
+     * Remove the profile document. Idempotent: no error when nothing is stored.
+     */
+    deleteProfile(): Promise<void>;
+}
+/**
+ * Metadata for a stored binary asset, returned by {@link TakuhonAssetStorage}.
+ *
+ * `url` is the relative path used inside the document (`/assets/...`);
+ * `publicUrl` is the absolute URL a browser can fetch. The two are kept
+ * distinct because adapters may serve assets from a different host than the
+ * profile (e.g. Cloudflare R2 + custom CDN).
+ */
+interface AssetRecord {
+    id: string;
+    url: string;
+    publicUrl: string;
+    mimeType: string;
+    size: number;
+    width?: number;
+    height?: number;
+    /** ISO-8601 timestamp. */
+    createdAt?: string;
+}
+/**
+ * Caller hints for {@link TakuhonAssetStorage.putAsset}. Both fields are
+ * optional; when omitted, the adapter falls back to the `File` / `Blob`
+ * metadata. Adapters are responsible for magic-byte verification, EXIF
+ * stripping, and dimension limits — callers must not pre-process.
+ */
+interface AssetOptions {
+    filename?: string;
+    contentType?: string;
+}
+/**
+ * Persistence contract for binary assets (avatars, project images, …).
+ *
+ * `listAssets()` is unbounded by design for the MVP; later phases may
+ * introduce paginated semantics with a different return shape. `getPublicUrl()`
+ * takes only an `assetId` today; a future options object (e.g. `expiresIn`
+ * for signed URLs) would be added in a backward-compatible way.
+ */
+interface TakuhonAssetStorage {
+    putAsset(file: File | Blob, options?: AssetOptions): Promise<AssetRecord>;
+    /** @throws {NotFoundError} when no asset exists for `assetId`. */
+    getPublicUrl(assetId: string): Promise<string>;
+    /** Idempotent: no error when the asset is already absent. */
+    deleteAsset(assetId: string): Promise<void>;
+    listAssets(): Promise<AssetRecord[]>;
+}
+/**
+ * Base class for errors thrown by storage adapters. Catch this to handle
+ * any storage-layer failure uniformly; check `instanceof` of a subclass
+ * (e.g. {@link NotFoundError}, {@link ConflictError}) to discriminate.
+ */
+declare class StorageError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a requested resource (profile or asset) does not exist. */
+declare class NotFoundError extends StorageError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when an optimistic-locking precondition fails: the caller supplied
+ * an `ifMatch` token that does not equal the current stored version.
+ *
+ * `currentVersion` (when set) carries the actual current version so the
+ * caller can decide between refetch-and-retry and surfacing a 409 to the
+ * end user without an extra round trip.
+ */
+declare class ConflictError extends StorageError {
+    readonly currentVersion?: string;
+    constructor(message: string, options?: {
+        currentVersion?: string;
+        cause?: unknown;
+    });
+}
+
+/**
+ * @takuhon/core — canonical JSON Schema, hand-written TypeScript types,
+ * Ajv-backed validation, document normalization, and locale resolution for
+ * takuhon profile data.
+ *
+ * Public surface (Phase 1):
+ * - {@link schema}: the JSON Schema 2020-12 contract bundled with this build.
+ * - {@link SCHEMA_VERSION}: the version of that schema (matches the `$id`).
+ * - {@link validate} / {@link ValidationResult} / {@link ValidationError} /
+ *   {@link SUPPORTED_SCHEMA_VERSIONS}: Result-style validator backed by Ajv.
+ * - {@link normalize} / {@link NormalizedTakuhon}: canonicalize a validated
+ *   document (sort lists by `order`, drop blank localized entries).
+ * - {@link resolveLocale} / {@link LocalizedTakuhon}: collapse a multi-locale
+ *   document to a single requested locale with BCP-47 regional fallback.
+ * - {@link generateJsonLd} / {@link generatePersonJsonLd} /
+ *   {@link generateProfilePageJsonLd}: emit Schema.org JSON-LD
+ *   (`ProfilePage` wrapping `Person`) from a locale-resolved document.
+ * - {@link TakuhonStorage} / {@link TakuhonAssetStorage}: persistence contracts
+ *   for adapters (KV / R2 / filesystem / SQLite / …), with the
+ *   {@link StorageError} / {@link NotFoundError} / {@link ConflictError}
+ *   exception family for optimistic-locking and not-found signalling.
+ * - {@link exportTakuhon} / {@link importTakuhon} / {@link ExportOptions} /
+ *   {@link ExportedTakuhon} / {@link ImportError}: roundtrip-stable
+ *   serialisation for transport (file, API response, …).
+ * - {@link migrateTakuhon} / {@link Migration} / {@link migrations} /
+ *   {@link MigrationError}: forward-only migration registry. Empty in
+ *   Phase 1; first entry lands with the v0.2.0 schema bump.
+ * - Domain types: {@link Takuhon} and its constituent shapes (`Profile`,
+ *   `Settings`, `Career`, `Project`, `Link` discriminated union, etc.).
+ */
+
+/**
+ * Version of the takuhon schema bundled with this build of `@takuhon/core`.
+ * A takuhon profile document's `schemaVersion` field must be migrate-compatible
+ * with this version. See operational-lifecycle docs for the migration policy.
+ */
+declare const SCHEMA_VERSION = "0.1.0";
+
+export { type Address, type AssetOptions, type AssetRecord, type Avatar, type Career, ConflictError, type Contact, type ContentLicense, type ContentLicenseAttribution, type ExportOptions, type ExportedTakuhon, ImportError, type Iso3166Alpha2, type IsoDateTime, type Link, type LinkBuiltin, type LinkCustom, type LinkType, type LocaleTag, type LocalizedAddress, type LocalizedAvatar, type LocalizedBody, type LocalizedCareer, type LocalizedLink, type LocalizedLinkBuiltin, type LocalizedLinkCustom, type LocalizedProfile, type LocalizedProject, type LocalizedTakuhon, type LocalizedTitle, type Meta, type Migration, MigrationError, type NormalizedTakuhon, NotFoundError, type Profile, type Project, SCHEMA_VERSION, SUPPORTED_SCHEMA_VERSIONS, type Schema, type Settings, type Skill, type Slug, StorageError, type Takuhon, type TakuhonAssetStorage, type TakuhonStorage, type ValidationError, type ValidationResult, type YearMonth, exportTakuhon, generateJsonLd, generatePersonJsonLd, generateProfilePageJsonLd, importTakuhon, migrateTakuhon, migrations, normalize, resolveLocale, schema, validate };