@sequenceholdings/orm 2.6.2 → 2.7.1

package/README.md

@@ -131,6 +131,37 @@ Execute uses the `/_data/v2` endpoint by default. Set
 `SEQUENCE_ORM_ATLAS_EXECUTE_V2=1` to opt into Atlas's `/api/data/v2` endpoint.
 This client rollout switch does not bypass server feature flags or authorization.
 
+## Internal synced dependencies
+
+Use `internal: true` on a typed, keyed `defineSyncedTable` when its rows are
+inputs to a managed view and must not be queried directly. The reflected source
+and its read policy remain available inside the view. Internal sources are
+excluded from GraphQL roots and links, default SQL, and registered SQL object
+ceilings. A missing persisted operation alone does not make a source private.
+Authoring rejects declared links targeting an internal synced source and
+rejects exporting it. This also prevents dynamic predicates from reaching it
+through hidden intermediate relations or cross-namespace links.
+
+```ts
+const privacy = defineSyncedTable("privacy", {
+  uid: t.text().primaryKey(),
+  restricted: t.boolean().notNull(),
+}, { source: "gold.customer_privacy", internal: true, policies: { read: "true" } });
+if (privacy.config.internal !== true) {
+  throw new Error("Upgrade the ORM SDK: internal synced dependencies are required.");
+}
+```
+
+Publish only the permitted projection through `defineView`, with its own read
+policy. Declaring `internal` does not grant access to the source or change row
+policies. The existing unkeyed-source restrictions remain in force.
+
+This authoring addition needs a released SDK containing the option. The existing
+Atlas internal-object exclusion remains the runtime boundary; do not replace
+the declaration with casts or edits to generated canonical JSON. ORM releases
+use the separate [Studio CLI chain release workflow](https://github.com/sequenceholdings/studio/blob/main/.changeset/README.md#studio-cli-chain-releases);
+chain packages do not use Changesets.
+
 ## Default read-only SQL (introduced in 2.6.0)
 
 With the matching SDK and Atlas rollout, every active v2 namespace supports
@@ -191,7 +222,42 @@ matching acknowledgement. Existing calls without that option are unchanged.
 - `@sequenceholdings/orm/client` — persisted-operation client utilities
 - `@sequenceholdings/orm/drizzle` — supported Drizzle helpers for views
 - `@sequenceholdings/orm/codegen` — GraphQL Code Generator preset used by a
-  scaffolded namespace
+  scaffolded namespace. Custom scalars (`bigint`, `date`, `jsonb`, `numeric`,
+  `timestamptz`, `uuid`) and any other unmapped scalar are emitted as
+  TypeScript `unknown`, not `any`, so `generated/client.ts` and
+  `generated/server.ts` pass native `@typescript-eslint/no-explicit-any`.
+
+### Regenerating clients after upgrading
+
+Existing scaffolds that already committed generated clients need a regenerate.
+`any` on those scalars fails native lint; the files are checked, not ignored.
+
+1. Install the `@sequenceholdings/orm` release that contains this preset.
+2. Run `seq-studio orm generate .` in the namespace directory.
+3. Commit the rewritten `generated/client.ts` and `generated/server.ts`.
+4. Narrow call sites that treated those scalars as `any`. `unknown` has to be
+   checked before it is used.
+
+To keep a concrete type, set `config.scalars` on the `./generated/` output in
+`codegen.ts`. A consumer entry replaces the preset default for that scalar
+only. Lossless `numeric` and `bigint` transport should use `string`:
+
+```ts
+generates: {
+  './generated/': {
+    preset,
+    config: { scalars: { numeric: 'string', bigint: 'string' } },
+  },
+},
+```
+
+Then run `seq-studio orm generate .` again. Mapping a scalar to `any`, or
+eslint-ignoring `generated/client.ts` and `generated/server.ts`, fails the
+purpose of the check: an authored file that uses `any` must still fail.
+
+A scaffold that cannot regenerate should replace each custom scalar's `any`
+with `unknown` (or `string` for lossless numeric/bigint) in the `Scalars` map
+and in every inlined field of both generated files.
 
 The `@sequenceholdings/orm/client` entry point contains the persisted-operation
 executor and error types without importing compiler, migration, Node builtins,
@@ -208,3 +274,11 @@ For a function invocation with no human caller (a Lattice step), use
 service account. The host adapters supply authentication; they do not grant namespace access or
 register operations. Do not extract CLI credentials or invent a browser token
 provider to wire a generated client.
+
+### Verified service policies (planned 2.7.0)
+
+`servicePrincipal()` is a zero-argument Boolean row-policy predicate. Combine it with a private capability, for example `servicePrincipal() and capability('ticket-delivery')`. A role or a `service-account|` subject string does not establish this predicate. The executing runtime derives it afresh from verified service authentication or an attached service delegation; user, dev, console run-as, impersonated and external-borrower requests cannot satisfy it. It is not accepted through `claim()`, request variables or serialized data-token claims.
+
+Affected namespaces require IR v6, including namespaces that only declare a write policy and have no operations. `orm apply` first checks the authenticated target's `/api/orm/runtime-capabilities` response; a missing or older endpoint blocks registration. The compiler and executor also reject an incompatible IR version. Publish the matching ORM and deploy its runtime before activating these policies. Service identity does not grant namespace access, operation capability, declared data scope or row access by itself.
+
+ORM 2.7.0 and downstream Artifact Studio 0.10.0, Managed Functions 0.4.4, Pipeline Spec 0.2.6 and Studio CLI 0.6.6 remain prepared for the separate chain-release workflow and awaiting publication. Their workspace dependencies are pinned to this ORM version when packed; no candidate build constitutes registry evidence.

package/dist/authoring.cjs

@@ -387,6 +387,7 @@ function defineSyncedTable(name2, columnsOrConfig, maybeConfig) {
   if (config.primaryKey !== void 0) tableConfig.primaryKey = config.primaryKey;
   if (config.links !== void 0) tableConfig.links = config.links;
   if (config.policies !== void 0) tableConfig.policies = { read: config.policies.read };
+  if (config.internal === true) tableConfig.internal = true;
   const table = {
     kind: TABLE_BRAND,
     tableName: name2,
@@ -2748,6 +2749,11 @@ function serializeNamespace(input) {
     enumsByName.set(ref.name, ref);
   }
   const canonicalTables = tables.map((table) => buildCanonicalTable({ table, relationsByName, enumsByName }));
+  for (const table of tables) {
+    if (table.source !== void 0 && table.config.internal === true && config.exports && Object.hasOwn(config.exports, table.tableName)) {
+      throw new OrmDefinitionError(`internal synced source "${table.tableName}" cannot be exported; export a permitted managed view instead`, table.file);
+    }
+  }
   const canonicalEnums = [...enumsByName.values()].map((ref) => ({
     name: ref.name,
     values: [...ref.values]
@@ -3081,6 +3087,9 @@ function buildCanonicalLink({
   if (!relationsByName.has(targetName)) {
     return fail(`targets ${relationKind(target)} "${targetName}" which is not part of this namespace`);
   }
+  if (isSeqTable(target) && target.source !== void 0 && target.config.internal === true) {
+    return fail(`targets internal synced source "${targetName}"; expose a permitted managed view instead`);
+  }
   if (link.enforce && (!isSeqTable(relation) || !isSeqTable(target))) {
     return fail("cannot enforce a PostgreSQL foreign key involving a view");
   }