@standards/schema 0.0.0-stage → 1.0.0-alpha.382

package/dist/object-Dzl7sfq8.mjs

@@ -0,0 +1,4 @@
+/*! © 2025-2026 AND YOU CREATE SAS (RCS Paris 940 190 614). Proprietary — see LICENSE (Standards SDK License 1.0). */
+import{ValidationError as e}from"./exceptions.mjs";import{t}from"./text-C8Lb-NFo.mjs";import{n,t as r}from"./core-BLHhNykL.mjs";import{createNumberValidator as i}from"./validation/primitives/number.mjs";import{createCheckboxValidator as a}from"./validation/primitives/checkbox.mjs";import{createDateValidator as o}from"./validation/primitives/date.mjs";import{createCurrencyValidator as s}from"./validation/complex/currency.mjs";import{createLocationValidator as c}from"./validation/complex/location.mjs";import{t as l}from"./phone-Bca_xiOX.mjs";import{createRelationValidator as u}from"./validation/complex/relation.mjs";import{createRichtextValidator as d}from"./validation/complex/richtext.mjs";import{createMultiselectValidator as f,createSelectValidator as p,createStatusValidator as m}from"./validation/complex/select.mjs";import{createUserValidator as h}from"./validation/complex/user.mjs";import{createFormulaValidator as g}from"./validation/computed/formula.mjs";import{createRollupValidator as _}from"./validation/computed/rollup.mjs";import{z as v}from"zod";function isNullishOrEmptyString(e){return e==null||e===``}function isValuePresent(e){return e==null?!1:typeof e==`string`?e.trim()!==``:!Array.isArray(e)||e.length>0}const y={phone:[`countryCode`]};function isEmptyValue(e,t=[]){return e==null||typeof e==`string`&&e.trim()===``?!0:e instanceof Date?!1:typeof e==`object`&&!Array.isArray(e)&&Object.entries(e).filter(([e])=>!t.includes(e)).every(([,e])=>e==null||typeof e==`string`&&e.trim()===``)}function withEmptyToNull(e,t){return v.preprocess(e=>isEmptyValue(e,t)?null:e,e.nullish())}function createAttributeValidator(e,r=n){switch(e.type){case`text`:return t(e,r);case`richtext`:return d(e,r);case`number`:return i(e,r);case`checkbox`:return a(e,r);case`date`:return o(e,r);case`phone`:return l(e,r);case`currency`:return s(e,r);case`status`:return m(e,r);case`location`:return c(e,r);case`select`:return p(e,r);case`multiselect`:return f(e,r);case`user`:return h(e,r);case`relation`:return u(e,r);case`formula`:return g(e,r);case`rollup`:return _(e,r);default:return v.unknown()}}function createFormAttributeValidator(e,t=n){let r=createAttributeValidator(e,t);return e.required?r:withEmptyToNull(r,y[e.type])}const b=new WeakMap,x=new WeakMap;function createObjectValidator(e){let t=b.get(e);if(t)return t;let r={};for(let t of e.attributes){let e=createAttributeValidator(t);t.required?r[t.name]=e.refine(isValuePresent,{message:n.required(t)}):r[t.name]=withEmptyToNull(e,y[t.type])}let i=v.object(r).passthrough();return b.set(e,i),i}function createDraftValidator(e){let t=x.get(e);if(t)return t;let n={};for(let t of e.attributes){let e=createAttributeValidator(t);n[t.name]=withEmptyToNull(e,y[t.type])}let r=v.object(n).passthrough();return x.set(e,r),r}function validateAttribute(e,t){let n=createAttributeValidator(e);if(!e.required&&t==null)return{success:!0,data:{[e.name]:t}};let i=n.safeParse(t);return i.success?{success:!0,data:{[e.name]:i.data}}:{success:!1,errors:r(i.error).map(t=>({path:[e.name,...t.path],message:t.message}))}}function validateObject(e,t){let n=createObjectValidator(e).safeParse(t);return n.success?{success:!0,data:n.data}:{success:!1,errors:r(n.error)}}function validateObjectOrThrow(t,n){let r=validateObject(t,n);if(!r.success){let n=r.errors??[],i=n.map(e=>`${e.path.join(`.`)}: ${e.message}`).join(`
+`)||`Unknown validation error`;throw new e(`Validation failed for ${t.label}:\n${i}`,n.map(e=>({path:e.path,message:e.message})))}return r.data}function validateDraft(e,t){let n=createDraftValidator(e).safeParse(t);return n.success?{success:!0,data:n.data}:{success:!1,errors:r(n.error)}}function validateDraftOrThrow(t,n){let r=validateDraft(t,n);if(!r.success){let n=r.errors??[],i=n.map(e=>`${e.path.join(`.`)}: ${e.message}`).join(`
+`)||`Unknown validation error`;throw new e(`Draft validation failed for ${t.label}:\n${i}`,n.map(e=>({path:e.path,message:e.message})))}return r.data}function rejectUnknownAttributesOrThrow(t,n){let r=new Set(t.attributes.map(e=>e.name)),i=Object.keys(n).filter(e=>!r.has(e));if(i.length>0)throw new e(`Unknown attribute${i.length>1?`s`:``} for ${t.label}: ${i.join(`, `)}`,i.map(e=>({path:[e],message:`Unknown attribute`})))}function getMissingRequiredAttributes(e,t){let n=[];for(let r of e.attributes)r.required&&!isValuePresent(t[r.name])&&n.push(r);return n}function isRecordComplete(e,t){return getMissingRequiredAttributes(e,t).length>0?!1:validateObject(e,t).success}export{validateDraft as a,validateObjectOrThrow as c,createAttributeValidator as d,createFormAttributeValidator as f,isValuePresent as h,validateAttribute as i,createDraftValidator as l,isNullishOrEmptyString as m,isRecordComplete as n,validateDraftOrThrow as o,isEmptyValue as p,rejectUnknownAttributesOrThrow as r,validateObject as s,getMissingRequiredAttributes as t,createObjectValidator as u};

