@kashscript/lexicons 0.1.0

package/src/lexicons/kash-id-preferences.ts

@@ -0,0 +1,114 @@
+/**
+ * Lexicon: kash.id.preferences@1.0.0
+ *
+ * App-agnostic user preferences. Single-record collection (rkey: "self").
+ *
+ * Privacy-by-default: if `privacy.allowAI` is absent or any flag within it
+ * is absent, the relevant flag defaults to FALSE. Oreoasis MUST NOT ingest
+ * a user's records without `allowAI.neuronIngest === true`.
+ */
+
+import { S, type ObjectSchema } from "../schema";
+
+export const KASH_PREFERENCES_NSID    = "kash.id.preferences" as const;
+export const KASH_PREFERENCES_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_PREFERENCES_ID      = "kash.id.preferences@1.0.0" as const;
+
+/* ── types ──────────────────────────────────────────────────────── */
+
+export type ThemePref     = "light" | "dark" | "system";
+export type Visibility    = "public" | "followers" | "private";
+export type TimeFormat    = "12h" | "24h";
+
+export interface AIConsent {
+  /** May my records be used to train models? */
+  readonly training: boolean;
+  /** May my records be retrieved at inference time (RAG)? */
+  readonly inference: boolean;
+  /** May Oreoasis (Neuron) ingest my records into its context engine? */
+  readonly neuronIngest: boolean;
+  /** Optional list of NSIDs explicitly excluded from any AI use. */
+  readonly excludedCollections?: readonly string[];
+}
+
+export interface PrivacyPreferences {
+  /** Visibility of the profile to non-followers / public crawlers. */
+  readonly profileVisibility: Visibility;
+  /** Whether crawlers / federation peers may index this identity. */
+  readonly indexable: boolean;
+  /** AI consent flags — ALL DEFAULT FALSE if absent. */
+  readonly allowAI?: AIConsent;
+}
+
+export interface NotificationPreferences {
+  readonly handshakes: boolean;
+  readonly keyRotations: boolean;
+  readonly quorumActivity: boolean;
+}
+
+export interface UnitPreferences {
+  /** ISO 4217 currency code (USD, PKR, EUR, …). */
+  readonly currency: string;
+  readonly timeFormat: TimeFormat;
+  /** strftime-like template ("%Y-%m-%d"). */
+  readonly dateFormat: string;
+}
+
+export interface KashPreferencesBody {
+  /** BCP 47 language tag ("en", "ur-PK"). */
+  readonly language?: string;
+  readonly theme?: ThemePref;
+  readonly privacy?: PrivacyPreferences;
+  readonly notifications?: NotificationPreferences;
+  readonly units?: UnitPreferences;
+}
+
+/* ── runtime schema ─────────────────────────────────────────────── */
+
+const AI_CONSENT: ObjectSchema = S.object(
+  {
+    training:            S.boolean(),
+    inference:           S.boolean(),
+    neuronIngest:        S.boolean(),
+    excludedCollections: S.optional(S.array(S.string({ format: "nsid" }), { maxItems: 64 })),
+  },
+  ["training", "inference", "neuronIngest"],
+);
+
+const PRIVACY: ObjectSchema = S.object(
+  {
+    profileVisibility: S.enum("public", "followers", "private"),
+    indexable:         S.boolean(),
+    allowAI:           S.optional(AI_CONSENT),
+  },
+  ["profileVisibility", "indexable"],
+);
+
+const NOTIFICATIONS: ObjectSchema = S.object(
+  {
+    handshakes:     S.boolean(),
+    keyRotations:   S.boolean(),
+    quorumActivity: S.boolean(),
+  },
+  ["handshakes", "keyRotations", "quorumActivity"],
+);
+
+const UNITS: ObjectSchema = S.object(
+  {
+    currency:   S.string({ format: "iso4217" }),
+    timeFormat: S.enum("12h", "24h"),
+    dateFormat: S.string({ minLength: 1, maxLength: 32 }),
+  },
+  ["currency", "timeFormat", "dateFormat"],
+);
+
+export const KASH_PREFERENCES_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    language:      S.optional(S.string({ format: "bcp47" })),
+    theme:         S.optional(S.enum("light", "dark", "system")),
+    privacy:       S.optional(PRIVACY),
+    notifications: S.optional(NOTIFICATIONS),
+    units:         S.optional(UNITS),
+  },
+  [],
+);

package/src/lexicons/kash-id-profile.ts

