diff --git a/content/docs/references/api/discovery.mdx b/content/docs/references/api/discovery.mdx index 717b1f8681..bb4273fa11 100644 --- a/content/docs/references/api/discovery.mdx +++ b/content/docs/references/api/discovery.mdx @@ -5,16 +5,6 @@ description: Discovery protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Service Status Enum -Describes the operational state of a service in the discovery response. - -- `available` – Fully operational: service is registered AND HTTP handler is verified. -- `registered` – Route is declared in the dispatcher table but the HTTP handler has - not been verified (may 501 at runtime). -- `unavailable` – Service is not installed / not registered in the kernel. -- `degraded` – Partially working (e.g., in-memory fallback, missing persistence). -- `stub` – Placeholder handler that always returns 501 Not Implemented. - **Source:** `packages/spec/src/api/discovery.zod.ts` diff --git a/content/docs/references/api/endpoint.mdx b/content/docs/references/api/endpoint.mdx index 5bdfc27191..ca852a8c5c 100644 --- a/content/docs/references/api/endpoint.mdx +++ b/content/docs/references/api/endpoint.mdx @@ -5,9 +5,6 @@ description: Endpoint protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -API Mapping Schema -Transform input/output data. - **Source:** `packages/spec/src/api/endpoint.zod.ts` diff --git a/content/docs/references/api/events.mdx b/content/docs/references/api/events.mdx index c3179c9ee2..f97a8ad110 100644 --- a/content/docs/references/api/events.mdx +++ b/content/docs/references/api/events.mdx @@ -5,16 +5,6 @@ description: Events protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Metadata Event Types - -Triggered when metadata items are created, updated, or deleted. -Follows the pattern: `metadata.{type}.{action}` - -Examples: -- `metadata.object.created` - A new object was created -- `metadata.view.updated` - A view was updated -- `metadata.agent.deleted` - An agent was deleted - **Source:** `packages/spec/src/api/events.zod.ts` diff --git a/content/docs/references/automation/flow.mdx b/content/docs/references/automation/flow.mdx index 2db25b42bb..ab7627bba1 100644 --- a/content/docs/references/automation/flow.mdx +++ b/content/docs/references/automation/flow.mdx @@ -5,18 +5,6 @@ description: Flow protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Flow Node Types — **built-in seed set** (ADR-0018). - -Historically this `z.enum` *gated* `FlowNodeSchema.type`, which made the -closed protocol reject any plugin-registered node type — defeating the open -runtime registry (`registerNodeExecutor(type: string)`). Per ADR-0018 the -gate is removed: `FlowNodeSchema.type` is now a validated `string`, checked -against the live action registry at `registerFlow()` time, not frozen here. - -`FlowNodeAction` is **retained** as the canonical list of built-in type ids -(documentation + the seed descriptor set the engine registers at boot). It -no longer constrains authored flows — plugins extend the vocabulary. - **Source:** `packages/spec/src/automation/flow.zod.ts` diff --git a/content/docs/references/automation/webhook.mdx b/content/docs/references/automation/webhook.mdx index 84d9bc4574..eadd72c264 100644 --- a/content/docs/references/automation/webhook.mdx +++ b/content/docs/references/automation/webhook.mdx @@ -5,37 +5,6 @@ description: Webhook protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Webhook Trigger Event -When should this webhook fire? - -These mirror the record events the engine actually emits -(`data.record.created` / `updated` / `deleted`), which the webhook -auto-enqueuer maps to `create` / `update` / `delete`. Only events with a real -producer are declared here — an author can't subscribe to something that -never fires. - -**Bulk triggers (#4639).** `bulk_update` / `bulk_delete` map to the engine's -aggregate `data.records.updated` / `data.records.deleted`, emitted when a -predicate write (`multi: true` → `IDataDriver.updateMany`/`deleteMany`) -affects a set of rows the driver reports only as a count. They are separate -trigger values, not extra sources for `update` / `delete`, because their -delivery has a different SHAPE: no `recordId`, no record body, just -`object` + `matched`. Folding them into the per-record triggers would send -every existing subscriber a body missing the fields it reads — the same -class of breakage as the pre-#4626 `recordId: ''` fabrication, arriving from -the other direction. A webhook that wants both subscribes to both. - -Deliberately NOT triggers (#3196): -- `undelete` — there is no soft-delete / restore capability in the engine - (`delete` is a hard delete; no `deleted_at` convention, no restore - operation, no `data.record.undeleted` emit), so it had no event source. - Reintroduce it only alongside a real restore subsystem that emits an - undelete event. -- `api` (manual/programmatic fire) — no manual fire path exists (the only - webhook HTTP surface re-queues already-failed deliveries). Reintroduce it - with a real "fire this webhook now" endpoint/service, not as a bare enum - value that silently never fires. - **Source:** `packages/spec/src/automation/webhook.zod.ts` diff --git a/content/docs/references/data/document.mdx b/content/docs/references/data/document.mdx index d3404cb7d1..41572995b2 100644 --- a/content/docs/references/data/document.mdx +++ b/content/docs/references/data/document.mdx @@ -5,24 +5,6 @@ description: Document protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Document Version Schema - -Represents a single version of a document in a version-controlled system. -Each version is immutable and maintains its own metadata and download URL. - -@example -```json -{ - "versionNumber": 2, - "createdAt": 1704067200000, - "createdBy": "user_123", - "size": 2048576, - "checksum": "a1b2c3d4e5f6", - "downloadUrl": "https://storage.example.com/docs/v2/file.pdf", - "isLatest": true -} -``` - **Source:** `packages/spec/src/data/document.zod.ts` diff --git a/content/docs/references/data/driver-nosql.mdx b/content/docs/references/data/driver-nosql.mdx index 8f7ba998db..7c8a2d349d 100644 --- a/content/docs/references/data/driver-nosql.mdx +++ b/content/docs/references/data/driver-nosql.mdx @@ -5,9 +5,6 @@ description: Driver Nosql protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -NoSQL Database Type Enumeration -Supported NoSQL database types - **Source:** `packages/spec/src/data/driver-nosql.zod.ts` diff --git a/content/docs/references/data/driver-sql.mdx b/content/docs/references/data/driver-sql.mdx index 95a938b05c..41d220d345 100644 --- a/content/docs/references/data/driver-sql.mdx +++ b/content/docs/references/data/driver-sql.mdx @@ -5,9 +5,6 @@ description: Driver Sql protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -SQL Dialect Enumeration -Supported SQL database dialects - **Source:** `packages/spec/src/data/driver-sql.zod.ts` diff --git a/content/docs/references/data/driver.mdx b/content/docs/references/data/driver.mdx index bef63bfd7c..b4b8d5f56c 100644 --- a/content/docs/references/data/driver.mdx +++ b/content/docs/references/data/driver.mdx @@ -5,9 +5,6 @@ description: Driver protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Common Driver Options -Passed to most driver methods to control behavior (transactions, timeouts, etc.) - **Source:** `packages/spec/src/data/driver.zod.ts` diff --git a/content/docs/references/data/field.mdx b/content/docs/references/data/field.mdx index fc5369a127..2912326555 100644 --- a/content/docs/references/data/field.mdx +++ b/content/docs/references/data/field.mdx @@ -5,8 +5,6 @@ description: Field protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Field Type Enum - **Source:** `packages/spec/src/data/field.zod.ts` diff --git a/content/docs/references/data/object.mdx b/content/docs/references/data/object.mdx index 284921c61a..08c4e88dba 100644 --- a/content/docs/references/data/object.mdx +++ b/content/docs/references/data/object.mdx @@ -5,8 +5,6 @@ description: Object protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -API Operations Enum - **Source:** `packages/spec/src/data/object.zod.ts` diff --git a/content/docs/references/data/seed.mdx b/content/docs/references/data/seed.mdx index fed024538f..88a25b1a00 100644 --- a/content/docs/references/data/seed.mdx +++ b/content/docs/references/data/seed.mdx @@ -5,9 +5,6 @@ description: Seed protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Seed Import Strategy -Defines how the engine handles existing records when a seed is applied. - **Source:** `packages/spec/src/data/seed.zod.ts` diff --git a/content/docs/references/identity/position.mdx b/content/docs/references/identity/position.mdx index 7641e31840..2d7524875f 100644 --- a/content/docs/references/identity/position.mdx +++ b/content/docs/references/identity/position.mdx @@ -5,40 +5,6 @@ description: Position protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Position Schema — the flat capability-distribution group (ADR-0090 D3). - -A position (岗位, "job role" in NetSuite/Workday terms) is a **named, -assignable bundle of permission sets**: users hold positions -(`sys_user_position`), positions bind permission sets -(`sys_position_permission_set`), and a user's capability is the union of -every set reached that way plus direct grants. - -Positions are deliberately **flat** — no `parent`, no hierarchy. The -visibility hierarchy lives on the business-unit tree (`sys_business_unit`, -ADR-0057 D2) and the manager chain (`sys_user.manager_id`); re-adding a -second tree here is the mistake ADR-0057 D5 retired and ADR-0090 D3 -finalizes. - -VOCABULARY (ADR-0090 D3): the word "role" is reserved-forbidden across the -platform — capability = permission_set, distribution = position, -hierarchy = business_unit. The sole exception is better-auth's internal -`sys_member.role` (org-membership tier), projected as -`org_membership_level`. - -**NAMING CONVENTION:** -Position names MUST be lowercase snake_case to prevent security issues. - -@example Good position names -- 'sales_manager' -- 'ceo' -- 'region_east_vp' -- 'engineering_lead' - -@example Bad position names (will be rejected) -- 'SalesManager' (camelCase) -- 'CEO' (uppercase) -- 'Region East VP' (spaces and uppercase) - **Source:** `packages/spec/src/identity/position.zod.ts` diff --git a/content/docs/references/kernel/events-bus.mdx b/content/docs/references/kernel/events-bus.mdx index a30957ddc7..dc55194361 100644 --- a/content/docs/references/kernel/events-bus.mdx +++ b/content/docs/references/kernel/events-bus.mdx @@ -5,19 +5,6 @@ description: Events Bus protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Event Bus Configuration Schema -Complete configuration for the event bus system - -@example -\{ - "persistence": \{ "enabled": true, "retention": 365 \}, - "queue": \{ "concurrency": 20 \}, - "eventSourcing": \{ "enabled": true \}, - "webhooks": [], - "messageQueue": \{ "provider": "kafka", "topic": "events" \}, - "realtime": \{ "enabled": true, "protocol": "websocket" \} -\} - **Source:** `packages/spec/src/kernel/events/bus.zod.ts` diff --git a/content/docs/references/kernel/events-core.mdx b/content/docs/references/kernel/events-core.mdx index 756f829cc2..4ecf7fc87f 100644 --- a/content/docs/references/kernel/events-core.mdx +++ b/content/docs/references/kernel/events-core.mdx @@ -5,10 +5,6 @@ description: Events Core protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Event Priority Enum -Priority levels for event processing -Lower numbers = higher priority - **Source:** `packages/spec/src/kernel/events/core.zod.ts` diff --git a/content/docs/references/kernel/events-dlq.mdx b/content/docs/references/kernel/events-dlq.mdx index cb569af9b6..6c1f84cbbc 100644 --- a/content/docs/references/kernel/events-dlq.mdx +++ b/content/docs/references/kernel/events-dlq.mdx @@ -5,9 +5,6 @@ description: Events Dlq protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Dead Letter Queue Entry Schema -Represents a failed event in the dead letter queue - **Source:** `packages/spec/src/kernel/events/dlq.zod.ts` diff --git a/content/docs/references/kernel/events-handlers.mdx b/content/docs/references/kernel/events-handlers.mdx index 2355ebeb0c..b1f1377621 100644 --- a/content/docs/references/kernel/events-handlers.mdx +++ b/content/docs/references/kernel/events-handlers.mdx @@ -5,9 +5,6 @@ description: Events Handlers protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Event Handler Schema -Defines how to handle a specific event - **Source:** `packages/spec/src/kernel/events/handlers.zod.ts` diff --git a/content/docs/references/kernel/events-integrations.mdx b/content/docs/references/kernel/events-integrations.mdx index 8b11fe2929..6b4d6dba5e 100644 --- a/content/docs/references/kernel/events-integrations.mdx +++ b/content/docs/references/kernel/events-integrations.mdx @@ -5,17 +5,6 @@ description: Events Integrations protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Event Webhook Configuration Schema -Configuration for sending events to webhooks - -@example -\{ - "eventPattern": "order.*", - "url": "https://api.example.com/webhooks/orders", - "method": "POST", - "headers": \{ "Authorization": "Bearer token" \} -\} - **Source:** `packages/spec/src/kernel/events/integrations.zod.ts` diff --git a/content/docs/references/kernel/events-queue.mdx b/content/docs/references/kernel/events-queue.mdx index ef9ce7a14d..29aecd6f32 100644 --- a/content/docs/references/kernel/events-queue.mdx +++ b/content/docs/references/kernel/events-queue.mdx @@ -5,19 +5,6 @@ description: Events Queue protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Event Queue Configuration Schema -Configuration for async event processing queue - -@example -\{ - "name": "event_queue", - "concurrency": 10, - "retryPolicy": \{ - "maxRetries": 3, - "backoffStrategy": "exponential" - \} -\} - **Source:** `packages/spec/src/kernel/events/queue.zod.ts` diff --git a/content/docs/references/kernel/execution-context.mdx b/content/docs/references/kernel/execution-context.mdx index c38f9ef8ea..5b5b43b611 100644 --- a/content/docs/references/kernel/execution-context.mdx +++ b/content/docs/references/kernel/execution-context.mdx @@ -5,20 +5,6 @@ description: Execution Context protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Execution Context Schema - -Defines the runtime context that flows from HTTP request → data operations. -This is the "identity + environment" envelope that every data operation can carry. - -Design: -- All fields are optional for backward compatibility -- `isSystem` bypasses permission checks (for internal/migration operations) -- `transaction` carries the database transaction handle for atomicity -- `traceId` enables distributed tracing across microservices - -Usage: - engine.find('account', \{ context: \{ userId: '...', tenantId: '...' \} \}) - **Source:** `packages/spec/src/kernel/execution-context.zod.ts` diff --git a/content/docs/references/security/sharing.mdx b/content/docs/references/security/sharing.mdx index d441a9c2b0..6142a9eb98 100644 --- a/content/docs/references/security/sharing.mdx +++ b/content/docs/references/security/sharing.mdx @@ -5,9 +5,6 @@ description: Sharing protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Organization-Wide Defaults (OWD) -The baseline security posture for an object. - **Source:** `packages/spec/src/security/sharing.zod.ts` diff --git a/content/docs/references/shared/identifiers.mdx b/content/docs/references/shared/identifiers.mdx index 5227ff7c39..1aa860a889 100644 --- a/content/docs/references/shared/identifiers.mdx +++ b/content/docs/references/shared/identifiers.mdx @@ -5,62 +5,6 @@ description: Identifiers protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -System Identifier Schema - -Universal naming convention for all machine identifiers (API Names) in ObjectStack. -Enforces lowercase with underscores or dots to ensure: -- Cross-platform compatibility (case-insensitive filesystems) -- URL-friendliness (no encoding needed) -- Database consistency (no collation issues) -- Security (no case-sensitivity bugs in permission checks) - -**Applies to all metadata that acts as a machine identifier:** -- Object names (tables/collections) -- Field names -- Role names -- Permission set names -- Action/trigger names -- Event keys -- App IDs -- Menu/page IDs -- Select option values -- Workflow names -- Webhook names - -**Naming Convention Summary:** -| Type | Pattern | Example | -|------|---------|---------| -| Machine ID | snake_case | `crm_account`, `btn_submit`, `role_admin` | -| Event keys | dot.notation | `user.login`, `order.created` | -| Labels | Any case | `Client Account`, `Submit Form` | - -**Length ceiling — storage-owned, deliberately not declared here (#12144).** -The identifier schemas in this file declare a floor and a grammar but no -`.max()`: the enforced ceiling on an identifier is the `maxLength` of the -column that stores it (refused at the write seam by ObjectQL's record -validator), and the storing columns disagree — the config-object name -columns (`sys_permission_set.name`, `sys_position.name`, -`sys_capability.name`) enforce 100 while `sys_metadata.name` enforces 255 — -so no single `.max()` here can equal every consumer's enforced ceiling. -Do not add one unless every consuming column agrees on one width: a -`.max()` below the widest storing column refuses names that are legal -stored rows today. The schema↔column link is pinned in -`@objectstack/plugin-security`'s `identifier-storage-ceiling-pin.test.ts`, -which reads the column widths off the registration surface. - -@example Valid identifiers -- 'account' -- 'crm_account' -- 'user_profile' -- 'order.created' (for events) -- 'api_v2_endpoint' - -@example Invalid identifiers (will be rejected) -- 'Account' (uppercase) -- 'CrmAccount' (camelCase) -- 'crm-account' (kebab-case - use underscore instead) -- 'user profile' (spaces) - **Source:** `packages/spec/src/shared/identifiers.zod.ts` diff --git a/content/docs/references/shared/metadata-types.mdx b/content/docs/references/shared/metadata-types.mdx index 60fe1704d4..bacdfc0d40 100644 --- a/content/docs/references/shared/metadata-types.mdx +++ b/content/docs/references/shared/metadata-types.mdx @@ -5,8 +5,6 @@ description: Metadata Types protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Supported metadata file formats - **Source:** `packages/spec/src/shared/metadata-types.zod.ts` diff --git a/content/docs/references/system/auth-config.mdx b/content/docs/references/system/auth-config.mdx index c53769072c..376df47c5b 100644 --- a/content/docs/references/system/auth-config.mdx +++ b/content/docs/references/system/auth-config.mdx @@ -5,11 +5,6 @@ description: Auth Config protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Better-Auth Configuration Protocol - -Defines the configuration required to initialize the Better-Auth kernel. -Used in server-side configuration injection. - **Source:** `packages/spec/src/system/auth-config.zod.ts` diff --git a/content/docs/references/system/change-management.mdx b/content/docs/references/system/change-management.mdx index 2dbcc5ca72..d8a37bbfa7 100644 --- a/content/docs/references/system/change-management.mdx +++ b/content/docs/references/system/change-management.mdx @@ -5,11 +5,6 @@ description: Change Management protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Change Type Enum - -Classification of change requests based on risk and approval requirements. -Follows ITIL change management best practices. - **Source:** `packages/spec/src/system/change-management.zod.ts` diff --git a/content/docs/references/system/disaster-recovery.mdx b/content/docs/references/system/disaster-recovery.mdx index 8be8c1d2ad..b47f173d65 100644 --- a/content/docs/references/system/disaster-recovery.mdx +++ b/content/docs/references/system/disaster-recovery.mdx @@ -5,24 +5,6 @@ description: Disaster Recovery protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Backup Strategy Schema - -Defines backup methods for disaster recovery. - -- **full**: Complete snapshot of all data -- **incremental**: Only changes since last backup -- **differential**: All changes since last full backup - -@example -```typescript -const backup: BackupConfig = { - strategy: 'incremental', - schedule: '0 2 * * *', - retention: { days: 30, minCopies: 3 }, - encryption: { enabled: true, algorithm: 'AES-256-GCM' }, -}; -``` - **Source:** `packages/spec/src/system/disaster-recovery.zod.ts` diff --git a/content/docs/references/system/encryption.mdx b/content/docs/references/system/encryption.mdx index c5a8b85402..1aa03c6476 100644 --- a/content/docs/references/system/encryption.mdx +++ b/content/docs/references/system/encryption.mdx @@ -5,9 +5,6 @@ description: Encryption protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Field-level encryption protocol -GDPR/HIPAA/PCI-DSS compliant - **Source:** `packages/spec/src/system/encryption.zod.ts` diff --git a/content/docs/references/system/job.mdx b/content/docs/references/system/job.mdx index f57c83d188..e60dea07a0 100644 --- a/content/docs/references/system/job.mdx +++ b/content/docs/references/system/job.mdx @@ -5,9 +5,6 @@ description: Job protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Cron Schedule Schema -Schedule jobs using cron expressions - **Source:** `packages/spec/src/system/job.zod.ts` diff --git a/content/docs/references/system/license.mdx b/content/docs/references/system/license.mdx index df8364ff9d..a148a93408 100644 --- a/content/docs/references/system/license.mdx +++ b/content/docs/references/system/license.mdx @@ -5,8 +5,6 @@ description: License protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Metric Type Classification - **Source:** `packages/spec/src/system/license.zod.ts` diff --git a/content/docs/references/system/metadata-persistence.mdx b/content/docs/references/system/metadata-persistence.mdx index 60540a04dd..40b560fe9d 100644 --- a/content/docs/references/system/metadata-persistence.mdx +++ b/content/docs/references/system/metadata-persistence.mdx @@ -5,9 +5,6 @@ description: Metadata Persistence protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Metadata Scope Enum -Defines the lifecycle and mutability of a metadata item. - **Source:** `packages/spec/src/system/metadata-persistence.zod.ts` diff --git a/content/docs/references/system/search-engine.mdx b/content/docs/references/system/search-engine.mdx index 66b98d26d1..0c08a1c9a8 100644 --- a/content/docs/references/system/search-engine.mdx +++ b/content/docs/references/system/search-engine.mdx @@ -5,9 +5,6 @@ description: Search Engine protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Full-text search protocol -Supports Elasticsearch, Algolia, Meilisearch, Typesense - **Source:** `packages/spec/src/system/search-engine.zod.ts` diff --git a/content/docs/references/ui/dashboard.mdx b/content/docs/references/ui/dashboard.mdx index 551b18b503..d4db9721f9 100644 --- a/content/docs/references/ui/dashboard.mdx +++ b/content/docs/references/ui/dashboard.mdx @@ -5,8 +5,6 @@ description: Dashboard protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Color variant for dashboard widgets (e.g., KPI cards). - **Source:** `packages/spec/src/ui/dashboard.zod.ts` diff --git a/content/docs/references/ui/notification.mdx b/content/docs/references/ui/notification.mdx index c1cebd582d..6b43ff25b7 100644 --- a/content/docs/references/ui/notification.mdx +++ b/content/docs/references/ui/notification.mdx @@ -5,9 +5,6 @@ description: Notification protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Notification Type Schema -Defines the visual presentation style of the notification. - **Source:** `packages/spec/src/ui/notification.zod.ts` diff --git a/content/docs/references/ui/report.mdx b/content/docs/references/ui/report.mdx index 2bbd99b179..0fbdcfa1d1 100644 --- a/content/docs/references/ui/report.mdx +++ b/content/docs/references/ui/report.mdx @@ -5,8 +5,6 @@ description: Report protocol schemas {/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */} -Report Type Enum - **Source:** `packages/spec/src/ui/report.zod.ts` diff --git a/packages/spec/scripts/file-description.test.ts b/packages/spec/scripts/file-description.test.ts index 1ce331672d..eb799771df 100644 --- a/packages/spec/scripts/file-description.test.ts +++ b/packages/spec/scripts/file-description.test.ts @@ -198,9 +198,15 @@ describe('findModuleDocBlock — a block documents a symbol, or it documents the }); it('keeps a header the lazify codemod separated from the imports', () => { - // `scripts/lazify-schemas.ts` inserts its import after the leading run of - // comments and imports — and that run swallows a doc block, so a header can - // end up with imports on both sides. It is still a header. + // `api/analytics.zod.ts`, as it really is on `main`. `lazify-schemas.ts` + // inserts its import after the leading run of comments and imports — and + // that run swallows a doc block, so a header can end up with imports on + // both sides. It is still a header, and the banner is why: the block was + // not sitting against the declaration before the codemod ran either. + // + // ⚠️ This case used to be written WITHOUT the banner, and that reduction + // dropped the one line carrying the verdict (#13263) — see the case below, + // which is that bannerless shape and now asserts the opposite. const source = [ "import { z } from 'zod';", '', @@ -208,6 +214,10 @@ describe('findModuleDocBlock — a block documents a symbol, or it documents the ' * Analytics API Protocol', ' */', '', + '// ==========================================', + '// 1. API Endpoints', + '// ==========================================', + '', "import { lazySchema } from '../shared/lazy-schema';", 'export const AnalyticsEndpoint = z.enum([]);', '', @@ -220,6 +230,143 @@ describe('findModuleDocBlock — a block documents a symbol, or it documents the }); }); +/** + * #13263 — an injected import is not a separator. + * + * `lazify-schemas.ts` injects its `lazySchema` import at the END of the file's + * leading run of comments, blank lines and imports, and its regex for that run + * counts a doc block among the comments. A module written as an import, a blank + * line, `Service Status Enum` and then `export const ServiceStatus` therefore + * came out of the codemod with the import BETWEEN the block and its symbol — + * and condition 3, which skipped only blank lines, then read the block as + * documenting nothing. 28 reference pages opened with one schema's comment, and + * `gen:skill-refs` copied each first line into the published skill indexes. + * + * The tightening applies only INSIDE the import block and stops at a comment of + * any kind, which is what the four `keeps` cases below pin: without the first + * limb, three real headers written above their imports go blank; without the + * second, `api/analytics` and `system/cache` do. + * + * MEASURED over `packages/spec/src` (193 sources, base `3322527f`): 28 pages + * lose a misattributed opening, 0 change to a different block, 165 are + * byte-identical. The corpus limb at the end of this file re-derives that + * rather than restating it. + */ +describe('findModuleDocBlock — #13263: an import injected between a block and its symbol', () => { + it('rejects a block the codemod separated from the declaration it documents', () => { + // `api/discovery.zod.ts`, `data/field.zod.ts`, and 26 more. This is the + // previous case's source with the banner removed — the whole difference. + const source = [ + "import { z } from 'zod';", + '', + '/**', + ' * Service Status Enum', + ' * Describes the operational state of a service in the discovery response.', + ' */', + "import { lazySchema } from '../shared/lazy-schema';", + "export const ServiceStatus = z.enum(['available', 'stub']);", + '', + ].join('\n'); + expect(findModuleDocBlock(source)).toBeNull(); + }); + + it('rejects it across a blank line and several injected imports', () => { + // `automation/flow.zod.ts` has five between the block and `FlowNodeAction`; + // `data/object.zod.ts` six. Distance in plumbing lines is not a signal. + const source = [ + "import { z } from 'zod';", + "import { ProtectionSchema } from '../shared/protection.zod';", + '', + '/**', + ' * Flow Node Types — built-in seed set (ADR-0018).', + ' */', + "import { lazySchema } from '../shared/lazy-schema';", + "import { retiredKey } from '../shared/retired-key';", + "import { strictObject } from '../shared/strict-object';", + '', + "export const FlowNodeAction = z.enum(['start', 'end']);", + '', + ].join('\n'); + expect(findModuleDocBlock(source)).toBeNull(); + }); + + it('rejects it across a MULTI-LINE import — continuation lines are plumbing too', () => { + // `data/document.zod.ts` and `kernel/execution-context.zod.ts` reach their + // declaration only over a wrapped import's `Foo,` and `} from '…';` lines. + const source = [ + "import { z } from 'zod';", + '', + '/**', + ' * Document Version Schema', + ' */', + 'import {', + ' MetadataProtectionFields,', + ' ProtectionSchema,', + "} from '../kernel/metadata-protection.zod';", + 'export const DocumentVersionSchema = z.object({});', + '', + ].join('\n'); + expect(findModuleDocBlock(source)).toBeNull(); + }); + + it('keeps a header written ABOVE the imports, even with a declaration right after them', () => { + // `system/doc.zod.ts`, `cloud/template-manifest.zod.ts`, + // `api/error-code-ledger.zod.ts`. The codemod injects AFTER the last + // import, so a block preceding every import preceded them beforehand too — + // the position is the proof, and dropping this limb blanks all three. + const source = [ + '// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.', + '', + '/**', + ' * Package Documentation Metadata Protocol (ADR-0046)', + ' */', + '', + "import { z } from 'zod';", + "import { lazySchema } from '../shared/lazy-schema';", + '', + 'export const DocSchema = z.object({});', + '', + ].join('\n'); + expect(opening(findModuleDocBlock(source))).toBe('Package Documentation Metadata Protocol (ADR-0046)'); + }); + + it('keeps a header inside the imports when the next schema carries its own JSDoc', () => { + // `system/cache.zod.ts` — its block names itself ("This File") and the + // declaration beyond the injected import is already documented, so that + // import says nothing about what the block documents. + const source = [ + "import { z } from 'zod';", + "import { CronExpressionInputSchema } from '../shared/expression.zod';", + '', + '/**', + ' * Application-Level Cache Protocol', + ' */', + "import { lazySchema } from '../shared/lazy-schema';", + '', + '/** Cache eviction strategy. */', + "export const CacheStrategySchema = z.enum(['lru']);", + '', + ].join('\n'); + expect(opening(findModuleDocBlock(source))).toBe('Application-Level Cache Protocol'); + }); + + it('keeps a block with no declaration on the far side at all', () => { + // A module that is nothing but re-exports — the plumbing runs to the end of + // the file, so there is no symbol for the block to have been torn from. + const source = [ + "import { z } from 'zod';", + '', + '/**', + ' * Environment Artifact Envelope — re-export', + ' */', + "export { EnvironmentArtifactSchema } from './artifact.zod';", + "export type { EnvironmentArtifact } from './artifact.zod';", + '', + ].join('\n'); + expect(opening(findModuleDocBlock(source))).toBe('Environment Artifact Envelope — re-export'); + }); +}); + describe('renderFileDescription', () => { // `fromCategory` is the directory the rendered module lives in (#6484); these // cases reference `automation/` and are written as if from there. @@ -1023,6 +1170,58 @@ describe('corpus — no reference source donates a symbol comment to its page', expect(openingOf('api/error-code-ledger.zod.ts')) .toBe('Error-Code Ledger (ADR-0112 D3).'); }); + + /** + * #13263's corpus limb — the half that cannot rot. + * + * Re-derives the verdict from the real tree instead of restating a file list: + * a selected block that sits inside the import block must have a COMMENT on + * the far side of that plumbing, never a declaration. A source that acquires + * the codemod shape later cannot quietly re-acquire a wrong page description, + * and the three headers written above their imports are pinned by name in the + * `#6145` case above, so neither direction can drift alone. + */ + it('never selects a block with a declaration on the far side of the imports', () => { + const PLUMBING = /^(?:import\b|export\s*(?:\*|\{|type\s*\{))/; + const offenders: string[] = []; + for (const file of zodFiles) { + const source = fs.readFileSync(file, 'utf-8'); + const block = findModuleDocBlock(source); + if (block === null) continue; + const lines = source.split('\n'); + const marker = `/**${block}*/`; + const at = source.indexOf(marker); + if (at < 0) continue; // already reported by the case above + const startLine = source.slice(0, at).split('\n').length - 1; + const endLine = startLine + marker.split('\n').length - 1; + if (!lines.slice(0, startLine).some(l => PLUMBING.test(l))) continue; // above the imports + + for (let i = endLine + 1; i < lines.length; i++) { + const line = lines[i]; + if (line.trim() === '') continue; + if (line.trimStart().startsWith('/')) break; // a comment ends the preamble + if (PLUMBING.test(line)) continue; + if (!/^[A-Za-z_$@]/.test(line)) continue; // continuation / closing punctuation + offenders.push(`${path.relative(SRC_DIR, file)} → ${line.slice(0, 60)}`); + break; + } + } + expect(offenders).toEqual([]); + }); + + it('publishes no description for the modules whose opening was one schema\'s doc', () => { + const openingOf = (rel: string) => + opening(findModuleDocBlock(fs.readFileSync(path.join(SRC_DIR, rel), 'utf-8'))); + + // Four of the 28, one per shape: the plain single injected import, the run + // of five, the wrapped import, and the one whose page-wide blast radius the + // card measured (`gen:skill-refs` shipped `Field Type Enum` as the pointer + // row for a module of ~40 field schemas). + expect(openingOf('api/discovery.zod.ts')).toBeNull(); + expect(openingOf('automation/flow.zod.ts')).toBeNull(); + expect(openingOf('kernel/execution-context.zod.ts')).toBeNull(); + expect(openingOf('data/field.zod.ts')).toBeNull(); + }); }); /** diff --git a/packages/spec/scripts/lib/file-description.ts b/packages/spec/scripts/lib/file-description.ts index 2581ae656a..b16f90ef14 100644 --- a/packages/spec/scripts/lib/file-description.ts +++ b/packages/spec/scripts/lib/file-description.ts @@ -33,7 +33,8 @@ * and this repo writes module headers on either side of them); the first * `const`/`export const`/… does. * 3. **Documenting nothing** — the block is not immediately followed by a - * declaration. + * declaration, and — when the block sits INSIDE the import block — no + * declaration sits on the far side of that plumbing either. * * (3) is the load-bearing one, and it is simply TSDoc's own rule read back: a * doc block belongs to the declaration it immediately precedes, which is why @@ -42,8 +43,51 @@ * as the Realtime page's opening paragraph was the generator inventing a second * meaning for text that already had one. "Immediately" means blank lines only: * nobody separates a JSDoc from its symbol with a `// ═══` banner, so a banner - * (or another doc block, or an import) between the two marks the end of the - * preamble rather than an attachment. + * (or another doc block) between the two marks the end of the preamble rather + * than an attachment. + * + * ## An import between a block and its symbol is not a separator (#13263) + * + * The one exception to that last sentence, and it is not a judgement call — it + * is a codemod. `scripts/lazify-schemas.ts` injects + * `import { lazySchema } from '…/shared/lazy-schema';` at the END of the file's + * leading run of comments, blank lines and imports, and the regex it uses for + * that run counts a doc block among the comments (its comment alternative is + * slash-star, any run, star-slash — a doc block matches it). So when a module + * was written as an `import { z } from 'zod';`, a blank line, a doc block + * reading `Service Status Enum`, and then `export const ServiceStatus`, + * the run swallowed the doc block and the injected import landed BETWEEN the + * block and the symbol it documents. Nothing about the block changed; only the + * detector's view of it did. Reading that import as "the preamble ends here" + * republished 28 symbol comments as their pages' subjects, `api/discovery`'s + * `Service Status Enum` and `data/field`'s `Field Type Enum` among them — and + * `gen:skill-refs` copied each one's first line into the PUBLISHED skill + * indexes, so the misattribution shipped to customer projects. + * + * Hence condition 3's second half: a declaration reachable across nothing but + * blank lines and plumbing is still the block's subject. Two things keep this a + * tightening rather than a demotion of the spelling `MODULE_PLUMBING` exists to + * permit — measured over all 193 reference sources, and both are load-bearing: + * + * - **It applies only INSIDE the import block.** A header written ABOVE the + * imports is where the codemod cannot have put it: the injection point is + * after the last import, so a block preceding every import was preceding them + * before the codemod ran too. Without that half, `api/error-code-ledger`, + * `cloud/template-manifest` and `system/doc` — three real headers whose + * imports happen to be followed directly by a declaration — lose their + * opening paragraph. + * - **A comment of any kind on the far side still ends the preamble.** A `// ═══` + * banner or a second doc block means the block did NOT sit against the + * declaration before the codemod ran, so the injection tells us nothing. + * `api/analytics` (banner) and `system/cache` (the next schema's own JSDoc) + * keep their headers through exactly this clause. + * + * What it deliberately does NOT decide is the block that sits inside the import + * list with a comment on the far side: `system/cache` and `shared/mapping` are + * genuine headers there and seven others are detached symbol docs, and no + * positional or structural signal separates them — only the prose does. That + * residue needs an explicit `@module` marker or a corpus pass, not a cleverer + * detector; #13263 records the reading, module by module. * * When no block qualifies, the module has no description and the page prints * none. 宁可缺,不要错 — a missing paragraph is a gap the reader can see, while @@ -255,6 +299,40 @@ function nextNonBlankLine(lines: readonly string[], from: number): number | null return i < lines.length ? i : null; } +/** + * Is there a declaration on the far side of the plumbing that starts at `from` + * — i.e. does everything between hold nothing but blank lines and imports? + * + * Only ever asked of a block that sits INSIDE the import block, where the one + * thing known to put an import between a doc block and its symbol is the lazify + * codemod (see the module comment). Answering `true` there restores the verdict + * the block had before that import was injected. + * + * A comment of any kind — a `// ═══` banner, a second doc block, an import's + * own explanatory note — answers `false` instead of being walked over. That is + * the same boundary `nextNonBlankLine` draws and for the same reason: it means + * the block was NOT sitting against the declaration beforehand either, so the + * injected import carries no information about what the block documents. It is + * what keeps `api/analytics` (banner) and `system/cache` (the next schema's own + * JSDoc) opening with their real module headers. + * + * Continuation and closing lines of a multi-line import (` Foo,`, + * `} from './x';`) are plumbing too — they open with neither an identifier + * character nor a comment delimiter, exactly as `findModuleDocBlock`'s own walk + * reads them. + */ +function declarationBeyondPlumbing(lines: readonly string[], from: number): boolean { + for (let i = from; i < lines.length; i++) { + const line = lines[i]; + if (line.trim() === '') continue; + if (line.trimStart().startsWith('/')) return false; // a comment ends the preamble + if (MODULE_PLUMBING.test(line)) continue; + if (!startsDeclaration(line)) continue; // continuation / closing punctuation + return true; + } + return false; +} + /** * The module's own doc block, INNER text only (delimiters stripped, `*` line * prefixes intact) — or `null` when the module does not have one. @@ -271,6 +349,12 @@ function nextNonBlankLine(lines: readonly string[], from: number): number | null export function findModuleDocBlock(source: string): string | null { const lines = source.split('\n'); + // Whether the walk has passed an import / re-export, i.e. whether a block + // found from here on sits INSIDE the import block rather than above it. Only + // there can the lazify codemod have put an import between a block and its + // symbol, so only there does the far-side check below apply (#13263). + let insideImportBlock = false; + let i = 0; while (i < lines.length) { const line = lines[i]; @@ -280,13 +364,16 @@ export function findModuleDocBlock(source: string): string | null { if (end >= lines.length) return null; // unterminated — nothing to trust const next = nextNonBlankLine(lines, end + 1); if (next !== null && startsDeclaration(lines[next])) return null; // documents a symbol + // …and the same verdict when only injected plumbing stands between the + // two: the import moved, the attachment did not. + if (insideImportBlock && declarationBeyondPlumbing(lines, end + 1)) return null; const raw = lines.slice(i, end + 1).join('\n'); return raw.slice(raw.indexOf('/**') + 3, raw.lastIndexOf('*/')); } if (line.startsWith('/*')) { i = endOfBlockComment(lines, i) + 1; continue; } if (line.trim() === '' || line.trim().startsWith('//') || !/^\S/.test(line)) { i++; continue; } - if (MODULE_PLUMBING.test(line)) { i++; continue; } + if (MODULE_PLUMBING.test(line)) { insideImportBlock = true; i++; continue; } if (startsDeclaration(line)) return null; // header zone closed before any block i++; // closing punctuation of a multi-line import / re-export diff --git a/skills/objectstack-ai/references/_index.md b/skills/objectstack-ai/references/_index.md index dc43598e14..ad27f6e764 100644 --- a/skills/objectstack-ai/references/_index.md +++ b/skills/objectstack-ai/references/_index.md @@ -24,11 +24,11 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/automation/state-machine.zod.ts` — XState-inspired State Machine Protocol — hierarchical states, guarded - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities diff --git a/skills/objectstack-api/references/_index.md b/skills/objectstack-api/references/_index.md index 1ff5756163..5b5f144ffc 100644 --- a/skills/objectstack-api/references/_index.md +++ b/skills/objectstack-api/references/_index.md @@ -11,7 +11,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/api/auth.zod.ts` — Authentication Service Protocol - `node_modules/@objectstack/spec/src/api/batch.zod.ts` — Batch Operations API -- `node_modules/@objectstack/spec/src/api/endpoint.zod.ts` — API Mapping Schema +- `node_modules/@objectstack/spec/src/api/endpoint.zod.ts` — Exports: ApiMappingSchema, ApiEndpointSchema, ApiEndpoint - `node_modules/@objectstack/spec/src/api/errors.zod.ts` — Standardized Error Codes Protocol - `node_modules/@objectstack/spec/src/api/realtime.zod.ts` — Exports: TransportProtocol, RealtimeEventType, SubscriptionEventSchema, SubscriptionSchema, RealtimePresenceSchema - `node_modules/@objectstack/spec/src/api/rest-server.zod.ts` — REST API Server Protocol @@ -25,15 +25,15 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/api/realtime-shared.zod.ts` — Realtime Shared Protocol - `node_modules/@objectstack/spec/src/data/data-engine.zod.ts` — Data Engine Protocol - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node -- `node_modules/@objectstack/spec/src/kernel/execution-context.zod.ts` — Execution Context Schema +- `node_modules/@objectstack/spec/src/kernel/execution-context.zod.ts` — Exports: ExecutionContextSchema - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/security/explain.zod.ts` — [ADR-0090 D6] Access-explanation contract — `explain(principal, object, - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol - `node_modules/@objectstack/spec/src/shared/http.zod.ts` — Shared HTTP Schemas -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities ## How to read these diff --git a/skills/objectstack-automation/references/_index.md b/skills/objectstack-automation/references/_index.md index c3d730ab41..6bcee7eb99 100644 --- a/skills/objectstack-automation/references/_index.md +++ b/skills/objectstack-automation/references/_index.md @@ -11,22 +11,22 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/automation/approval.zod.ts` — Exports: ApproverType, ApprovalDecision, ApprovalNodeApproverSchema, DecisionOutputDefSchema, ApprovalEscalationSchema - `node_modules/@objectstack/spec/src/automation/execution.zod.ts` — Automation Execution Protocol -- `node_modules/@objectstack/spec/src/automation/flow.zod.ts` — Flow Node Types — **built-in seed set** (ADR-0018). +- `node_modules/@objectstack/spec/src/automation/flow.zod.ts` — Exports: FlowNodeAction, FlowVariableSchema, FlowNodeSchema, FlowEdgeSchema, FlowSchema - `node_modules/@objectstack/spec/src/automation/node-executor.zod.ts` — Node Executor Plugin Protocol — Wait Node Pause/Resume - `node_modules/@objectstack/spec/src/automation/state-machine.zod.ts` — XState-inspired State Machine Protocol — hierarchical states, guarded - `node_modules/@objectstack/spec/src/automation/time-relative-trigger.zod.ts` — Time-Relative Trigger Protocol -- `node_modules/@objectstack/spec/src/automation/webhook.zod.ts` — Webhook Trigger Event +- `node_modules/@objectstack/spec/src/automation/webhook.zod.ts` — Exports: WebhookTriggerType, WebhookSchema - `node_modules/@objectstack/spec/src/data/validation.zod.ts` — ObjectStack Validation Protocol ## Transitive dependencies - `node_modules/@objectstack/spec/src/automation/control-flow.zod.ts` — Structured control-flow constructs (ADR-0031) — the **native + AI-authored** - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/retry-policy.zod.ts` — The **single declaration** of the exponential-backoff retry policy. - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities diff --git a/skills/objectstack-data/references/_index.md b/skills/objectstack-data/references/_index.md index 8a2050ea9f..107b66d09d 100644 --- a/skills/objectstack-data/references/_index.md +++ b/skills/objectstack-data/references/_index.md @@ -10,10 +10,10 @@ from `node_modules` — there is no local copy in the skill bundle. ## Core schemas - `node_modules/@objectstack/spec/src/data/datasource.zod.ts` — Driver Identifier -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/hook.zod.ts` — Hook Lifecycle Events -- `node_modules/@objectstack/spec/src/data/object.zod.ts` — API Operations Enum -- `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Seed Import Strategy +- `node_modules/@objectstack/spec/src/data/object.zod.ts` — Exports: ApiMethod, ApiOperationSchema, ObjectCapabilities, IndexSchema, TenancyConfigSchema +- `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Exports: SeedMode, SeedSchema, leadSeed - `node_modules/@objectstack/spec/src/data/validation.zod.ts` — ObjectStack Validation Protocol - `node_modules/@objectstack/spec/src/security/permission.zod.ts` — Entity (Object) Level Permissions @@ -21,8 +21,8 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/api/errors.zod.ts` — Standardized Error Codes Protocol - `node_modules/@objectstack/spec/src/automation/flow-function.zod.ts` — The contract for a **named handler function a `script` node invokes** — -- `node_modules/@objectstack/spec/src/data/driver-sql.zod.ts` — SQL Dialect Enumeration -- `node_modules/@objectstack/spec/src/data/driver.zod.ts` — Common Driver Options +- `node_modules/@objectstack/spec/src/data/driver-sql.zod.ts` — Exports: SQLDialectSchema, DataTypeMappingSchema, SSLConfigSchema, SQLDriverConfigSchema, SQLiteDataTypeMappingDefaults +- `node_modules/@objectstack/spec/src/data/driver.zod.ts` — Exports: DriverOptionsSchema, DriverCapabilitiesSchema, DriverInterfaceSchema, PoolConfigSchema, DriverConfigSchema - `node_modules/@objectstack/spec/src/data/driver/common.zod.ts` — Shared building blocks for the per-driver `datasource.config` shapes. - `node_modules/@objectstack/spec/src/data/driver/config-registry.zod.ts` — The driver-id → `datasource.config` shape registry. - `node_modules/@objectstack/spec/src/data/driver/memory.zod.ts` — Memory Driver Configuration Schema @@ -40,7 +40,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/shared/enums.zod.ts` — Exports: SortDirectionEnum, SortItemSchema, MutationEventEnum, IsolationLevelEnum - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol - `node_modules/@objectstack/spec/src/shared/http.zod.ts` — Shared HTTP Schemas -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities - `node_modules/@objectstack/spec/src/system/deploy-bundle.zod.ts` — Deploy Bundle Protocol diff --git a/skills/objectstack-i18n/references/_index.md b/skills/objectstack-i18n/references/_index.md index e91ee1fc01..dcf6cf9c54 100644 --- a/skills/objectstack-i18n/references/_index.md +++ b/skills/objectstack-i18n/references/_index.md @@ -15,11 +15,11 @@ from `node_modules` — there is no local copy in the skill bundle. ## Transitive dependencies - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities ## How to read these diff --git a/skills/objectstack-platform/references/_index.md b/skills/objectstack-platform/references/_index.md index f16d3e9d14..14638841fb 100644 --- a/skills/objectstack-platform/references/_index.md +++ b/skills/objectstack-platform/references/_index.md @@ -10,7 +10,7 @@ from `node_modules` — there is no local copy in the skill bundle. ## Core schemas - `node_modules/@objectstack/spec/src/data/datasource.zod.ts` — Driver Identifier -- `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Seed Import Strategy +- `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Exports: SeedMode, SeedSchema, leadSeed - `node_modules/@objectstack/spec/src/kernel/context.zod.ts` — Exports: RuntimeMode, KernelContextSchema, TenantRuntimeContextSchema - `node_modules/@objectstack/spec/src/kernel/manifest.zod.ts` — Exports: PluginPermissionsSchema, ManifestPermissionsSchema, PluginEnginesSchema, PluginRuntimeSchema, PluginPackagingSchema - `node_modules/@objectstack/spec/src/kernel/metadata-plugin.zod.ts` — Metadata Plugin Protocol @@ -31,15 +31,15 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/driver/sqlite.zod.ts` — SQLite driver configuration — the `config` slot of a `datasource` whose - `node_modules/@objectstack/spec/src/data/driver/turso.zod.ts` — Turso / libSQL Driver Protocol. - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema - `node_modules/@objectstack/spec/src/kernel/cluster.zod.ts` — Cluster Protocol - `node_modules/@objectstack/spec/src/kernel/metadata-loader.zod.ts` — Metadata Manager Configuration - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema -- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Supported metadata file formats +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema +- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Exports: MetadataFormatSchema, BaseMetadataRecordSchema - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities - `node_modules/@objectstack/spec/src/system/tenant.zod.ts` — Tenant Schema (Multi-Tenant Architecture) diff --git a/skills/objectstack-query/references/_index.md b/skills/objectstack-query/references/_index.md index a8c41ea0a6..e7cc0139e2 100644 --- a/skills/objectstack-query/references/_index.md +++ b/skills/objectstack-query/references/_index.md @@ -16,10 +16,10 @@ from `node_modules` — there is no local copy in the skill bundle. ## Transitive dependencies - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010) - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities ## How to read these diff --git a/skills/objectstack-ui/references/_index.md b/skills/objectstack-ui/references/_index.md index 08694f7664..8fed011033 100644 --- a/skills/objectstack-ui/references/_index.md +++ b/skills/objectstack-ui/references/_index.md @@ -13,10 +13,10 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/ui/app.zod.ts` — Base Navigation Item Schema - `node_modules/@objectstack/spec/src/ui/chart.zod.ts` — Unified Chart Type Taxonomy - `node_modules/@objectstack/spec/src/ui/component.zod.ts` — Empty Properties Schema -- `node_modules/@objectstack/spec/src/ui/dashboard.zod.ts` — Color variant for dashboard widgets (e.g., KPI cards). +- `node_modules/@objectstack/spec/src/ui/dashboard.zod.ts` — Exports: WidgetColorVariantSchema, WidgetActionTypeSchema, DashboardHeaderActionSchema, DashboardHeaderSchema, DashboardWidgetOptionsSchema - `node_modules/@objectstack/spec/src/ui/dataset.zod.ts` — Analytics Dataset — the one semantic layer (ADR-0021). - `node_modules/@objectstack/spec/src/ui/page.zod.ts` — Page Region Schema -- `node_modules/@objectstack/spec/src/ui/report.zod.ts` — Report Type Enum +- `node_modules/@objectstack/spec/src/ui/report.zod.ts` — Exports: ReportType, ReportChartSchema, ReportSortSchema, JoinedReportBlockSchema, ReportSchema - `node_modules/@objectstack/spec/src/ui/view.zod.ts` — View protocol schemas — the `view` metadata type and its three persisted body spellings. - `node_modules/@objectstack/spec/src/ui/widget.zod.ts` — Exports: FieldWidgetPropsSchema @@ -26,7 +26,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/data/date-macros.zod.ts` — Date Macro Tokens — the declarative placeholders the UI substitutes - `node_modules/@objectstack/spec/src/data/feed.zod.ts` — Activity-timeline UI config enums, and the `sys_activity.type` built-in set. - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1). -- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum +- `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification - `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node @@ -34,7 +34,7 @@ from `node_modules` — there is no local copy in the skill bundle. - `node_modules/@objectstack/spec/src/shared/enums.zod.ts` — Exports: SortDirectionEnum, SortItemSchema, MutationEventEnum, IsolationLevelEnum - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol - `node_modules/@objectstack/spec/src/shared/http.zod.ts` — Shared HTTP Schemas -- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema +- `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema, EventNameSchema - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3) - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities - `node_modules/@objectstack/spec/src/ui/action-params.zod.ts` — The action DISPATCH contract: what the platform validates on the way in, and