videobook-engine 5.3.2 → 5.4.0

package/dist/tag-transfer.js

@@ -0,0 +1,341 @@
+/**
+ * Tag history reads and snapshot transfer.
+ *
+ * Two jobs the consumer cannot do for itself without touching catalogs
+ * directly: reading an artifact's tag state as some revision recorded it,
+ * and moving tag state between artifacts — including between separate
+ * engines — as validated data rather than raw rows.
+ *
+ * Transfer never trusts the source's keys or references. Labels are
+ * re-normalized into destination-local identities, an entity reference
+ * survives only if that entity exists in the destination, and automatic
+ * evidence crosses only when the destination artifact actually carries the
+ * bytes that were analyzed. A modified or generated derivative therefore
+ * cannot inherit automatic tags describing content it does not have.
+ */
+import { ok } from "./engine-types.js";
+import { resultOf, syncResultOf } from "./context.js";
+import { EngineFault } from "./store.js";
+import { normalizeAutomaticTags } from "./tag-validation.js";
+import { automaticTagsMatch, compareTags, snapshotMatches, storedSnapshot, } from "./tag-rows.js";
+import { MANUAL_TAGS_PER_ARTIFACT_MAX, TAG_DISMISSALS_PER_ARTIFACT_MAX, normalizeTagList, tagIdentity, } from "./tag-values.js";
+/** Schema version that introduced the tag tables. */
+const TAG_SCHEMA_VERSION = 25;
+export const TAG_SNAPSHOT_VERSION = 1;
+export function createTagTransferApi(context, tagState) {
+    return {
+        readAtRevision: (artifactId, revision) => syncResultOf(() => readAtRevision(context, artifactId, revision)),
+        export: (artifactId) => syncResultOf(() => exportTags(context, tagState, artifactId)),
+        import: (artifactId, snapshot) => importTags(context, tagState, artifactId, snapshot),
+    };
+}
+// -------------------------------------------------------------- history
+/**
+ * Tag state as `revision` recorded it. A revision written before the tag
+ * schema existed has no tag state at all, which is an empty snapshot
+ * rather than an error.
+ */
+function readAtRevision(context, artifactId, revision) {
+    const db = context.store.db;
+    const artifact = db
+        .prepare("SELECT artifact_id FROM dolt_at_artifacts(?) WHERE artifact_id=? LIMIT 1")
+        .get(revision, artifactId);
+    if (!artifact) {
+        throw new EngineFault({
+            code: "NOT_FOUND",
+            message: `Artifact not found: ${artifactId} at ${revision}`,
+        });
+    }
+    const schema = db
+        .prepare("SELECT version FROM dolt_at_engine_schema(?) WHERE singleton=1")
+        .get(revision);
+    if ((schema?.version ?? 0) < TAG_SCHEMA_VERSION) {
+        return emptyState(artifactId);
+    }
+    const tags = db
+        .prepare(`SELECT origin, facet, tag_key, label, entity_id, created_at
+       FROM dolt_at_artifact_tags(?)
+       WHERE artifact_id=?
+       ORDER BY facet, tag_key`)
+        .all(revision, artifactId);
+    const dismissals = db
+        .prepare(`SELECT facet, tag_key, label, dismissed_at
+       FROM dolt_at_artifact_tag_dismissals(?)
+       WHERE artifact_id=?
+       ORDER BY facet, tag_key`)
+        .all(revision, artifactId);
+    const snapshot = db
+        .prepare(`SELECT artifact_id, source_hash, generator, model, extractor_version,
+              tag_count, generation, analyzed_at
+       FROM dolt_at_artifact_tag_snapshots(?)
+       WHERE artifact_id=?`)
+        .get(revision, artifactId);
+    const hashes = new Set(db
+        .prepare("SELECT object_hash FROM dolt_at_artifact_files(?) WHERE artifact_id=?")
+        .all(revision, artifactId).map((row) => row.object_hash));
+    const stale = snapshot !== undefined && !hashes.has(snapshot.source_hash);
+    const dismissed = new Set(dismissals.map((row) => tagIdentity(row.facet, row.tag_key)));
+    const manual = tags
+        .filter((row) => row.origin === "manual")
+        .map((row) => historicalTag(row));
+    const automatic = tags
+        .filter((row) => row.origin === "automatic")
+        .map((row) => ({
+        ...historicalTag(row),
+        dismissed: dismissed.has(tagIdentity(row.facet, row.tag_key)),
+        stale,
+    }));
+    const claimed = new Set(manual.map((tag) => tagIdentity(tag.facet, tag.key)));
+    const effective = [...manual];
+    for (const tag of automatic) {
+        if (tag.dismissed || tag.stale)
+            continue;
+        const identity = tagIdentity(tag.facet, tag.key);
+        if (claimed.has(identity))
+            continue;
+        claimed.add(identity);
+        effective.push({
+            facet: tag.facet,
+            key: tag.key,
+            label: tag.label,
+            origin: tag.origin,
+            ...(tag.entityId ? { entityId: tag.entityId } : {}),
+            createdAt: tag.createdAt,
+        });
+    }
+    effective.sort(compareTags);
+    return {
+        artifactId,
+        effective,
+        manual,
+        automatic,
+        dismissed: dismissals.map((row) => ({
+            facet: row.facet,
+            key: row.tag_key,
+            label: row.label,
+            dismissedAt: row.dismissed_at,
+        })),
+        ...(snapshot
+            ? {
+                snapshot: {
+                    artifactId,
+                    sourceHash: snapshot.source_hash,
+                    generator: snapshot.generator,
+                    ...(snapshot.model === null ? {} : { model: snapshot.model }),
+                    extractorVersion: snapshot.extractor_version,
+                    tagCount: snapshot.tag_count,
+                    generation: snapshot.generation,
+                    analyzedAt: snapshot.analyzed_at,
+                    stale,
+                },
+            }
+            : {}),
+    };
+}
+function historicalTag(row) {
+    return {
+        facet: row.facet,
+        key: row.tag_key,
+        label: row.label,
+        origin: row.origin,
+        ...(row.entity_id ? { entityId: row.entity_id } : {}),
+        createdAt: row.created_at,
+    };
+}
+function emptyState(artifactId) {
+    return {
+        artifactId,
+        effective: [],
+        manual: [],
+        automatic: [],
+        dismissed: [],
+    };
+}
+// ------------------------------------------------------------- transfer
+/**
+ * A portable copy of an artifact's tag state. Automatic evidence is
+ * included only while it is still valid for the source, so a stale
+ * snapshot is never handed on.
+ */
+function exportTags(context, tagState, artifactReference) {
+    const artifact = context.artifactRow(artifactReference);
+    const state = tagState(artifact.artifact_id);
+    const automatic = state.snapshot;
+    return {
+        version: TAG_SNAPSHOT_VERSION,
+        artifactId: artifact.artifact_id,
+        manual: state.manual.map((tag) => ({
+            facet: tag.facet,
+            label: tag.label,
+            ...(tag.entityId ? { entityId: tag.entityId } : {}),
+        })),
+        dismissed: state.dismissed.map((tag) => ({
+            facet: tag.facet,
+            label: tag.label,
+        })),
+        ...(automatic && !automatic.stale
+            ? {
+                automatic: {
+                    sourceHash: automatic.sourceHash,
+                    generator: automatic.generator,
+                    ...(automatic.model ? { model: automatic.model } : {}),
+                    extractorVersion: automatic.extractorVersion,
+                    analyzedAt: automatic.analyzedAt,
+                    tags: state.automatic.map((tag) => ({
+                        facet: tag.facet,
+                        label: tag.label,
+                        ...(tag.entityId ? { entityId: tag.entityId } : {}),
+                    })),
+                },
+            }
+            : {}),
+    };
+}
+async function importTags(context, tagState, artifactReference, snapshot) {
+    return resultOf(() => context.store.semanticOperation((commit) => {
+        const artifact = context.artifactRow(artifactReference);
+        const artifactId = artifact.artifact_id;
+        if (snapshot?.version !== TAG_SNAPSHOT_VERSION) {
+            throw new Error(`Tag snapshot version must be ${TAG_SNAPSHOT_VERSION}; received ${snapshot?.version ?? "none"}`);
+        }
+        const manual = localTags(context, normalizeTagList(snapshot.manual ?? []));
+        const dismissed = normalizeTagList(snapshot.dismissed ?? []);
+        const candidate = importableAutomatic(context, artifactId, snapshot);
+        // Importing the same evidence a second time is not a new analysis.
+        const current = storedSnapshot(context.store.db, artifactId);
+        const automatic = candidate &&
+            snapshotMatches(current, candidate) &&
+            automaticTagsMatch(context.store.db, artifactId, candidate.tags)
+            ? undefined
+            : candidate;
+        const existingManual = identitySet(context, artifactId, "SELECT facet, tag_key FROM artifact_tags WHERE artifact_id=? AND origin='manual'");
+        const existingDismissed = identitySet(context, artifactId, "SELECT facet, tag_key FROM artifact_tag_dismissals WHERE artifact_id=?");
+        const newManual = manual.filter((tag) => !existingManual.has(tagIdentity(tag.facet, tag.key)));
+        const newDismissed = dismissed.filter((tag) => !existingDismissed.has(tagIdentity(tag.facet, tag.key)));
+        assertCapacity(existingManual.size + newManual.length, MANUAL_TAGS_PER_ARTIFACT_MAX, `manual tags on ${artifactId}`);
+        assertCapacity(existingDismissed.size + newDismissed.length, TAG_DISMISSALS_PER_ARTIFACT_MAX, `dismissals on ${artifactId}`);
+        const result = {
+            importedManual: newManual.length,
+            importedDismissals: newDismissed.length,
+            importedAutomatic: automatic ? automatic.tags.length : 0,
+            skippedAutomatic: snapshot.automatic !== undefined && candidate === undefined,
+        };
+        if (newManual.length === 0 &&
+            newDismissed.length === 0 &&
+            automatic === undefined) {
+            return ok({ ...result, state: tagState(artifactId) });
+        }
+        const generation = current?.generation ?? 0;
+        const mutation = commit({
+            operation: "import_artifact_tags",
+            tables: [
+                "artifact_tags",
+                "artifact_tag_dismissals",
+                "artifact_tag_snapshots",
+            ],
+            artifactId,
+            details: {
+                artifactId,
+                sourceArtifactId: snapshot.artifactId,
+                manual: newManual.length,
+                dismissed: newDismissed.length,
+                automatic: automatic?.tags.length ?? 0,
+            },
+            writeSet: [`artifact-tags-import:${artifactId}`],
+        }, (_operationId, now) => {
+            const insertTag = context.store.db.prepare(`INSERT INTO artifact_tags(
+             artifact_id, origin, facet, tag_key, label, entity_id, created_at
+           ) VALUES (?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(artifact_id, origin, facet, tag_key) DO UPDATE SET
+             label=excluded.label,
+             entity_id=excluded.entity_id`);
+            for (const tag of newManual) {
+                insertTag.run(artifactId, "manual", tag.facet, tag.key, tag.label, tag.entityId ?? null, now);
+            }
+            const insertDismissal = context.store.db.prepare(`INSERT INTO artifact_tag_dismissals(
+             artifact_id, facet, tag_key, label, dismissed_at
+           ) VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(artifact_id, facet, tag_key) DO NOTHING`);
+            for (const tag of newDismissed) {
+                insertDismissal.run(artifactId, tag.facet, tag.key, tag.label, now);
+            }
+            if (!automatic)
+                return;
+            context.store.db
+                .prepare("DELETE FROM artifact_tags WHERE artifact_id=? AND origin='automatic'")
+                .run(artifactId);
+            for (const tag of automatic.tags) {
+                insertTag.run(artifactId, "automatic", tag.facet, tag.key, tag.label, tag.entityId ?? null, now);
+            }
+            context.store.db
+                .prepare(`INSERT INTO artifact_tag_snapshots(
+               artifact_id, source_hash, generator, model, extractor_version,
+               tag_count, generation, analyzed_at
+             ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+             ON CONFLICT(artifact_id) DO UPDATE SET
+               source_hash=excluded.source_hash,
+               generator=excluded.generator,
+               model=excluded.model,
+               extractor_version=excluded.extractor_version,
+               tag_count=excluded.tag_count,
+               generation=excluded.generation,
+               analyzed_at=excluded.analyzed_at`)
+                .run(artifactId, automatic.sourceHash, automatic.generator, automatic.model ?? null, automatic.extractorVersion, automatic.tags.length, generation + 1, automatic.analyzedAt);
+        });
+        return ok({ ...result, state: tagState(artifactId) }, mutation.revision);
+    }));
+}
+/**
+ * Automatic evidence transfers only to an artifact that carries the exact
+ * bytes it describes, which is what makes a hash-identical duplicate a
+ * legitimate destination and a derivative an illegitimate one.
+ */
+function importableAutomatic(context, artifactId, snapshot) {
+    const automatic = snapshot.automatic;
+    if (!automatic)
+        return undefined;
+    const normalized = normalizeAutomaticTags(automatic);
+    if (!Number.isSafeInteger(automatic.analyzedAt) || automatic.analyzedAt < 0) {
+        throw new Error("Automatic tag analyzedAt must be a nonnegative integer timestamp");
+    }
+    const present = context.store.db
+        .prepare("SELECT 1 AS present FROM artifact_files WHERE artifact_id=? AND object_hash=?")
+        .get(artifactId, normalized.sourceHash);
+    if (!present)
+        return undefined;
+    return {
+        ...normalized,
+        analyzedAt: automatic.analyzedAt,
+        tags: localTags(context, normalized.tags),
+    };
+}
+/**
+ * Re-points imported tags at destination-local identities: the label is
+ * re-normalized here, and a source entity reference survives only when the
+ * destination knows that entity.
+ */
+function localTags(context, tags) {
+    const resolve = context.store.db.prepare("SELECT 1 AS present FROM entities WHERE entity_id=?");
+    return tags.map((tag) => {
+        if (!tag.entityId || resolve.get(tag.entityId))
+            return tag;
+        const { entityId: _dropped, ...local } = tag;
+        return local;
+    });
+}
+function identitySet(context, artifactId, sql) {
+    const rows = context.store.db
+        .prepare(sql)
+        .all(artifactId);
+    return new Set(rows.map((row) => tagIdentity(row.facet, row.tag_key)));
+}
+function assertCapacity(total, limit, what) {
+    if (total <= limit)
+        return;
+    throw new EngineFault({
+        code: "RESOURCE_EXHAUSTED",
+        message: `Importing would leave ${total} ${what}; the limit is ${limit}`,
+        details: { requested: total, limit },
+    });
+}
+//# sourceMappingURL=tag-transfer.js.map

