@openlfcp/shared-objects 0.1.0-rc.1

package/dist/task.d.ts

@@ -0,0 +1,159 @@
+import { LfcpError, type ObjectId, type PrincipalId } from "@openlfcp/core";
+import { type Json, type ProfileProblem } from "./validate.js";
+import { type PrincipalRef } from "./values.js";
+/**
+ * The version-1 Task (SHARED-OBJECTS-PROFILE-01 §23, §30-§43) over logical
+ * state, and the §59 Task intents.
+ *
+ * A Task is its logical JSON object: the known fields typed, every other
+ * field kept as is. Mutators never rebuild the object; they copy it and
+ * change only the field the intent names, so unknown fields and extension
+ * namespaces survive any mutation (§70-§72). Each mutator returns the new
+ * state and the intent that produced it; the Automerge binding (LFCP-031)
+ * maps intents to Automerge changes. Conflict state (several concurrent
+ * values of a register, §45) only exists in the Automerge document, so
+ * task.resolve_field_conflict is LFCP-031 work.
+ */
+export type TaskStatus = "todo" | "in_progress" | "done" | "cancelled" | `x/${string}`;
+export type TaskPriority = "lowest" | "low" | "normal" | "high" | "highest" | `x/${string}`;
+export interface Task {
+    readonly id: ObjectId;
+    readonly type: "task";
+    readonly lifecycle: "active" | "deleted";
+    readonly created_by: PrincipalRef;
+    readonly created_at?: string;
+    readonly title: string;
+    readonly status: TaskStatus;
+    readonly due?: string | null;
+    readonly scheduled?: string | null;
+    readonly completion_date?: string | null;
+    readonly priority: TaskPriority;
+    /** Add-wins set: tag -> true (§39). */
+    readonly tags: {
+        readonly [tag: string]: true;
+    };
+    /** Add-wins set: Principal reference -> true (§42). */
+    readonly assignees: {
+        readonly [ref: string]: true;
+    };
+    readonly extensions: {
+        readonly [namespace: string]: Json;
+    };
+    /** Unknown Task fields are preserved (§72). */
+    readonly [unknown: string]: Json | undefined;
+}
+/** A §59 intent: what a mutation means, for the Automerge binding. */
+export type TaskIntent = {
+    readonly intent: "task.create";
+    readonly task: Task;
+} | {
+    readonly intent: "task.set_title";
+    readonly id: ObjectId;
+    readonly title: string;
+} | {
+    readonly intent: "task.set_status";
+    readonly id: ObjectId;
+    readonly status: TaskStatus;
+} | {
+    readonly intent: "task.complete";
+    readonly id: ObjectId;
+    readonly completionDate?: string;
+} | {
+    readonly intent: "task.reopen";
+    readonly id: ObjectId;
+} | {
+    readonly intent: "task.cancel";
+    readonly id: ObjectId;
+} | {
+    readonly intent: "task.set_due" | "task.set_scheduled";
+    readonly id: ObjectId;
+    readonly date: string;
+} | {
+    readonly intent: "task.clear_due" | "task.clear_scheduled";
+    readonly id: ObjectId;
+} | {
+    readonly intent: "task.set_priority";
+    readonly id: ObjectId;
+    readonly priority: TaskPriority;
+} | {
+    readonly intent: "task.add_tag" | "task.remove_tag";
+    readonly id: ObjectId;
+    readonly tag: string;
+} | {
+    readonly intent: "task.add_assignee" | "task.remove_assignee";
+    readonly id: ObjectId;
+    readonly assignee: PrincipalRef;
+} | {
+    readonly intent: "task.delete" | "task.restore";
+    readonly id: ObjectId;
+};
+/** A mutation result: the new Task and the intent. */
+export interface TaskChange {
+    readonly task: Task;
+    readonly intent: TaskIntent;
+}
+/** Thrown for a value a writer must not create: PROFILE_INVALID with the §74.1 problems. */
+export declare class ProfileError extends LfcpError {
+    readonly problems: readonly ProfileProblem[];
+    constructor(problems: readonly ProfileProblem[]);
+}
+export type ParsedTask = {
+    readonly valid: true;
+    readonly task: Task;
+} | {
+    readonly valid: false;
+    readonly problems: readonly ProfileProblem[];
+};
+/**
+ * Validates a Task stored under `key` (default: its own id) and returns it
+ * as a Task (a frozen copy with every field, known or not), or its
+ * problems with pointers relative to the object ("/title", ...).
+ */
+export declare function parseTask(object: Json | undefined, key?: string): ParsedTask;
+/** The Task as logical JSON (it already is; this returns a deep copy). */
+export declare const taskToJson: (task: Task) => Json;
+export interface NewTask {
+    readonly title: string;
+    /** The creating Principal (§27). */
+    readonly createdBy: PrincipalId;
+    readonly status?: TaskStatus;
+    readonly priority?: TaskPriority;
+    readonly due?: string;
+    readonly scheduled?: string;
+    readonly tags?: readonly string[];
+    readonly assignees?: readonly (PrincipalId | PrincipalRef)[];
+    /** RFC 3339 UTC; omitted when no reliable clock is available (§53). */
+    readonly createdAt?: string;
+    /** A UUIDv7 Object ID; generated client-side when absent (§19, §60). */
+    readonly id?: ObjectId;
+}
+/** task.create (§53, §60): a new active Task with every required field, in one change. */
+export declare function createTask(input: NewTask): TaskChange;
+export declare const setTitle: (task: Task, title: string) => TaskChange;
+/** task.set_status (§62): changes only the status. */
+export declare const setStatus: (task: Task, status: TaskStatus) => TaskChange;
+/** task.complete (§63): status done and, when supplied, the completion date. */
+export declare function complete(task: Task, completionDate?: string): TaskChange;
+/** task.reopen (§64): status todo and no completion date. */
+export declare const reopen: (task: Task) => TaskChange;
+/** task.cancel (§65): status cancelled; the completion date is cleared. */
+export declare const cancel: (task: Task) => TaskChange;
+export declare const setDue: (task: Task, value: string) => TaskChange;
+export declare const setScheduled: (task: Task, value: string) => TaskChange;
+/** task.clear_due (§66): deletes the property. */
+export declare const clearDue: (task: Task) => TaskChange;
+export declare const clearScheduled: (task: Task) => TaskChange;
+export declare const setPriority: (task: Task, priority: TaskPriority) => TaskChange;
+/** task.add_tag (§67): tags[tag] = true, after NFC normalization. */
+export declare function addTag(task: Task, tag: string): TaskChange;
+/** task.remove_tag (§67): deletes the key (never stores false, §39). */
+export declare function removeTag(task: Task, tag: string): TaskChange;
+/** task.add_assignee (§68). */
+export declare function assign(task: Task, who: PrincipalId | PrincipalRef): TaskChange;
+/** task.remove_assignee (§68): deletes the key. */
+export declare function unassign(task: Task, who: PrincipalId | PrincipalRef): TaskChange;
+/** task.delete (§54): lifecycle = deleted, a tombstone; the object stays. */
+export declare const deleteTask: (task: Task) => TaskChange;
+/** task.restore (§55): lifecycle = active. */
+export declare const restoreTask: (task: Task) => TaskChange;
+//# sourceMappingURL=task.d.ts.map