@@ -0,0 +1,82 @@
+/**
+ * Lexicon: kash.id.profile@1.0.0
+ *
+ * Sovereign user profile. Single-record collection (rkey: "self" by convention).
+ */
+
+import { S, type ObjectSchema } from "../schema";
+import type { CID } from "../types";
+
+export const KASH_PROFILE_NSID    = "kash.id.profile" as const;
+export const KASH_PROFILE_VERSION = { major: 1, minor: 0, patch: 0 } as const;
+export const KASH_PROFILE_ID      = "kash.id.profile@1.0.0" as const;
+
+/* ── types ──────────────────────────────────────────────────────── */
+
+export type ProfileImageMime = "image/jpeg" | "image/png" | "image/webp" | "image/avif";
+
+export interface ProfileBlobRef {
+  readonly cid: CID;
+  readonly mimeType: ProfileImageMime;
+  readonly altText?: string;
+}
+
+export interface ProfileLink {
+  readonly label: string;
+  readonly url: string;
+}
+
+export interface KashProfileBody {
+  /** Optional human-readable handle hint. The authoritative handle is in the DID Document's alsoKnownAs. */
+  readonly handle?: string;
+  /** Display name. 1–64 characters after NFC normalisation. */
+  readonly displayName: string;
+  /** Short bio. 0–280 characters. */
+  readonly bio?: string;
+  /** Avatar image blob reference. */
+  readonly avatar?: ProfileBlobRef;
+  /** Banner image blob reference. */
+  readonly banner?: ProfileBlobRef;
+  /** Free-form pronouns string. */
+  readonly pronouns?: string;
+  /** Human-readable location ("Islamabad, PK"). */
+  readonly location?: string;
+  /** Pinned PDS / relay URLs the author wants peers to discover. Max 8. */
+  readonly pdsUrls?: readonly string[];
+  /** External profile links. Max 8. */
+  readonly links?: readonly ProfileLink[];
+}
+
+/* ── runtime schema ─────────────────────────────────────────────── */
+
+const PROFILE_BLOB_REF: ObjectSchema = S.object(
+  {
+    cid:      S.string({ format: "cid" }),
+    mimeType: S.enum("image/jpeg", "image/png", "image/webp", "image/avif"),
+    altText:  S.optional(S.string({ maxLength: 420 })),
+  },
+  ["cid", "mimeType"],
+);
+
+const PROFILE_LINK: ObjectSchema = S.object(
+  {
+    label: S.string({ minLength: 1, maxLength: 32 }),
+    url:   S.string({ format: "url" }),
+  },
+  ["label", "url"],
+);
+
+export const KASH_PROFILE_BODY_SCHEMA: ObjectSchema = S.object(
+  {
+    handle:      S.optional(S.string({ minLength: 1, maxLength: 64 })),
+    displayName: S.string({ minLength: 1, maxLength: 64 }),
+    bio:         S.optional(S.string({ maxLength: 280 })),
+    avatar:      S.optional(PROFILE_BLOB_REF),
+    banner:      S.optional(PROFILE_BLOB_REF),
+    pronouns:    S.optional(S.string({ maxLength: 32 })),
+    location:    S.optional(S.string({ maxLength: 64 })),
+    pdsUrls:     S.optional(S.array(S.string({ format: "url" }), { maxItems: 8 })),
+    links:       S.optional(S.array(PROFILE_LINK, { maxItems: 8 })),
+  },
+  ["displayName"],
+);

package/src/registry.ts