package/dist/tag-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-transfer.js","sourceRoot":"","sources":["../src/tag-transfer.ts"],"names":[],"mappings":"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"}

package/dist/tag-validation.d.ts

@@ -0,0 +1,15 @@
+import { type TagInput } from "./tag-values.js";
+export declare function normalizeAutomaticTags(input: {
+    sourceHash: string;
+    generator: string;
+    model?: string;
+    extractorVersion: string;
+    tags: readonly TagInput[];
+}): {
+    extractorVersion: string;
+    tags: import("./tag-values.js").NormalizedTag[];
+    model?: string | undefined;
+    sourceHash: string;
+    generator: string;
+};
+//# sourceMappingURL=tag-validation.d.ts.map

package/dist/tag-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validation.d.ts","sourceRoot":"","sources":["../src/tag-validation.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,iBAAiB,CAAC;AAEzB,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;CAC3B;;;;;;EAwBA"}

package/dist/tag-validation.js

@@ -0,0 +1,36 @@
+/** Shared validation for new analysis and portable automatic evidence. */
+import { EngineFault } from "./store.js";
+import { AUTOMATIC_TAGS_PER_SNAPSHOT_MAX, normalizeTagList, } from "./tag-values.js";
+export function normalizeAutomaticTags(input) {
+    const sourceHash = requiredText(input.sourceHash, "sourceHash").toLowerCase();
+    if (!/^[0-9a-f]{64}$/u.test(sourceHash)) {
+        throw new Error("Automatic tag sourceHash must be a hex sha256 content hash");
+    }
+    const generator = requiredText(input.generator, "generator");
+    const extractorVersion = requiredText(input.extractorVersion, "extractorVersion");
+    if (input.model !== undefined && typeof input.model !== "string") {
+        throw new Error("Automatic tag model must be a string");
+    }
+    const model = input.model?.trim();
+    if (!Array.isArray(input.tags))
+        throw new Error("Automatic tags must be an array");
+    const tags = normalizeTagList(input.tags);
+    if (tags.some((tag) => tag.facet === "custom")) {
+        throw new Error("Automatic tag facets must be people, places or editing; custom tags are manual");
+    }
+    if (tags.length > AUTOMATIC_TAGS_PER_SNAPSHOT_MAX) {
+        throw new EngineFault({
+            code: "RESOURCE_EXHAUSTED",
+            message: `An automatic snapshot carries at most ${AUTOMATIC_TAGS_PER_SNAPSHOT_MAX} tags; received ${tags.length}`,
+            details: { requested: tags.length, limit: AUTOMATIC_TAGS_PER_SNAPSHOT_MAX },
+        });
+    }
+    return { sourceHash, generator, ...(model ? { model } : {}), extractorVersion, tags };
+}
+function requiredText(value, field) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Automatic tag ${field} is required`);
+    }
+    return value.trim();
+}
+//# sourceMappingURL=tag-validation.js.map

package/dist/tag-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-validation.js","sourceRoot":"","sources":["../src/tag-validation.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,+BAA+B,EAC/B,gBAAgB,GAEjB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,UAAU,sBAAsB,CAAC,KAMtC;IACC,MAAM,UAAU,GAAG,YAAY,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC;IAC9E,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC7D,MAAM,gBAAgB,GAAG,YAAY,CAAC,KAAK,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;IAClF,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;IAClC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACnF,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;IACpG,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,+BAA+B,EAAE,CAAC;QAClD,MAAM,IAAI,WAAW,CAAC;YACpB,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,yCAAyC,+BAA+B,mBAAmB,IAAI,CAAC,MAAM,EAAE;YACjH,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,+BAA+B,EAAE;SAC5E,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;AACxF,CAAC;AAED,SAAS,YAAY,CAAC,KAAa,EAAE,KAAa;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,cAAc,CAAC,CAAC;IACxD,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/dist/tag-values.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Asset-tag values: normalization, identity and the documented limits.
+ *
+ * Deliberately dependency-free and side-effect-free so the same rules can
+ * run in a browser client before a write reaches the engine. Semantic tag
+ * identity is the pair (facet, canonical key) — never the display label
+ * alone — so the same word carried by two facets stays distinct.
+ */
+export declare const TAG_FACETS: readonly ["people", "places", "editing", "custom"];
+export type TagFacet = (typeof TAG_FACETS)[number];
+export type TagOrigin = "manual" | "automatic";
+/** Display labels are capped in Unicode code points, not UTF-16 units. */
+export declare const TAG_LABEL_MAX_CODE_POINTS = 64;
+/** Manual assignments a single artifact may carry. */
+export declare const MANUAL_TAGS_PER_ARTIFACT_MAX = 100;
+/** Automatic assignments one analysis snapshot may carry. */
+export declare const AUTOMATIC_TAGS_PER_SNAPSHOT_MAX = 12;
+/**
+ * Durable dismissals a single artifact may carry. Dismissals record user
+ * intent, so the ceiling refuses the write instead of silently dropping
+ * the oldest suppression.
+ */
+export declare const TAG_DISMISSALS_PER_ARTIFACT_MAX = 500;
+export interface TagInput {
+    facet: TagFacet;
+    label: string;
+    /** An already-confirmed entity; never minted from a model guess. */
+    entityId?: string;
+}
+export interface TagIdentityInput {
+    facet: TagFacet;
+    label: string;
+}
+export interface NormalizedTag {
+    facet: TagFacet;
+    key: string;
+    label: string;
+    entityId?: string;
+}
+export declare function isTagFacet(value: string): value is TagFacet;
+export declare function assertTagFacet(value: string): TagFacet;
+/**
+ * NFKC, whitespace-collapsed, trimmed display label. Control characters
+ * that survive whitespace collapsing are rejected rather than stripped, so
+ * a caller never silently stores something other than what it sent.
+ */
+export declare function normalizeTagLabel(value: string): string;
+/** Stable, locale-independent canonical key for a normalized label. */
+export declare function tagCanonicalKey(label: string): string;
+/**
+ * Prefix form of a label for autocomplete: the same NFKC, whitespace, trim
+ * and case rules as a key, so what a user types matches what was stored.
+ * An empty prefix is a legitimate "no filter" rather than an error.
+ */
+export declare function normalizeTagPrefix(value: string): string;
+export declare function tagIdentity(facet: TagFacet, key: string): string;
+export declare function normalizeTagIdentity(input: TagIdentityInput): {
+    facet: TagFacet;
+    key: string;
+    label: string;
+};
+export declare function normalizeTag(input: TagInput): NormalizedTag;
+/**
+ * Normalizes a list and drops later duplicates of an identity already
+ * seen, so a caller's repeated word never becomes a repeated chip.
+ */
+export declare function normalizeTagList(inputs: readonly TagInput[]): NormalizedTag[];
+//# sourceMappingURL=tag-values.d.ts.map

package/dist/tag-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-values.d.ts","sourceRoot":"","sources":["../src/tag-values.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,UAAU,oDAAqD,CAAC;AAE7E,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE/C,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,sDAAsD;AACtD,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,+BAA+B,KAAK,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAOtD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgBvD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWxD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,gBAAgB,GAAG;IAC7D,KAAK,EAAE,QAAQ,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf,CAIA;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa,CAS3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,QAAQ,EAAE,GAAG,aAAa,EAAE,CAW7E"}

package/dist/tag-values.js

@@ -0,0 +1,107 @@
+/**
+ * Asset-tag values: normalization, identity and the documented limits.
+ *
+ * Deliberately dependency-free and side-effect-free so the same rules can
+ * run in a browser client before a write reaches the engine. Semantic tag
+ * identity is the pair (facet, canonical key) — never the display label
+ * alone — so the same word carried by two facets stays distinct.
+ */
+export const TAG_FACETS = ["people", "places", "editing", "custom"];
+/** Display labels are capped in Unicode code points, not UTF-16 units. */
+export const TAG_LABEL_MAX_CODE_POINTS = 64;
+/** Manual assignments a single artifact may carry. */
+export const MANUAL_TAGS_PER_ARTIFACT_MAX = 100;
+/** Automatic assignments one analysis snapshot may carry. */
+export const AUTOMATIC_TAGS_PER_SNAPSHOT_MAX = 12;
+/**
+ * Durable dismissals a single artifact may carry. Dismissals record user
+ * intent, so the ceiling refuses the write instead of silently dropping
+ * the oldest suppression.
+ */
+export const TAG_DISMISSALS_PER_ARTIFACT_MAX = 500;
+const CONTROL_CHARACTER = /\p{Cc}/u;
+export function isTagFacet(value) {
+    return TAG_FACETS.includes(value);
+}
+export function assertTagFacet(value) {
+    if (!isTagFacet(value)) {
+        throw new Error(`Tag facet must be one of ${TAG_FACETS.join(", ")}; received ${value}`);
+    }
+    return value;
+}
+/**
+ * NFKC, whitespace-collapsed, trimmed display label. Control characters
+ * that survive whitespace collapsing are rejected rather than stripped, so
+ * a caller never silently stores something other than what it sent.
+ */
+export function normalizeTagLabel(value) {
+    if (typeof value !== "string") {
+        throw new Error("Tag label is required");
+    }
+    const label = value.normalize("NFKC").replace(/\s+/gu, " ").trim();
+    if (!label)
+        throw new Error("Tag label is required");
+    if (CONTROL_CHARACTER.test(label)) {
+        throw new Error("Tag label must not contain control characters");
+    }
+    const codePoints = [...label].length;
+    if (codePoints > TAG_LABEL_MAX_CODE_POINTS) {
+        throw new Error(`Tag label must be at most ${TAG_LABEL_MAX_CODE_POINTS} characters; received ${codePoints}`);
+    }
+    return label;
+}
+/** Stable, locale-independent canonical key for a normalized label. */
+export function tagCanonicalKey(label) {
+    return normalizeTagLabel(label).toLowerCase();
+}
+/**
+ * Prefix form of a label for autocomplete: the same NFKC, whitespace, trim
+ * and case rules as a key, so what a user types matches what was stored.
+ * An empty prefix is a legitimate "no filter" rather than an error.
+ */
+export function normalizeTagPrefix(value) {
+    const prefix = value.normalize("NFKC").replace(/\s+/gu, " ").trim();
+    if (CONTROL_CHARACTER.test(prefix)) {
+        throw new Error("Tag prefix must not contain control characters");
+    }
+    if ([...prefix].length > TAG_LABEL_MAX_CODE_POINTS) {
+        throw new Error(`Tag prefix must be at most ${TAG_LABEL_MAX_CODE_POINTS} characters`);
+    }
+    return prefix.toLowerCase();
+}
+export function tagIdentity(facet, key) {
+    return `${facet}:${key}`;
+}
+export function normalizeTagIdentity(input) {
+    const facet = assertTagFacet(input.facet);
+    const label = normalizeTagLabel(input.label);
+    return { facet, key: label.toLowerCase(), label };
+}
+export function normalizeTag(input) {
+    const { facet, key, label } = normalizeTagIdentity(input);
+    const entityId = input.entityId?.trim();
+    return {
+        facet,
+        key,
+        label,
+        ...(entityId ? { entityId } : {}),
+    };
+}
+/**
+ * Normalizes a list and drops later duplicates of an identity already
+ * seen, so a caller's repeated word never becomes a repeated chip.
+ */
+export function normalizeTagList(inputs) {
+    const seen = new Set();
+    const tags = [];
+    for (const input of inputs) {
+        const tag = normalizeTag(input);
+        const identity = tagIdentity(tag.facet, tag.key);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        tags.push(tag);
+    }
+    return tags;
+}
+//# sourceMappingURL=tag-values.js.map

package/dist/tag-values.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-values.js","sourceRoot":"","sources":["../src/tag-values.ts"],"names":[],"mappings":"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"}

package/dist/tags.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Asset tags: durable automatic and user-managed tagging.
+ *
+ * The engine owns state, normalization, transactions and provenance; the
+ * consumer owns inference, scheduling and vocabulary. Three rules shape
+ * everything here:
+ *
+ * 1. Semantic identity is (facet, canonical key). Two facets carrying the
+ *    same word stay distinct assignments.
+ * 2. Manual intent outranks analysis. An automatic snapshot replaces only
+ *    the automatic rows; it can never add, drop or relabel a manual row,
+ *    and it can never clear a dismissal.
+ * 3. Automatic output is fenced to the content it described. A snapshot
+ *    records the analyzed source hash and a per-artifact generation, so a
+ *    late result cannot overwrite a newer one and tags for replaced
+ *    content drop out of the effective set instead of lying.
+ */
+import type { ArtifactTagState, AutomaticTagSnapshot, EngineError, ReplaceAutomaticTagsArgs, Result } from "./engine-types.js";
+import { EngineContext } from "./context.js";
+import type { TagIdentityInput, TagInput } from "./tag-values.js";
+/** Artifacts a single batched read may cover. */
+export declare const TAG_READ_BATCH_MAX = 500;
+export declare function createTagsApi(context: EngineContext): {
+    read: (artifactId: string) => Result<ArtifactTagState, EngineError>;
+    readMany: (artifactIds: readonly string[]) => Result<ArtifactTagState[], EngineError>;
+    add: (artifactId: string, tag: TagInput) => Promise<Result<ArtifactTagState, EngineError>>;
+    addMany: (artifactId: string, tags: readonly TagInput[]) => Promise<Result<ArtifactTagState, EngineError>>;
+    remove: (artifactId: string, tag: TagIdentityInput) => Promise<Result<ArtifactTagState, EngineError>>;
+    restore: (artifactId: string, tag: TagIdentityInput) => Promise<Result<ArtifactTagState, EngineError>>;
+    automatic: {
+        snapshot: (artifactId: string) => Result<AutomaticTagSnapshot | undefined, EngineError>;
+        replace: (input: ReplaceAutomaticTagsArgs) => Promise<Result<ArtifactTagState, EngineError>>;
+    };
+    readAtRevision: (artifactId: string, revision: string) => Result<ArtifactTagState, EngineError>;
+    export: (artifactId: string) => Result<import("./engine-types.js").AssetTagSnapshotExport, EngineError>;
+    import: (artifactId: string, snapshot: import("./engine-types.js").AssetTagSnapshotExport) => Promise<Result<import("./engine-types.js").TagImportResult, EngineError>>;
+    query: (filter?: import("./engine-types.js").TagFilter, options?: import("./engine-types.js").TagQueryOptions) => Result<import("./engine-types.js").TagQueryPage, EngineError>;
+    candidates: (filter?: import("./engine-types.js").TagFilter) => Result<string[], EngineError>;
+    facets: (filter?: import("./engine-types.js").TagFilter, options?: {
+        limit?: number;
+    }) => Result<import("./engine-types.js").TagFacetCount[], EngineError>;
+    suggest: (query?: import("./engine-types.js").TagSuggestQuery) => Result<import("./engine-types.js").TagFacetCount[], EngineError>;
+};
+//# sourceMappingURL=tags.d.ts.map