package/dist/task.js

@@ -0,0 +1,192 @@
+import { generateObjectId, isObjectId, LfcpError, } from "@openlfcp/core";
+import { isMap, objectProblems } from "./validate.js";
+import { isLocalDate, isPrincipalRef, principalRef } from "./values.js";
+/** Thrown for a value a writer must not create: PROFILE_INVALID with the §74.1 problems. */
+export class ProfileError extends LfcpError {
+    problems;
+    constructor(problems) {
+        super("PROFILE_INVALID", problems.map((p) => `${p.diagnostic} at ${p.pointer}: ${p.message}`).join("; "));
+        this.name = "ProfileError";
+        this.problems = problems;
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const v of Object.values(value))
+            deepFreeze(v);
+        Object.freeze(value);
+    }
+    return value;
+}
+const copy = (value) => JSON.parse(JSON.stringify(value));
+/**
+ * Validates a Task stored under `key` (default: its own id) and returns it
+ * as a Task (a frozen copy with every field, known or not), or its
+ * problems with pointers relative to the object ("/title", ...).
+ */
+export function parseTask(object, key) {
+    if (!isMap(object) || object.type !== "task") {
+        const problems = isMap(object)
+            ? [
+                {
+                    code: "PROFILE_INVALID",
+                    diagnostic: "INVALID_FIELD_TYPE",
+                    pointer: "/type",
+                    message: "not a Task (type must be task)",
+                },
+            ]
+            : objectProblems(object, key ?? "", "");
+        return { valid: false, problems };
+    }
+    const problems = objectProblems(object, key ?? String(object.id), "");
+    if (problems.length > 0)
+        return { valid: false, problems };
+    return { valid: true, task: deepFreeze(copy(object)) };
+}
+/** The Task as logical JSON (it already is; this returns a deep copy). */
+export const taskToJson = (task) => copy(task);
+function checked(task) {
+    const problems = objectProblems(task, String(task.id), "");
+    if (problems.length > 0)
+        throw new ProfileError(problems);
+    return deepFreeze(task);
+}
+/** A copy of `task` with `changes` applied; `undefined` deletes a property (§36: writers delete cleared dates). */
+function edit(task, changes) {
+    const next = copy(task);
+    for (const [field, value] of Object.entries(changes)) {
+        if (value === undefined)
+            delete next[field];
+        else
+            next[field] = value;
+    }
+    return checked(next);
+}
+const tagKey = (tag) => tag.normalize("NFC"); // §40, §67: SHOULD normalize to NFC
+const refOf = (who) => typeof who === "string" ? who : principalRef(who);
+/** task.create (§53, §60): a new active Task with every required field, in one change. */
+export function createTask(input) {
+    const id = input.id ?? generateObjectId();
+    if (!isObjectId(id))
+        throw new LfcpError("INVALID_UUIDV7", "a Task id must be a canonical UUIDv7");
+    const object = {
+        id,
+        type: "task",
+        lifecycle: "active",
+        created_by: principalRef(input.createdBy),
+        ...(input.createdAt !== undefined ? { created_at: input.createdAt } : {}),
+        title: input.title,
+        status: input.status ?? "todo",
+        ...(input.due !== undefined ? { due: input.due } : {}),
+        ...(input.scheduled !== undefined ? { scheduled: input.scheduled } : {}),
+        priority: input.priority ?? "normal",
+        tags: Object.fromEntries((input.tags ?? []).map((t) => [tagKey(t), true])),
+        assignees: Object.fromEntries((input.assignees ?? []).map((a) => [refOf(a), true])),
+        extensions: {},
+    };
+    const task = checked(object);
+    return { task, intent: { intent: "task.create", task } };
+}
+const change = (task, intent) => Object.freeze({ task, intent });
+export const setTitle = (task, title) => change(edit(task, { title }), { intent: "task.set_title", id: task.id, title });
+/** task.set_status (§62): changes only the status. */
+export const setStatus = (task, status) => change(edit(task, { status }), { intent: "task.set_status", id: task.id, status });
+/** task.complete (§63): status done and, when supplied, the completion date. */
+export function complete(task, completionDate) {
+    const next = edit(task, completionDate === undefined
+        ? { status: "done" }
+        : { status: "done", completion_date: completionDate });
+    return change(next, {
+        intent: "task.complete",
+        id: task.id,
+        ...(completionDate !== undefined ? { completionDate } : {}),
+    });
+}
+/** task.reopen (§64): status todo and no completion date. */
+export const reopen = (task) => change(edit(task, { status: "todo", completion_date: undefined }), {
+    intent: "task.reopen",
+    id: task.id,
+});
+/** task.cancel (§65): status cancelled; the completion date is cleared. */
+export const cancel = (task) => change(edit(task, { status: "cancelled", completion_date: undefined }), {
+    intent: "task.cancel",
+    id: task.id,
+});
+function date(field, task, value) {
+    // §66: "MUST validate the Local Date grammar before creating a change".
+    if (!isLocalDate(value))
+        throw new ProfileError([
+            {
+                code: "PROFILE_INVALID",
+                diagnostic: "INVALID_LOCAL_DATE",
+                pointer: `/${field}`,
+                message: `${value} is not a Gregorian YYYY-MM-DD date (§35)`,
+            },
+        ]);
+    return change(edit(task, { [field]: value }), {
+        intent: `task.set_${field}`,
+        id: task.id,
+        date: value,
+    });
+}
+export const setDue = (task, value) => date("due", task, value);
+export const setScheduled = (task, value) => date("scheduled", task, value);
+/** task.clear_due (§66): deletes the property. */
+export const clearDue = (task) => change(edit(task, { due: undefined }), { intent: "task.clear_due", id: task.id });
+export const clearScheduled = (task) => change(edit(task, { scheduled: undefined }), { intent: "task.clear_scheduled", id: task.id });
+export const setPriority = (task, priority) => change(edit(task, { priority }), { intent: "task.set_priority", id: task.id, priority });
+/** task.add_tag (§67): tags[tag] = true, after NFC normalization. */
+export function addTag(task, tag) {
+    const key = tagKey(tag);
+    return change(edit(task, { tags: { ...task.tags, [key]: true } }), {
+        intent: "task.add_tag",
+        id: task.id,
+        tag: key,
+    });
+}
+/** task.remove_tag (§67): deletes the key (never stores false, §39). */
+export function removeTag(task, tag) {
+    const key = tagKey(tag);
+    const tags = { ...task.tags };
+    delete tags[key];
+    return change(edit(task, { tags }), { intent: "task.remove_tag", id: task.id, tag: key });
+}
+function assigneeRef(who) {
+    const ref = refOf(who);
+    // §68: "MUST validate the Principal reference encoding before mutation".
+    if (!isPrincipalRef(ref))
+        throw new ProfileError([
+            {
+                code: "PROFILE_INVALID",
+                diagnostic: "INVALID_PRINCIPAL_REF",
+                pointer: "/assignees",
+                message: "not a Principal reference (§27)",
+            },
+        ]);
+    return ref;
+}
+/** task.add_assignee (§68). */
+export function assign(task, who) {
+    const ref = assigneeRef(who);
+    return change(edit(task, { assignees: { ...task.assignees, [ref]: true } }), {
+        intent: "task.add_assignee",
+        id: task.id,
+        assignee: ref,
+    });
+}
+/** task.remove_assignee (§68): deletes the key. */
+export function unassign(task, who) {
+    const ref = assigneeRef(who);
+    const assignees = { ...task.assignees };
+    delete assignees[ref];
+    return change(edit(task, { assignees }), {
+        intent: "task.remove_assignee",
+        id: task.id,
+        assignee: ref,
+    });
+}
+/** task.delete (§54): lifecycle = deleted, a tombstone; the object stays. */
+export const deleteTask = (task) => change(edit(task, { lifecycle: "deleted" }), { intent: "task.delete", id: task.id });
+/** task.restore (§55): lifecycle = active. */
+export const restoreTask = (task) => change(edit(task, { lifecycle: "active" }), { intent: "task.restore", id: task.id });
+//# sourceMappingURL=task.js.map