@@ -0,0 +1,168 @@
+/**
+ * LexiconRegistry — agnostic storage for Lexicon definitions.
+ *
+ * The registry holds a map of Lexicon IDs (NSID@semver) to schema definitions.
+ * It is **empty by default**: no Identity, Social, or Trade lexicons are
+ * pre-registered. Consumers explicitly register a Standard Library or load
+ * Extensions at bootstrap time (see `./engine.ts` and the Standard Library /
+ * Extension exports).
+ *
+ * The class does ZERO validation work itself — it just stores and resolves.
+ * Validation is performed by `validateEvent` (see `./engine.ts`) which
+ * accepts a registry as a parameter. This decoupling preserves the
+ * Box-vs-Content separation: the registry (Box) never knows about any
+ * specific domain (Content).
+ */
+
+import type { Schema } from "./schema";
+import { compareSemver, isForwardCompatible, parseLexiconId, type Semver } from "./semver";
+
+/** A single lexicon definition held in the registry. */
+export interface LexiconDef {
+  /** Full Lexicon ID — e.g., "kash.id.profile@1.0.0". */
+  readonly id: string;
+  /** NSID portion — e.g., "kash.id.profile". */
+  readonly nsid: string;
+  /** Semver of this definition. */
+  readonly semver: Semver;
+  /** Schema for the envelope body. */
+  readonly bodySchema: Schema;
+  /** Optional human-readable title (shown by tooling). */
+  readonly title?: string;
+  /** Optional human-readable description (shown by tooling). */
+  readonly description?: string;
+}
+
+/** Options accepted by the `register(id, schema, opts)` convenience overload. */
+export interface RegisterOptions {
+  readonly title?: string;
+  readonly description?: string;
+}
+
+/**
+ * In-memory map of registered lexicons.
+ *
+ * Multiple major versions for the same NSID may co-exist. The registry
+ * resolves by exact match first, then by forward-compatible major.
+ */
+export class LexiconRegistry {
+  private readonly byId: Map<string, LexiconDef> = new Map();
+  private readonly byNsid: Map<string, LexiconDef[]> = new Map();
+
+  /** Number of registered definitions. */
+  get size(): number {
+    return this.byId.size;
+  }
+
+  /** Register a fully-described lexicon entry. */
+  register(entry: LexiconDef): this;
+  /** Register by Lexicon ID + body schema (convenience overload). */
+  register(id: string, bodySchema: Schema, opts?: RegisterOptions): this;
+  register(arg1: LexiconDef | string, arg2?: Schema, arg3?: RegisterOptions): this {
+    if (typeof arg1 === "string") {
+      if (arg2 === undefined) {
+        throw new TypeError("LexiconRegistry.register(id, schema): schema is required");
+      }
+      const parsed = parseLexiconId(arg1);
+      if (parsed === null) {
+        throw new TypeError(`LexiconRegistry.register: invalid lexicon ID "${arg1}"`);
+      }
+      const entry: LexiconDef = {
+        id: arg1,
+        nsid: parsed.nsid,
+        semver: parsed.semver,
+        bodySchema: arg2,
+        ...(arg3?.title !== undefined ? { title: arg3.title } : {}),
+        ...(arg3?.description !== undefined ? { description: arg3.description } : {}),
+      };
+      return this.addEntry(entry);
+    }
+    return this.addEntry(arg1);
+  }
+
+  /** Register a batch of entries (typically a Standard Library or Extension export). */
+  registerAll(entries: readonly LexiconDef[]): this {
+    for (const entry of entries) this.addEntry(entry);
+    return this;
+  }
+
+  /** Exact-match lookup by full Lexicon ID. Returns undefined when not present. */
+  get(id: string): LexiconDef | undefined {
+    return this.byId.get(id);
+  }
+
+  /**
+   * Forward-compatible lookup by NSID + caller-supplied semver.
+   * Returns the highest-version registered entry whose major matches the caller.
+   */
+  resolve(nsid: string, semver: Semver): LexiconDef | undefined {
+    const candidates = this.byNsid.get(nsid);
+    if (!candidates) return undefined;
+    for (const def of candidates) {
+      if (isForwardCompatible(def.semver, semver)) return def;
+    }
+    return undefined;
+  }
+
+  /** True if any version of the given NSID is registered. */
+  has(nsid: string): boolean {
+    return this.byNsid.has(nsid);
+  }
+
+  /** True if the exact Lexicon ID is registered. */
+  hasId(id: string): boolean {
+    return this.byId.has(id);
+  }
+
+  /** All registered Lexicon IDs, in insertion order. */
+  list(): readonly string[] {
+    return Array.from(this.byId.keys());
+  }
+
+  /** All registered entries. */
+  entries(): readonly LexiconDef[] {
+    return Array.from(this.byId.values());
+  }
+
+  /** All NSIDs present in the registry. */
+  namespaces(): readonly string[] {
+    return Array.from(this.byNsid.keys());
+  }
+
+  /** Drop every registered entry. */
+  clear(): void {
+    this.byId.clear();
+    this.byNsid.clear();
+  }
+
+  /** Remove a single entry by its full Lexicon ID. Returns whether anything was removed. */
+  unregister(id: string): boolean {
+    const entry = this.byId.get(id);
+    if (!entry) return false;
+    this.byId.delete(id);
+    const list = this.byNsid.get(entry.nsid);
+    if (list) {
+      const next = list.filter((e) => e.id !== id);
+      if (next.length === 0) this.byNsid.delete(entry.nsid);
+      else this.byNsid.set(entry.nsid, next);
+    }
+    return true;
+  }
+
+  /* ── internal ─────────────────────────────────────────────────── */
+
+  private addEntry(entry: LexiconDef): this {
+    this.byId.set(entry.id, entry);
+    const list = this.byNsid.get(entry.nsid);
+    if (list) {
+      // remove any existing entry with the same full ID, then re-insert sorted descending
+      const next = list.filter((e) => e.id !== entry.id);
+      next.push(entry);
+      next.sort((a, b) => compareSemver(b.semver, a.semver));
+      this.byNsid.set(entry.nsid, next);
+    } else {
+      this.byNsid.set(entry.nsid, [entry]);
+    }
+    return this;
+  }
+}