fix(spec): published agent prompts reference real exports (#9545) (#9615)

Three published agent-authoring prompts in packages/spec/prompts told agents to
import five symbols @objectstack/spec does not export. Four failed loudly. The
fifth did not: `import { Object } from '@objectstack/spec/data'` does not
resolve, so `export const AccountObject: Object = { ... }` bound to the
JavaScript global instead, and metadata authored from that prompt type-checked
against a type that constrains nothing -- false assurance handed to an
automated author.

Every substitution was measured against the built .d.ts, not guessed:

- Object -> ObjectSchema.create({ ... }), the house authoring convention (34
  uses across the example apps; zero uses of the annotation form). Making the
  form genuinely constrain exposed that the prompt's own example set
  enable.audit / enable.workflow, neither of which exists; they are now
  trackHistory / files, the pair the schema's own docstring uses.
- implement-objectql.md keeps the real Field and QuerySchema imports and
  derives the metadata type as z.infer of typeof ObjectSchema, matching
  prompts/instructions.md and spec's own src/contracts/schema-driver.ts. No
  bare Object type is exported -- it would shadow the JS global.
- ManifestSchema -> ObjectStackDefinitionSchema on the package root. The
  prompt's subject is objectstack.config.ts, which is neither /system manifest.
- IdentitySchema / PolicySchema have no bare referent anywhere in spec. Rule #2
  now names RLSUserContextSchema and RowLevelSecurityPolicySchema from
  @objectstack/spec/security.
- The three dead "Key Files to Watch" paths now point at stack.zod.ts,
  security/rls.zod.ts and kernel/events.zod.ts.

The five baseline entries are deleted in the same commit; the gate is
reconciled in both directions and green.


Claude-Session: https://claude.ai/code/session_01Fs18A2DdXLVN2h8PaaFBcP

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/spec-prompts-real-exports-9545.md

@@ -0,0 +1,32 @@
+---
+'@objectstack/spec': patch
+---
+
+Published agent-authoring prompts now reference real exports.
+
+`prompts/create-new-project.md`, `prompts/implement-objectql.md` and
+`prompts/implement-objectos.md` told agents to import five symbols that
+`@objectstack/spec` does not export. Four failed loudly. The fifth did not:
+`import { Object } from '@objectstack/spec/data'` does not resolve, so the
+annotation in `export const AccountObject: Object = { ... }` bound to the
+**JavaScript global** `Object` instead — metadata authored from that prompt
+type-checked against a type that constrains nothing.
+
+- Object definitions now use the house authoring convention measured in the
+  example apps, `ObjectSchema.create({ ... })`, which genuinely validates.
+  Correcting it exposed that the prompt's own example set `enable.audit` /
+  `enable.workflow`, neither of which exists; they are now `trackHistory` /
+  `files`, the pair the schema's own docstring uses.
+- `implement-objectql.md` keeps the real `Field` and `QuerySchema` imports and
+  derives the object metadata type as `z.infer<typeof ObjectSchema>`, matching
+  both `prompts/instructions.md` ("interfaces must be inferred from Zod") and
+  spec's own `src/contracts/schema-driver.ts`.
+- `ManifestSchema` becomes `ObjectStackDefinitionSchema` from the package root:
+  the prompt's subject is `objectstack.config.ts`, which is neither of the
+  `/system` manifests.
+- `IdentitySchema` / `PolicySchema` have no bare referent; Rule #2 now names
+  `RLSUserContextSchema` and `RowLevelSecurityPolicySchema` from
+  `@objectstack/spec/security`.
+- The three non-existent "Key Files to Watch" paths
+  (`system/{manifest,identity,events}.zod.ts`) now point at `stack.zod.ts`,
+  `security/rls.zod.ts` and `kernel/events.zod.ts`.

packages/spec/prompts/create-new-project.md

@@ -38,9 +38,9 @@ my-app/
 
 # Implementation Rules
 
-1.  **Strict Typing:** Always explicit types.
+1.  **Strict Typing:** Always define metadata through its schema, never as a bare literal.
     *   BAD: `const MyObject = { ... }`
-    *   GOOD: `export const MyObject: Object = { ... }`
+    *   GOOD: `export const MyObject = ObjectSchema.create({ ... })`
 
 2.  **Naming Conventions:**
     *   **File Names:** `snake_case` or `domain.feature.ts` (e.g., `account.object.ts`).
@@ -49,14 +49,14 @@ my-app/
 
 3.  **Code Pattern (Object Definition):**
     ```typescript
-    import { Object } from '@objectstack/spec/data';
+    import { ObjectSchema } from '@objectstack/spec/data';
 
-    export const AccountObject: Object = {
+    export const AccountObject = ObjectSchema.create({
       name: 'account',
       label: 'Corporate Account',
       enable: {
-        audit: true,
-        workflow: true
+        trackHistory: true,
+        files: true
       },
       fields: {
         name: { type: 'text', label: 'Account Name', required: true },
@@ -66,7 +66,7 @@ my-app/
         },
         owner: { type: 'lookup', reference: 'user' }
       }
-    };
+    });
     ```
 
 4.  **Code Pattern (App Config):**

packages/spec/prompts/implement-objectos.md

@@ -12,18 +12,29 @@ Your source of truth is `node_modules/@objectstack/spec`.
 
 ### Rule #1: Manifest Driven Boot
 The system MUST boot by loading and validating the `objectstack.config.ts`.
+That file's authoring surface is `defineStack`, and its schema is
+`ObjectStackDefinitionSchema` on the package root — not one of the `/system`
+manifests (`AppManifestSchema` installs an app into a running stack;
+`DeployManifestSchema` describes a deploy bundle).
 ```typescript
-import { ManifestSchema } from '@objectstack/spec/system';
+import { ObjectStackDefinitionSchema } from '@objectstack/spec';
 // The kernel starts here
-const config = ManifestSchema.parse(loadedConfig);
+const config = ObjectStackDefinitionSchema.parse(loadedConfig);
 ```
 
 ### Rule #2: Security First (Identity & Policy)
-All request handlers must validate against `IdentitySchema`.
-No operation proceeds without checking `PolicySchema`.
+All request handlers must validate the caller's security context against
+`RLSUserContextSchema`. No operation proceeds without evaluating the applicable
+`RowLevelSecurityPolicySchema` rules against that context.
 ```typescript
-import { IdentitySchema, PolicySchema } from '@objectstack/spec/system';
+import {
+  RLSUserContextSchema,
+  RowLevelSecurityPolicySchema,
+} from '@objectstack/spec/security';
 ```
+There is no bare `Identity` or `Policy` schema: identity is the per-request RLS
+user context, and policy is per-object and per-operation. Broader posture lives
+in the qualified schemas (`TenantSecurityPolicySchema`, `PermissionSetSchema`).
 
 ### Rule #3: API Gateway Contract
 The HTTP/Gateway layer must perform strict request/response validation using `api/contract.zod.ts` and `api/endpoint.zod.ts`.
@@ -36,13 +47,13 @@ Do not invent event formats. Use the standard CloudEvents-compatible structure.
 
 ## 3. Workflow
 
-1.  **Define Configuration**: Start by mapping `ManifestSchema` to your runtime config.
-2.  **Initialize Identity**: Implement the Auth Provider using `IdentitySchema`.
+1.  **Define Configuration**: Start by mapping `ObjectStackDefinitionSchema` to your runtime config.
+2.  **Initialize Identity**: Implement the Auth Provider so it produces a context that satisfies `RLSUserContextSchema`.
 3.  **Setup Gateway**: Configure routes based on `ApiRoutesSchema` (from `api/discovery.zod.ts`).
 
 ## 4. Key Files to Watch
 
-- `system/manifest.zod.ts`: The "Kernel Configuration".
-- `system/identity.zod.ts`: The "Security Context".
-- `system/events.zod.ts`: The "System Bus".
+- `stack.zod.ts`: The "Kernel Configuration" (`ObjectStackDefinitionSchema`, `defineStack`).
+- `security/rls.zod.ts`: The "Security Context" (`RLSUserContextSchema`, `RowLevelSecurityPolicySchema`).
+- `kernel/events.zod.ts`: The "System Bus" (`EventSchema`; the `kernel/events/*` sub-modules are internal — import from the published `@objectstack/spec/kernel` entrypoint).
 - `api/contract.zod.ts`: The "Wire Protocol".

packages/spec/prompts/implement-objectql.md

@@ -11,10 +11,16 @@ Your source of truth is `node_modules/@objectstack/spec`.
 ## 2. Implementation Rules
 
 ### Rule #1: Never Redefine Types
-Do not create your own interfaces for `Object`, `Field`, or `Query`.
-ALWAYS import them:
+Do not create your own interfaces for object metadata, `Field`, or `Query`.
+ALWAYS import them, and derive any type you need from the schema:
 ```typescript
-import { type Object, ObjectSchema } from '@objectstack/spec/data';
+import { z } from 'zod';
+import { ObjectSchema, type Field, QuerySchema } from '@objectstack/spec/data';
+
+// The object metadata type is NOT exported under the name `Object` — that would
+// shadow the JS global and silently type-check against it. Derive it instead:
+type ObjectMetadata = z.infer<typeof ObjectSchema>;
+type Query = z.infer<typeof QuerySchema>;
 ```
 
 ### Rule #2: Schema-First Validation

scripts/published-readme-exports.baseline.json

@@ -42,26 +42,6 @@
     {
       "id": "@objectstack/spec|packages/spec/README.md|import|@objectstack/spec/ai|MCPServerConfigSchema",
       "why": "@objectstack/spec/ai exports `MCPServerRefSchema`; there is no `MCPServerConfigSchema`. This is the protocol package's own front page."
-    },
-    {
-      "id": "@objectstack/spec|packages/spec/prompts/create-new-project.md|import|@objectstack/spec/data|Object",
-      "why": "@objectstack/spec/data exports `ObjectSchema`. `Object` resolves to the JS global instead of failing loudly — the worst shape for a published AGENT-AUTHORING prompt."
-    },
-    {
-      "id": "@objectstack/spec|packages/spec/prompts/implement-objectos.md|import|@objectstack/spec/system|ManifestSchema",
-      "why": "@objectstack/spec/system exports `AppManifestSchema` and `DeployManifestSchema`; there is no bare `ManifestSchema`. Published agent-authoring prompt."
-    },
-    {
-      "id": "@objectstack/spec|packages/spec/prompts/implement-objectos.md|import|@objectstack/spec/system|IdentitySchema",
-      "why": "@objectstack/spec/system exports `Identity`; there is no `IdentitySchema`. Published agent-authoring prompt."
-    },
-    {
-      "id": "@objectstack/spec|packages/spec/prompts/implement-objectos.md|import|@objectstack/spec/system|PolicySchema",
-      "why": "@objectstack/spec/system has no bare `PolicySchema` — only qualified ones (`KeyRotationPolicySchema`, `IncidentResponsePolicySchema`, `DataClassificationPolicySchema`, …). Published agent-authoring prompt."
-    },
-    {
-      "id": "@objectstack/spec|packages/spec/prompts/implement-objectql.md|import|@objectstack/spec/data|Object",
-      "why": "Same fabrication as create-new-project.md: `ObjectSchema` is the real export."
     }
   ]
 }