package/dist/validate.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Profile validation of Shared Objects logical state (SHARED-OBJECTS-
+ * PROFILE-01 §73-§77): the JSON an Automerge document of this profile
+ * materializes to. Every failure is PROFILE_INVALID with exactly one §74.1
+ * diagnostic, at a JSON Pointer (RFC 6901); a field value that breaks
+ * several rules gets the first in §74.1 table order. One invalid object never makes
+ * the others unusable (§77); unknown fields, extension namespaces, object
+ * types and x/…/… values are accepted and preserved (§70-§72).
+ */
+/** §74.1 diagnostics. */
+export type ProfileDiagnostic = "INVALID_ROOT" | "INVALID_OBJECT_ID" | "OBJECT_ID_MISMATCH" | "MISSING_REQUIRED_FIELD" | "INVALID_FIELD_TYPE" | "INVALID_ENUM_VALUE" | "INVALID_EXTENSION_NAMESPACE" | "INVALID_PRINCIPAL_REF" | "INVALID_TIMESTAMP" | "INVALID_LOCAL_DATE" | "INVALID_COLLECTION_REPRESENTATION" | "INVALID_TAG" | "IMMUTABLE_FIELD_MUTATED"
+/** §8, §11: a Data Unit's Automerge change is not of its signer's actor; it is not merged. */
+ | "CHANGE_ACTOR_MISMATCH"
+/** §11, §13: a plaintext's framing or Automerge bytes are invalid (chunk type, checksum, parse, load); nothing is merged. */
+ | "INVALID_AUTOMERGE_BYTES";
+/** One profile validation failure: PROFILE_INVALID with its §74.1 diagnostic. */
+export interface ProfileProblem {
+    readonly code: "PROFILE_INVALID";
+    readonly diagnostic: ProfileDiagnostic;
+    /** JSON Pointer of the offending value (of its container, for a missing field). */
+    readonly pointer: string;
+    readonly message: string;
+}
+/** The §74.1 registry in table order: structure and value rules first, IMMUTABLE_FIELD_MUTATED last. */
+export declare const DIAGNOSTIC_ORDER: readonly ProfileDiagnostic[];
+/**
+ * §74.1 precedence for the fields of the object at `object` (its JSON
+ * Pointer): "When one value breaks several rules, its diagnostic is the
+ * first that applies in the order of this table", and a field with
+ * concurrent values (§45) gets the diagnostic of its first invalid value in
+ * that order. Of several problems at one field pointer, those with the
+ * first diagnostic are kept, at every pointer below the object (fields,
+ * set members, values inside extensions). Problems at the object itself
+ * (its key, a missing field) are kept as they are.
+ */
+export declare function firstPerField(problems: readonly ProfileProblem[], object: string): ProfileProblem[];
+export { ProfileInvalidError } from "./profile-invalid.js";
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+type JsonMap = {
+    readonly [key: string]: Json;
+};
+export declare const isMap: (v: unknown) => v is JsonMap;
+/** RFC 6901 escaping of one reference token. */
+export declare const pointerToken: (key: string) => string;
+/**
+ * Problems of one Shared Object stored under `key` in `objects`, with
+ * pointers below `at` (default "/objects/<key>"). Non-Task types are
+ * checked for the base fields only (§23, §71).
+ */
+export declare function objectProblems(object: Json | undefined, key: string, at?: string): ProfileProblem[];
+/** The result of validating a root: root-level problems and problems per object (§77 isolation). */
+export interface RootValidation {
+    readonly valid: boolean;
+    readonly problems: readonly ProfileProblem[];
+    /** Problems per objects key; an object with none is usable. */
+    readonly objects: ReadonlyMap<string, readonly ProfileProblem[]>;
+}
+/** Validates a whole root (§15, §74). Unknown top-level keys are preserved, not rejected (§17). */
+export declare function validateRoot(root: Json | undefined): RootValidation;
+/**
+ * §75: id, type and created_by never change. Problems for every object
+ * present in both states whose immutable field differs, unless the new
+ * value breaks a structure or value rule: §74.1 puts
+ * IMMUTABLE_FIELD_MUTATED last, so that value's diagnostic is the one
+ * objectProblems reports.
+ */
+export declare function validateTransition(before: Json | undefined, after: Json | undefined): readonly ProfileProblem[];
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.js