package/dist/objects-B4DgFZ82.d.ts

@@ -0,0 +1,398 @@
+
+import { r as Uuid } from "./utils-B7Dlrtnx.js";
+import { n as Attribute } from "./attributes-kAhQzg8-.js";
+import { ColorId, IconName } from "@standards/constants";
+//#region src/types/appearance.d.ts
+/** Icon used when neither the entity nor its parent has one. */
+declare const DEFAULT_APPEARANCE_ICON: IconName;
+declare const IMAGE_SHAPES: readonly ["circle", "square"];
+type ImageShape = (typeof IMAGE_SHAPES)[number];
+/** The one appearance shape: every entity stores the facets it accepts. */
+interface Appearance {
+  icon?: IconName;
+  color?: ColorId;
+  imageFileId?: Uuid;
+}
+type AppearanceFacet = "icon" | "color" | "image";
+type AppearanceEntity = "object" | "record" | "emailCategory" | "option" | "view" | "agent" | "user";
+declare const APPEARANCE_FACETS: Record<AppearanceEntity, readonly AppearanceFacet[]>;
+type ResolvedAppearance = {
+  kind: "image";
+  imageFileId: Uuid;
+  shape: ImageShape;
+} | {
+  kind: "tile";
+  icon: IconName;
+  color: ColorId;
+} | {
+  kind: "glyph";
+  icon: IconName;
+};
+type Named = Appearance & {
+  name?: string;
+};
+/** Image wins; else an icon in a colour (own, parent's or derived from the name) is a tile, without colour a glyph. */
+declare function resolveAppearance(entity: Named, parent?: Named & {
+  imageShape?: ImageShape;
+}): ResolvedAppearance;
+//#endregion
+//#region src/types/document-layout.d.ts
+interface DocumentLayout {
+  /** Dev-declared folder structures the user can instantiate via the UI inside a record's drive. */
+  presets?: FolderPreset[];
+}
+interface FolderPreset {
+  id: string;
+  label: string;
+  icon?: IconName;
+  description?: string;
+  structure: PresetNode[];
+  /** When true, this preset is auto-instantiated on every new record's drive for the owning object. */
+  autoInstantiate?: boolean;
+}
+interface PresetNode {
+  title: string;
+  description?: string;
+  children?: PresetNode[];
+}
+/** Max depth allowed for preset.structure to keep instantiation predictable. */
+declare const MAX_PRESET_DEPTH = 5;
+//#endregion
+//#region src/types/record-access.d.ts
+/**
+ * Every role a resource access grant can carry, weakest first (spec
+ * 2026-10-08 §3.2): `reader` sees, `runner` also uses (agents only),
+ * `editor` also modifies and manages the grants.
+ */
+declare const ACCESS_ROLES: readonly ["reader", "runner", "editor"];
+type AccessRole = (typeof ACCESS_ROLES)[number];
+/** Roles a record access grant can carry (spec 2026-09-25 §5.1): a record is never "used". */
+declare const RECORD_ACCESS_ROLES: readonly ["reader", "editor"];
+type RecordAccessRole = (typeof RECORD_ACCESS_ROLES)[number];
+/**
+ * Why a grant exists — the equivalent of Salesforce's `RowCause` (spec §3):
+ * automatic grants are recomputed without ever touching manual shares.
+ */
+declare const RECORD_ACCESS_SOURCES: readonly ["manual", "meeting_attendee"];
+type RecordAccessSource = (typeof RECORD_ACCESS_SOURCES)[number];
+/**
+ * Agent-internal objects whose records are never shared (spec 2026-09-25
+ * §5.3.4): the memory resolver reads "private and visible" as "mine", and an
+ * extraction could rewrite another member's memory through an `editor` grant.
+ * A constant in v1 — a definition flag would mean editing native objects. The
+ * server refuses them; the UI hides the share control for them.
+ */
+declare const UNSHAREABLE_OBJECT_NAMES: ReadonlySet<string>;
+/** What the reading actor may do with a resource (spec §6.6); records never produce `runner`. */
+type ViewerAccess = "owner" | "editor" | "runner" | "reader" | "workspace";
+/** One beneficiary of a private resource: its effective role and every source that grants it. */
+interface ResourceAccessGrant<TRole extends AccessRole = AccessRole, TSource extends string = RecordAccessSource> {
+  actorId: Uuid;
+  role: TRole;
+  sources: TSource[];
+}
+/** One beneficiary of a private record (shape unchanged since 2026-09-25, D11). */
+type RecordAudienceGrant = ResourceAccessGrant<RecordAccessRole, RecordAccessSource>;
+/** Who can reach a record beyond its owner (`GET /records/:object/:id/access`). */
+interface RecordAudience {
+  recordId: Uuid;
+  visibility: ResourceVisibility;
+  ownedBy: Uuid | null;
+  /** The caller's own level; additive (D11), always sent by the server. */
+  viewerAccess?: ViewerAccess;
+  grants: RecordAudienceGrant[];
+}
+/** Who can reach an agent definition beyond its owner (`GET /agents/definitions/:id/access`). */
+interface AgentDefinitionAudience {
+  definitionId: string;
+  visibility: ResourceVisibility;
+  ownedBy: Uuid | null;
+  viewerAccess: ViewerAccess;
+  /** Agents only carry manual grants (spec §3.1). */
+  grants: ResourceAccessGrant<AccessRole, "manual">[];
+}
+/** Who can reach a private page beyond its owner (`GET /pages/:id/access`). */
+interface PageAudience {
+  pageId: Uuid;
+  visibility: ResourceVisibility;
+  ownedBy: Uuid | null;
+  viewerAccess: ViewerAccess;
+  /** Pages only carry manual grants (screens spec § 8). */
+  grants: ResourceAccessGrant<RecordAccessRole, "manual">[];
+}
+/** The resource an access operation addresses. */
+type ResourceAccessTarget = {
+  kind: "record";
+  object: string;
+  id: string;
+} | {
+  kind: "agent_definition";
+  id: string;
+} | {
+  kind: "page";
+  id: string;
+};
+/** Narrow an untrusted value (HTTP body, CLI flag) to a record grant role. */
+declare function parseRecordAccessRole(value: unknown): RecordAccessRole;
+/** Narrow an untrusted value to an agent definition grant role. */
+declare function parseAgentDefinitionAccessRole(value: unknown): AccessRole;
+/** Narrow an untrusted value to a page grant role: a page is read or edited, never "used". */
+declare function parsePageAccessRole(value: unknown): RecordAccessRole;
+/**
+ * The single derivation of `viewerAccess`, from the row's owner and the
+ * `viewer_grant` storage computed FOR this viewer. A private resource that is
+ * neither owned nor granted can only have been read by the system reader,
+ * which reads and never writes: `reader`.
+ */
+declare function deriveViewerAccess(resource: {
+  visibility: ResourceVisibility;
+  ownedBy: string | null;
+  viewerGrant?: AccessRole | null;
+}, actorIds: readonly string[]): ViewerAccess;
+//#endregion
+//#region src/types/objects.d.ts
+/** Visibility scopes shared by resources that can be workspace-wide or actor-private. */
+declare const RESOURCE_VISIBILITIES: readonly ["workspace", "private"];
+type ResourceVisibility = (typeof RESOURCE_VISIBILITIES)[number];
+/**
+ * Scope a list-view tab reads. Deliberately a SEPARATE union from
+ * {@link ResourceVisibility}: a stored resource is always exactly one of
+ * `workspace` or `private`, while a tab may also read across both.
+ *
+ * `all` is not a third resource state — it means "impose no scope", so the tab
+ * returns whatever the mandatory viewer predicate already allows. `shared` is
+ * not one either: it reads the private resources other members shared with
+ * the viewer (spec 2026-10-08 §5). Never assign a tab scope to a record's
+ * `visibility` column.
+ */
+declare const LIST_VIEW_TAB_VISIBILITIES: readonly ["all", "workspace", "private", "shared"];
+type ListViewTabVisibility = (typeof LIST_VIEW_TAB_VISIBILITIES)[number];
+/** The exact scope a record list query may impose: a visibility, or `shared` (owned by someone else, granted to me). */
+declare const RECORD_LIST_SCOPES: readonly ["workspace", "private", "shared"];
+type RecordListScope = (typeof RECORD_LIST_SCOPES)[number];
+/** Narrow an untrusted list scope (HTTP body) or reject it — `all` is a tab value, never a query scope. */
+declare function parseRecordListScope(value: unknown): RecordListScope;
+/**
+ * Narrow an untrusted value from an edge (HTTP body, CLI flag) to a
+ * {@link ResourceVisibility}, or reject it.
+ *
+ * It lives beside the union so that whoever changes the union sees the one
+ * gate that admits values into it. Every edge had grown its own copy, and the
+ * one edge that instead trusted a `@IsIn` decorator had no gate at all: the
+ * API host installs a zod-only global pipe, so class-validator DTOs never ran
+ * and `"all"` — a real member of the sibling {@link ListViewTabVisibility}
+ * union, so the first thing a confused client sends — reached the visibility
+ * state machine as a 404, and Postgres as a SQLSTATE 22023 (#1715).
+ *
+ * Throws {@link ValidationError} rather than a transport exception so it can
+ * be used below the controller layer; the HTTP filter maps its code to 400.
+ */
+declare function parseResourceVisibility(value: unknown): ResourceVisibility;
+/**
+ * Timestamps for tracking creation and updates
+ */
+interface Timestamps {
+  createdAt: Date;
+  updatedAt: Date;
+}
+/**
+ * Object definition - Represents a database table/entity
+ */
+interface ObjectDefinition {
+  id?: Uuid;
+  name: string;
+  label: string;
+  pluralLabel?: string;
+  description?: string;
+  icon?: IconName;
+  color?: ColorId;
+  /** How the images of this object's records are cropped. */
+  imageShape?: ImageShape;
+  /**
+   * Template expression used to compute the object's display label.
+   * Supports variable interpolation and pipes for formatting.
+   *
+   * @example
+   * ```typescript
+   * // Simple attribute reference
+   * labelExpression: "{{ name }}"
+   *
+   * // Multiple attributes
+   * labelExpression: "{{ firstName }} {{ lastName }}"
+   *
+   * // With pipes for formatting
+   * labelExpression: "{{ code | UPPER }} - {{ name | capitalize }}"
+   * ```
+   *
+   * Available pipes: UPPER, LOWER, capitalize, trim
+   */
+  labelExpression: string;
+  /**
+   * Optional template expression used to compute the semantic text sent to
+   * Meilisearch for vector generation. When absent, records opt out of semantic
+   * embedding generation.
+   */
+  embeddingExpression?: string;
+  attributes: Attribute[];
+  system?: boolean;
+  /**
+   * If true, no custom (user-created) attributes are allowed on this object.
+   * `standards diff` will report an error if any custom attribute is found.
+   * Use .sealed() on the ObjectBuilder to set this.
+   */
+  sealed?: boolean;
+  /**
+   * List of custom attribute names explicitly acknowledged by the developer.
+   * On a sealed object, these names will NOT trigger a CI failure.
+   * On an extensible object, this is purely documentary.
+   * Use .tolerate(["name"]) on the ObjectBuilder to set this.
+   */
+  toleratedAttributes?: string[];
+  metadata?: Record<string, unknown>;
+  /** Smart-folder layout convention for documents attached to records of this object. */
+  documentLayout?: DocumentLayout;
+}
+/**
+ * Links an attribute to an object
+ */
+interface ObjectAttribute {
+  objectId: Uuid;
+  attributeId: Uuid;
+  order?: number;
+  required?: boolean;
+}
+/** A record's own icon and image file (`APPEARANCE_FACETS.record`); each key is absent when unset. */
+type RecordAppearance = Pick<Appearance, "icon" | "imageFileId">;
+/**
+ * Record - Instance of an Object (a row in the database)
+ */
+interface ObjectRecord<TValues extends Record<string, unknown> = Record<string, unknown>> extends Timestamps {
+  id: Uuid;
+  objectId: Uuid;
+  /**
+   * Name of the owning object. Present on every row read through the repository
+   * (`object_records.object_name` is denormalized and always selected), absent
+   * on records built in memory before a write.
+   */
+  objectName?: string;
+  /** Workspace-wide or owner-private visibility enforced by repository queries. */
+  visibility: ResourceVisibility;
+  /** Owning actor for private records; always null for workspace records. */
+  ownedBy: Uuid | null;
+  /**
+   * What the reading actor may do with this record (spec §6.6): its owner,
+   * an editor or reader by grant, or any member of a workspace record.
+   * Computed for the viewer that read the row; absent on records built in
+   * memory and on rows read without a viewer. Never broadcast nor indexed.
+   */
+  viewerAccess?: ViewerAccess;
+  /**
+   * Display label computed from the object's labelExpression.
+   * Computed dynamically based on record values.
+   *
+   * @example "John Doe" (from "{{ firstName }} {{ lastName }}")
+   */
+  label: string;
+  /**
+   * Semantic text computed from the object's embeddingExpression and persisted
+   * for Meilisearch documentTemplate-based vector generation.
+   */
+  embeddingText?: string;
+  /**
+   * The record's own icon and image (a `files` row id; clients compose
+   * `{publicFilesUrl}/{imageFileId}`). Absent when it has neither: the record
+   * then shows its object's appearance.
+   */
+  appearance?: RecordAppearance;
+  values: TValues;
+  /**
+   * Custom metadata for the record.
+   * Use this for UI/UX state, feature flags, or any application-specific data.
+   * Unlike system fields (id, createdAt, updatedAt), metadata can be updated.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Soft delete timestamp.
+   * If set, the record is considered deleted but can be restored.
+   * Queries exclude soft-deleted records by default.
+   */
+  deletedAt?: Date | null;
+  /**
+   * Actor ID who soft-deleted this record.
+   * Set alongside deletedAt when a record is soft-deleted.
+   */
+  deletedBy?: string | null;
+  /**
+   * Actor ID who created this record.
+   * Automatically set by RecordService when actorId is configured.
+   * Optional for backward compatibility with existing records.
+   */
+  createdBy?: string;
+  /**
+   * Actor ID who last updated this record.
+   * Automatically set by RecordService when actorId is configured.
+   * Optional for backward compatibility with existing records.
+   */
+  lastUpdatedBy?: string;
+  /** Monotonic record version: moves on every stored change, computed recalculations included. */
+  version?: number;
+  /**
+   * Storage-managed compare-and-set token the engine's own writers retry on.
+   * Not part of the API contract: no route accepts it as a precondition (a
+   * write's precondition is an operation step's `base`); read `version`.
+   * @internal
+   */
+  writeVersion?: number;
+  /** Schema version at the time this record was last migrated */
+  schemaVersion: number;
+}
+/**
+ * System-managed field names on ObjectRecord.
+ * These are stored as SQL columns (not in JSONB `values`).
+ *
+ * Use this in adapters to determine if a filter/sort attribute is a table column
+ * vs. a JSONB value field.
+ *
+ * @example
+ * ```typescript
+ * if (SYSTEM_FIELD_NAMES.includes(filter.attribute)) {
+ *   // Filter on SQL column (e.g., WHERE created_at > ...)
+ * } else {
+ *   // Filter on JSONB field (e.g., WHERE values->>'name' = ...)
+ * }
+ * ```
+ */
+declare const SYSTEM_FIELD_NAMES: readonly ["id", "createdAt", "updatedAt", "createdBy", "lastUpdatedBy", "visibility", "ownedBy"];
+/**
+ * Type for system field names
+ */
+type SystemFieldName = (typeof SYSTEM_FIELD_NAMES)[number];
+/**
+ * Reserved attribute names that cannot be used for custom attributes.
+ * These names conflict with ObjectRecord properties.
+ *
+ * Includes:
+ * - System fields (id, timestamps, actor audit fields, visibility, ownership)
+ * - Other ObjectRecord properties (objectId, label, values, metadata, deletedAt)
+ *
+ * @example
+ * ```typescript
+ * if (RESERVED_ATTRIBUTE_NAMES.includes(attributeName)) {
+ *   throw new Error(`"${attributeName}" is a reserved name`);
+ * }
+ * ```
+ */
+declare const RESERVED_ATTRIBUTE_NAMES: readonly ["id", "createdAt", "updatedAt", "createdBy", "lastUpdatedBy", "visibility", "ownedBy", "objectId", "label", "embeddingText", "values", "metadata", "deletedAt", "deletedBy", "schemaVersion", "appearance", "owned_by"];
+/**
+ * Type for reserved attribute names
+ */
+type ReservedAttributeName = (typeof RESERVED_ATTRIBUTE_NAMES)[number];
+/**
+ * Reserved object names: every framework-native object. They cannot be used
+ * for user-created (runtime) objects, nor declared by a consumer's builder,
+ * registry entry, bundle or schema source — see `native/names.ts`.
+ */
+declare const RESERVED_OBJECT_NAMES: readonly ["skill", "memory", "drives", "artifact", "meeting"];
+type ReservedObjectName = (typeof RESERVED_OBJECT_NAMES)[number];
+//#endregion
+export { ResourceAccessGrant as A, MAX_PRESET_DEPTH as B, PageAudience as C, RecordAccessSource as D, RecordAccessRole as E, parseAgentDefinitionAccessRole as F, AppearanceFacet as G, APPEARANCE_FACETS as H, parsePageAccessRole as I, ImageShape as J, DEFAULT_APPEARANCE_ICON as K, parseRecordAccessRole as L, UNSHAREABLE_OBJECT_NAMES as M, ViewerAccess as N, RecordAudience as O, deriveViewerAccess as P, DocumentLayout as R, AgentDefinitionAudience as S, RECORD_ACCESS_SOURCES as T, Appearance as U, PresetNode as V, AppearanceEntity as W, resolveAppearance as X, ResolvedAppearance as Y, Timestamps as _, ObjectRecord as a, ACCESS_ROLES as b, RESERVED_OBJECT_NAMES as c, RecordListScope as d, ReservedAttributeName as f, SystemFieldName as g, SYSTEM_FIELD_NAMES as h, ObjectDefinition as i, ResourceAccessTarget as j, RecordAudienceGrant as k, RESOURCE_VISIBILITIES as l, ResourceVisibility as m, ListViewTabVisibility as n, RECORD_LIST_SCOPES as o, ReservedObjectName as p, IMAGE_SHAPES as q, ObjectAttribute as r, RESERVED_ATTRIBUTE_NAMES as s, LIST_VIEW_TAB_VISIBILITIES as t, RecordAppearance as u, parseRecordListScope as v, RECORD_ACCESS_ROLES as w, AccessRole as x, parseResourceVisibility as y, FolderPreset as z };