@astram/engine 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -19,6 +19,7 @@
  */
 export type { RecordEngine, AccessDeclaration, FieldSpec, FieldType, TrustedSource, IdentityRole, PkStrategy, JunctionSpec, RecordInput, RecordId, RecordView, ListQuery, RecordPage, Principal, ReadScope, ReadScopeCreateMode, } from './types.js';
 export { READ_SCOPE_NODES_TOKEN } from './types.js';
+export { canonicalUuid } from './uuid.js';
 export { EngineError, CapabilityNotSupportedError, RegistrationError, AuthorizationDeniedError, ValidationError, EngineUnavailableError, } from './errors.js';
 export { ObjectType, Field, PrimaryKey, reflectObjectType, type ObjectTypeOptions, type FieldOptions, type PrimaryKeyOptions, } from './decorators/object-type.decorator.js';
 export { AccessBundle, reflectAccessBundle, type AccessBundleOptions, type AccessBundlePermission, type AccessBundleSpec, } from './decorators/access-bundle.decorator.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/E,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAKpD,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE1C,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC/E,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -19,12 +19,17 @@
  *    `@astram/engine/internal`, which only the composition root may import.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MariaDbAuditSink = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = exports.READ_SCOPE_NODES_TOKEN = void 0;
+exports.MariaDbAuditSink = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = exports.canonicalUuid = exports.READ_SCOPE_NODES_TOKEN = void 0;
 // The read-scope subtree-id placeholder token (ADR-0027) — a `subtreeSubquery` template
 // uses it; the engine expands it to a `?`-list. Exported so per-type declarations can
 // reference the canonical token (rather than a stringly-typed duplicate).
 var types_js_1 = require("./types.js");
 Object.defineProperty(exports, "READ_SCOPE_NODES_TOKEN", { enumerable: true, get: function () { return types_js_1.READ_SCOPE_NODES_TOKEN; } });
+// The ONE uuid canonicaliser (Phase 11 #1): strict 8-4-4-4-12 ASCII hex, returned lower-cased;
+// anything else (padded, fullwidth, ...) is null. Guard's `UuidPipe` and the identity body checks
+// use it; consumers may too.
+var uuid_js_1 = require("./uuid.js");
+Object.defineProperty(exports, "canonicalUuid", { enumerable: true, get: function () { return uuid_js_1.canonicalUuid; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "EngineError", { enumerable: true, get: function () { return errors_js_1.EngineError; } });
 Object.defineProperty(exports, "CapabilityNotSupportedError", { enumerable: true, get: function () { return errors_js_1.CapabilityNotSupportedError; } });

package/dist/pipe/stages/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAiDzD,wBAAgB,aAAa,IAAI,KAAK,CAmCrC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/pipe/stages/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAgB,MAAM,eAAe,CAAC;AAiDzD,wBAAgB,aAAa,IAAI,KAAK,CAmCrC"}

package/dist/pipe/stages/validate.js

@@ -11,6 +11,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateStage = validateStage;
 const errors_js_1 = require("../../errors.js");
 const registry_js_1 = require("../../registry.js");
+const uuid_js_1 = require("../../uuid.js");
 const SUPPORTED = new Set([
     'string',
     'number',
@@ -19,7 +20,6 @@ const SUPPORTED = new Set([
     'timestamp',
     'json',
 ]);
-const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
 /** Validate + coerce one value against a field type. Returns the coerced value. */
 function coerce(field, value) {
     switch (field.type) {
@@ -36,11 +36,14 @@ function coerce(field, value) {
             if (typeof value === 'boolean')
                 return value ? 1 : 0; // MariaDB tinyint
             throw new errors_js_1.ValidationError(field.key, 'expected a boolean');
-        case 'uuid':
-            if (typeof value !== 'string' || !UUID_RE.test(value)) {
+        case 'uuid': {
+            // Phase 11 #1: stored uuids are always canonical. A valid upper-case uuid is accepted and
+            // lower-cased (existing writers keep working); padded/fullwidth/other spellings are rejected.
+            const canonical = (0, uuid_js_1.canonicalUuid)(value);
+            if (canonical === null)
                 throw new errors_js_1.ValidationError(field.key, 'expected a uuid');
-            }
-            return value;
+            return canonical;
+        }
         case 'timestamp':
             if (value instanceof Date)
                 return value;

package/dist/uuid.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The ONE uuid canonicaliser (Phase 11 #1). Every framework uuid that crosses a trust boundary
+ * (route param, body field, engine `uuid` field) goes through it.
+ *
+ * Why strict: the uuid columns are `utf8mb4_unicode_ci`, which compares ignoring letter case,
+ * trailing spaces (PAD SPACE) and character width (fullwidth digits/letters). A non-canonical
+ * spelling therefore reaches the stored row in SQL while every JS-side comparison (own root,
+ * platform administrators, `JSON_CONTAINS`, Redis keys, Sets) sees a different id. So: no trimming,
+ * no Unicode normalisation; only the 8-4-4-4-12 ASCII hex form is accepted, and it is returned
+ * lower-cased (the one canonical spelling). Anything else is `null`.
+ */
+/** The canonical (lower-case) form of a uuid, or `null` when `v` is not exactly a uuid. */
+export declare function canonicalUuid(v: unknown): string | null;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,2FAA2F;AAC3F,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEvD"}

package/dist/uuid.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * The ONE uuid canonicaliser (Phase 11 #1). Every framework uuid that crosses a trust boundary
+ * (route param, body field, engine `uuid` field) goes through it.
+ *
+ * Why strict: the uuid columns are `utf8mb4_unicode_ci`, which compares ignoring letter case,
+ * trailing spaces (PAD SPACE) and character width (fullwidth digits/letters). A non-canonical
+ * spelling therefore reaches the stored row in SQL while every JS-side comparison (own root,
+ * platform administrators, `JSON_CONTAINS`, Redis keys, Sets) sees a different id. So: no trimming,
+ * no Unicode normalisation; only the 8-4-4-4-12 ASCII hex form is accepted, and it is returned
+ * lower-cased (the one canonical spelling). Anything else is `null`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalUuid = canonicalUuid;
+// ASCII hex only: without the `u` flag, `i` never folds a non-ASCII character onto A-F, and `$`
+// matches only at the end of input (a trailing newline or space fails).
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** The canonical (lower-case) form of a uuid, or `null` when `v` is not exactly a uuid. */
+function canonicalUuid(v) {
+    return typeof v === 'string' && UUID_RE.test(v) ? v.toLowerCase() : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/engine",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "license": "MIT",
   "description": "Astram framework — the paved road. ONE unbypassable write pipe (resolve-schema → permission gate → derive-write-context → validate → compute → write → junction-sync → audit → emit-event) over real physical tables, that every feature's CRUD flows through. Feature code receives ONLY the RecordEngine facade — never a raw pool/DataSource/QueryRunner (the physical wall). Security-gate + audit are mandatory stages. Missing capability → a typed CapabilityNotSupportedError (the gap-flag STOP). Builds on @astram/core (metadata contract, decide(), audit) + @astram/guard (decision authority).",
   "type": "commonjs",
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "mariadb": "^3.5.4",
-    "@astram/core": "1.4.0"
+    "@astram/core": "1.5.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",