@@ -0,0 +1,196 @@
+import { isObjectId } from "@openlfcp/core";
+import { isLocalDate, isNamespacedValue, isPrincipalRef, isReverseDomain, isUtcTimestamp, PROFILE_ID, } from "./values.js";
+/** The §74.1 registry in table order: structure and value rules first, IMMUTABLE_FIELD_MUTATED last. */
+export const DIAGNOSTIC_ORDER = Object.freeze([
+    "INVALID_ROOT",
+    "INVALID_OBJECT_ID",
+    "OBJECT_ID_MISMATCH",
+    "MISSING_REQUIRED_FIELD",
+    "INVALID_FIELD_TYPE",
+    "INVALID_ENUM_VALUE",
+    "INVALID_EXTENSION_NAMESPACE",
+    "INVALID_PRINCIPAL_REF",
+    "INVALID_TIMESTAMP",
+    "INVALID_LOCAL_DATE",
+    "INVALID_COLLECTION_REPRESENTATION",
+    "INVALID_TAG",
+    "IMMUTABLE_FIELD_MUTATED",
+    "CHANGE_ACTOR_MISMATCH",
+    "INVALID_AUTOMERGE_BYTES",
+]);
+/**
+ * §74.1 precedence for the fields of the object at `object` (its JSON
+ * Pointer): "When one value breaks several rules, its diagnostic is the
+ * first that applies in the order of this table", and a field with
+ * concurrent values (§45) gets the diagnostic of its first invalid value in
+ * that order. Of several problems at one field pointer, those with the
+ * first diagnostic are kept, at every pointer below the object (fields,
+ * set members, values inside extensions). Problems at the object itself
+ * (its key, a missing field) are kept as they are.
+ */
+export function firstPerField(problems, object) {
+    const rank = (p) => DIAGNOSTIC_ORDER.indexOf(p.diagnostic);
+    // Every value below the object (a field, a set member, a value inside extensions).
+    const isField = (pointer) => pointer.startsWith(`${object}/`);
+    const best = new Map();
+    for (const p of problems)
+        if (isField(p.pointer))
+            best.set(p.pointer, Math.min(best.get(p.pointer) ?? Number.POSITIVE_INFINITY, rank(p)));
+    return problems.filter((p) => !isField(p.pointer) || rank(p) === best.get(p.pointer));
+}
+export { ProfileInvalidError } from "./profile-invalid.js";
+export const isMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/** RFC 6901 escaping of one reference token. */
+export const pointerToken = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
+const problem = (diagnostic, pointer, message) => Object.freeze({ code: "PROFILE_INVALID", diagnostic, pointer, message });
+const STATUSES = new Set(["todo", "in_progress", "done", "cancelled"]);
+const PRIORITIES = new Set(["lowest", "low", "normal", "high", "highest"]);
+const LIFECYCLES = new Set(["active", "deleted"]);
+const BASE_REQUIRED = ["id", "type", "lifecycle", "created_by", "extensions"];
+const TASK_REQUIRED = ["title", "status", "priority", "tags", "assignees"];
+const DATE_FIELDS = ["due", "scheduled", "completion_date"];
+function extensionProblems(value, at, onType) {
+    if (!isMap(value))
+        return [problem(onType, at, "extensions must be a map (§18, §29)")];
+    return Object.keys(value)
+        .filter((ns) => !isReverseDomain(ns))
+        .map((ns) => problem("INVALID_EXTENSION_NAMESPACE", `${at}/${pointerToken(ns)}`, `"${ns}" is not a reverse-domain namespace (§18)`));
+}
+function setProblems(value, at, what, keyCheck) {
+    if (!isMap(value))
+        return [
+            problem("INVALID_COLLECTION_REPRESENTATION", at, `${what} must be a map of key -> true (§39, §42)`),
+        ];
+    const out = [];
+    for (const [key, member] of Object.entries(value)) {
+        const keyProblem = keyCheck(key);
+        if (keyProblem !== null)
+            out.push(keyProblem);
+        if (member !== true)
+            out.push(problem("INVALID_COLLECTION_REPRESENTATION", `${at}/${pointerToken(key)}`, `a ${what} member's value must be true (§39, §42)`));
+    }
+    return out;
+}
+/**
+ * Problems of one Shared Object stored under `key` in `objects`, with
+ * pointers below `at` (default "/objects/<key>"). Non-Task types are
+ * checked for the base fields only (§23, §71).
+ */
+export function objectProblems(object, key, at = `/objects/${pointerToken(key)}`) {
+    return firstPerField(allObjectProblems(object, key, at), at);
+}
+function allObjectProblems(object, key, at) {
+    const out = [];
+    if (!isObjectId(key))
+        out.push(problem("INVALID_OBJECT_ID", at, `the objects key "${key}" is not a canonical UUIDv7 (§19)`));
+    if (!isMap(object)) {
+        out.push(problem("INVALID_FIELD_TYPE", at, "a Shared Object must be a map (§23)"));
+        return out;
+    }
+    const o = object;
+    const required = o.type === "task" ? [...BASE_REQUIRED, ...TASK_REQUIRED] : BASE_REQUIRED;
+    for (const field of required) {
+        if (!(field in o))
+            out.push(problem("MISSING_REQUIRED_FIELD", at, `the required field ${field} is missing (§23, §31)`));
+    }
+    if ("id" in o) {
+        if (typeof o.id !== "string" || !isObjectId(o.id))
+            out.push(problem("INVALID_OBJECT_ID", `${at}/id`, "id is not a canonical UUIDv7 (§19)"));
+        if (o.id !== key)
+            out.push(problem("OBJECT_ID_MISMATCH", `${at}/id`, "id differs from its objects key (§20, §24)"));
+    }
+    if ("type" in o && (typeof o.type !== "string" || o.type.length === 0))
+        out.push(problem("INVALID_FIELD_TYPE", `${at}/type`, "type must be non-empty text (§25)"));
+    if ("lifecycle" in o && !(typeof o.lifecycle === "string" && LIFECYCLES.has(o.lifecycle)))
+        out.push(problem("INVALID_ENUM_VALUE", `${at}/lifecycle`, "lifecycle must be active or deleted (§26)"));
+    if ("created_by" in o && !isPrincipalRef(o.created_by))
+        out.push(problem("INVALID_PRINCIPAL_REF", `${at}/created_by`, "created_by is not a Principal reference (§27)"));
+    // created_at is a base field (§23, §28), so it is checked on every object type.
+    if ("created_at" in o && !isUtcTimestamp(o.created_at))
+        out.push(problem("INVALID_TIMESTAMP", `${at}/created_at`, "created_at is not an RFC 3339 UTC timestamp (§28)"));
+    if ("extensions" in o)
+        out.push(...extensionProblems(o.extensions, `${at}/extensions`, "INVALID_FIELD_TYPE"));
+    if (o.type !== "task")
+        return out;
+    if ("title" in o && typeof o.title !== "string")
+        out.push(problem("INVALID_FIELD_TYPE", `${at}/title`, "title must be text (§32)"));
+    if ("status" in o &&
+        !(typeof o.status === "string" && (STATUSES.has(o.status) || isNamespacedValue(o.status))))
+        out.push(problem("INVALID_ENUM_VALUE", `${at}/status`, "status is neither standard nor x/<reverse-domain>/<value> (§33)"));
+    if ("priority" in o &&
+        !(typeof o.priority === "string" &&
+            (PRIORITIES.has(o.priority) || isNamespacedValue(o.priority))))
+        out.push(problem("INVALID_ENUM_VALUE", `${at}/priority`, "priority is neither standard nor x/<reverse-domain>/<value> (§38)"));
+    for (const field of DATE_FIELDS) {
+        // §36: missing and null both mean no date.
+        if (field in o && o[field] !== null && !isLocalDate(o[field]))
+            out.push(problem("INVALID_LOCAL_DATE", `${at}/${field}`, `${field} is not a Gregorian YYYY-MM-DD date (§35)`));
+    }
+    if ("tags" in o)
+        out.push(...setProblems(o.tags, `${at}/tags`, "tag", (tag) => tag.length === 0 || tag.startsWith("#")
+            ? problem("INVALID_TAG", `${at}/tags/${pointerToken(tag)}`, "a tag must be non-empty without a leading # (§40)")
+            : null));
+    if ("assignees" in o)
+        out.push(...setProblems(o.assignees, `${at}/assignees`, "assignee", (ref) => isPrincipalRef(ref)
+            ? null
+            : problem("INVALID_PRINCIPAL_REF", `${at}/assignees/${pointerToken(ref)}`, "an assignee key is not a Principal reference (§42)")));
+    return out;
+}
+/** Validates a whole root (§15, §74). Unknown top-level keys are preserved, not rejected (§17). */
+export function validateRoot(root) {
+    const rootProblems = [];
+    const perObject = new Map();
+    if (!isMap(root)) {
+        rootProblems.push(problem("INVALID_ROOT", "/", "the root must be a map (§15)"));
+    }
+    else {
+        if (!("profile" in root) || root.profile !== PROFILE_ID)
+            rootProblems.push(problem("INVALID_ROOT", "profile" in root ? "/profile" : "/", `profile must be ${PROFILE_ID} (§15)`));
+        if (!("objects" in root))
+            rootProblems.push(problem("INVALID_ROOT", "/", "objects is missing (§15)"));
+        else if (!isMap(root.objects))
+            rootProblems.push(problem("INVALID_ROOT", "/objects", "objects must be a map (§15)"));
+        else
+            for (const [key, object] of Object.entries(root.objects))
+                perObject.set(key, objectProblems(object, key));
+        if (!("extensions" in root))
+            rootProblems.push(problem("INVALID_ROOT", "/", "extensions is missing (§15)"));
+        else
+            rootProblems.push(...extensionProblems(root.extensions, "/extensions", "INVALID_ROOT"));
+    }
+    const all = [...rootProblems, ...[...perObject.values()].flat()];
+    return Object.freeze({
+        valid: all.length === 0,
+        problems: Object.freeze(all),
+        objects: perObject,
+    });
+}
+const IMMUTABLE = ["id", "type", "created_by"];
+/**
+ * §75: id, type and created_by never change. Problems for every object
+ * present in both states whose immutable field differs, unless the new
+ * value breaks a structure or value rule: §74.1 puts
+ * IMMUTABLE_FIELD_MUTATED last, so that value's diagnostic is the one
+ * objectProblems reports.
+ */
+export function validateTransition(before, after) {
+    if (!isMap(before) || !isMap(after) || !isMap(before.objects) || !isMap(after.objects))
+        return [];
+    const out = [];
+    for (const [key, old] of Object.entries(before.objects)) {
+        const now = after.objects[key];
+        if (!isMap(old) || !isMap(now))
+            continue;
+        const at = `/objects/${pointerToken(key)}`;
+        const broken = new Set(objectProblems(now, key, at).map((p) => p.pointer));
+        for (const field of IMMUTABLE) {
+            // A removed field is MISSING_REQUIRED_FIELD, an earlier diagnostic.
+            if (!(field in now) || broken.has(`${at}/${field}`))
+                continue;
+            if (field in old && JSON.stringify(old[field]) !== JSON.stringify(now[field]))
+                out.push(problem("IMMUTABLE_FIELD_MUTATED", `${at}/${field}`, `${field} changed (§24, §25, §27, §75)`));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=validate.js.map

package/dist/values.d.ts

@@ -0,0 +1,52 @@
+import { type PrincipalId, type ResourceId } from "@openlfcp/core";
+/**
+ * Value-level rules of SHARED-OBJECTS-PROFILE-01: Principal references,
+ * Local Dates, timestamps, reverse-domain names, namespaced values, the
+ * Automerge actor ID and the profile framing of Data Unit and Snapshot
+ * plaintexts.
+ */
+/** §6: the profile identifier. */
+export declare const PROFILE_ID = "org.openlfcp.shared-objects.v1";
+/** A Principal reference (§27, §42): "p:" + unpadded base64url of the 32-byte Principal ID. */
+export type PrincipalRef = string & {
+    readonly __principalRef: true;
+};
+/** §27: the reference of a Principal ID. */
+export declare function principalRef(id: PrincipalId): PrincipalRef;
+/** True when `text` is a canonical Principal reference of exactly 32 bytes. */
+export declare function isPrincipalRef(text: unknown): text is PrincipalRef;
+/** The Principal ID a reference names; throws INVALID_BASE64URL / INVALID_LENGTH otherwise. */
+export declare function parsePrincipalRef(text: string): PrincipalId;
+/** §35: a real Gregorian date YYYY-MM-DD (no time zone). */
+export declare function isLocalDate(text: unknown): text is string;
+/** §28: an RFC 3339 UTC timestamp ending in Z with a real date and time (second 60 for leap seconds). */
+export declare function isUtcTimestamp(text: unknown): text is string;
+/** §18 ABNF reverse-domain: at least two lowercase LDH labels without leading or trailing hyphen. */
+export declare const isReverseDomain: (text: unknown) => text is string;
+/** §33 ABNF namespaced-value: x/<reverse-domain>/<value>, value non-empty without "/". */
+export declare const isNamespacedValue: (text: unknown) => text is string;
+/**
+ * §8: the Automerge actor ID of `principal` editing `resource`:
+ * SHA-256(ASCII("OPENLFCP-SHARED-OBJECTS-ACTOR-v1") || resource_id || principal_id),
+ * from the raw 32-byte IDs.
+ */
+export declare function deriveActorId(resource: ResourceId, principal: PrincipalId): Uint8Array;
+/** §11, §13: the only framing version. */
+export declare const FRAMING_VERSION = 1;
+/**
+ * Deterministic CBOR of [1, bstr] (§11 shared-objects-change, §13
+ * shared-objects-snapshot): the profile plaintext of a Data Unit (one
+ * Automerge change) or a Snapshot (one Automerge full save). The bytes are
+ * framed as given; checking that they are a valid Automerge change or save
+ * is the Automerge binding (LFCP-031).
+ */
+export declare function frameProfilePayload(bytes: Uint8Array): Uint8Array;
+/**
+ * The inner bytes of a framed profile plaintext. §11: a receiver MUST
+ * reject plaintext that is not valid CBOR, not a two-element array, or
+ * uses an unsupported framing version; this also requires the
+ * deterministic encoding and no trailing bytes. Throws PROFILE_INVALID /
+ * INVALID_AUTOMERGE_BYTES (§74.1).
+ */
+export declare function unframeProfilePayload(framed: Uint8Array): Uint8Array;
+//# sourceMappingURL=values.d.ts.map