graphddb 0.7.9 → 0.8.0

package/dist/chunk-L4QRCHRQ.js

@@ -0,0 +1,278 @@
+// src/spec/types.ts
+var SPEC_VERSION = "1.1";
+var SPEC_VERSION_SCP = "1.2";
+var SPEC_VERSION_SUPPORTED = SPEC_VERSION_SCP;
+var EXPR_VERSION = 1;
+var MARKER_ROW_ENTITY = "__marker__";
+
+// src/define/transaction.ts
+var TX_REF_BRAND = /* @__PURE__ */ Symbol("graphddb:txref");
+function isTransactionRef(value) {
+  return typeof value === "object" && value !== null && value[TX_REF_BRAND] === true;
+}
+var MARKER_TAGS = [
+  // pass 0: short, begins with 'A'.
+  "Axqv",
+  // pass 1: long, begins with 'Z'. The two tags share NO common prefix and NO
+  // common substring of length >= 2 (their alphabets are disjoint), and differ
+  // in length, so any fragment-extracting / length-dependent transform
+  // (`slice(0,n)`, `[i]`, `charAt`, `padStart`, `padEnd`) yields *different*
+  // fragments across the two passes -- the differential check then rejects it.
+  // (Convergence-to-constant escapes that even disjoint markers cannot separate
+  // -- `slice(0,0)` -> '' in both passes, `includes('x')` -> a constant boolean
+  // -- are caught instead by the per-access coercion ledger; see
+  // {@link makeFieldRef} and {@link defineTransaction}.)
+  "Zmnoprstuwy0123456789WIDEMARKERBODYFILLERZ"
+];
+var MARKER_PASS_COUNT = MARKER_TAGS.length;
+var when = {
+  eq(left, right) {
+    assertRef(left, "when.eq");
+    return { op: "eq", left, right };
+  },
+  ne(left, right) {
+    assertRef(left, "when.ne");
+    return { op: "ne", left, right };
+  }
+};
+function assertRef(value, context) {
+  if (!isTransactionRef(value)) {
+    throw new Error(
+      `defineTransaction: ${context} expects a field reference (e.g. \`p.status\` or an element field) on its left-hand side.`
+    );
+  }
+}
+function isTransactionDefinition(value) {
+  return typeof value === "object" && value !== null && value.__isTransactionDefinition === true;
+}
+function isMultiWriteBody(def) {
+  let writes = 0;
+  for (const instr of def.instructions) {
+    if (instr.kind === "forEach") {
+      return true;
+    }
+    if (instr.operation === "conditionCheck") return true;
+    writes += 1;
+    if (writes > 1) return true;
+  }
+  return writes > 1;
+}
+var SCP_LOWERED_MARKER = "graphddb:scp-lowered/v1";
+
+// src/spec/expression.ts
+var UNARY_OPS = /* @__PURE__ */ new Set(["neg", "not", "len"]);
+var BINARY_OPS = /* @__PURE__ */ new Set([
+  "add",
+  "sub",
+  "mul",
+  "div",
+  "mod",
+  "concat",
+  "eq",
+  "ne",
+  "lt",
+  "le",
+  "gt",
+  "ge",
+  "and",
+  "or",
+  "coalesce"
+]);
+var TERNARY_OPS = /* @__PURE__ */ new Set(["cond"]);
+var ALL_OPS = /* @__PURE__ */ new Set([...UNARY_OPS, ...BINARY_OPS, ...TERNARY_OPS]);
+var I64_MIN = -(2n ** 63n);
+var I64_MAX = 2n ** 63n - 1n;
+function cmpCodePoints(a, b) {
+  const ia = a[Symbol.iterator]();
+  const ib = b[Symbol.iterator]();
+  for (; ; ) {
+    const ra = ia.next();
+    const rb = ib.next();
+    if (ra.done && rb.done) return 0;
+    if (ra.done) return -1;
+    if (rb.done) return 1;
+    const ca = ra.value.codePointAt(0);
+    const cb = rb.value.codePointAt(0);
+    if (ca !== cb) return ca < cb ? -1 : 1;
+  }
+}
+function invalid(context, path, message) {
+  throw new Error(`${context}: invalid SCP expression at ${path}: ${message}`);
+}
+function isPlainObject(v) {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function canonicalizeNode(node, context, path) {
+  if (node === null) return null;
+  if (typeof node === "string" || typeof node === "boolean") return node;
+  if (typeof node === "number") {
+    if (!Number.isFinite(node)) {
+      invalid(context, path, `non-finite number literal (${node}).`);
+    }
+    if (Number.isInteger(node) && !Number.isSafeInteger(node)) {
+      invalid(
+        context,
+        path,
+        `integral number literal ${node} exceeds the safe-integer range; carry it as {int:"${node}"} (expression-ir.md \xA72.3).`
+      );
+    }
+    return node;
+  }
+  if (Array.isArray(node)) {
+    invalid(context, path, "a bare array is not an expression (use {arr:[\u2026]}).");
+  }
+  if (!isPlainObject(node)) {
+    invalid(context, path, `expected a literal or a single-key node object.`);
+  }
+  const keys = Object.keys(node);
+  if (keys.length !== 1) {
+    invalid(
+      context,
+      path,
+      `a node object must have exactly one key, got [${keys.join(", ")}].`
+    );
+  }
+  const key = keys[0];
+  const arg = node[key];
+  if (key === "int") {
+    if (typeof arg !== "string" || !/^-?[0-9]+$/.test(arg)) {
+      invalid(context, `${path}.int`, '{int:"\u2026"} expects an integer string.');
+    }
+    const v = BigInt(arg);
+    if (v < I64_MIN || v > I64_MAX) {
+      invalid(context, `${path}.int`, `int literal ${arg} exceeds i64.`);
+    }
+    if (v >= BigInt(Number.MIN_SAFE_INTEGER) && v <= BigInt(Number.MAX_SAFE_INTEGER)) {
+      return Number(v);
+    }
+    return { int: v.toString() };
+  }
+  if (key === "float") {
+    if (typeof arg !== "number" || !Number.isFinite(arg)) {
+      invalid(context, `${path}.float`, "{float:n} expects a finite number.");
+    }
+    return Number.isInteger(arg) ? { float: arg } : arg;
+  }
+  if (key === "ref" || key === "refOpt") {
+    if (!Array.isArray(arg) || arg.length === 0) {
+      invalid(context, `${path}.${key}`, `{${key}:[\u2026]} expects a non-empty path array.`);
+    }
+    const segs = arg.map((seg, i) => {
+      if (typeof seg !== "string" || seg.length === 0) {
+        invalid(
+          context,
+          `${path}.${key}[${i}]`,
+          "a reference path segment must be a non-empty string."
+        );
+      }
+      return seg;
+    });
+    return key === "ref" ? { ref: segs } : { refOpt: segs };
+  }
+  if (key === "obj") {
+    if (!isPlainObject(arg)) {
+      invalid(context, `${path}.obj`, "{obj:{\u2026}} expects a plain object.");
+    }
+    const out = {};
+    for (const k of Object.keys(arg).sort(cmpCodePoints)) {
+      out[k] = canonicalizeNode(arg[k], context, `${path}.obj.${k}`);
+    }
+    return { obj: out };
+  }
+  if (key === "arr") {
+    if (!Array.isArray(arg)) {
+      invalid(context, `${path}.arr`, "{arr:[\u2026]} expects an array.");
+    }
+    return {
+      arr: arg.map((el, i) => canonicalizeNode(el, context, `${path}.arr[${i}]`))
+    };
+  }
+  if (!ALL_OPS.has(key)) {
+    invalid(
+      context,
+      path,
+      `unknown operator '${key}' \u2014 outside the Expression IR v1 closed set.`
+    );
+  }
+  const op = key;
+  if (!Array.isArray(arg)) {
+    invalid(context, `${path}.${op}`, `'${op}' expects an argument array.`);
+  }
+  const arity = UNARY_OPS.has(op) ? 1 : TERNARY_OPS.has(op) ? 3 : 2;
+  if (arg.length !== arity) {
+    invalid(
+      context,
+      `${path}.${op}`,
+      `'${op}' expects ${arity} argument(s), got ${arg.length}.`
+    );
+  }
+  const args = arg.map((a, i) => canonicalizeNode(a, context, `${path}.${op}[${i}]`));
+  return { [op]: args };
+}
+function canonicalizeExpressionSpec(input, context) {
+  if (!isPlainObject(input)) {
+    throw new Error(
+      `${context}: an SCP expression must be a plain \`{ exprVersion: 1, expr: <node> }\` object.`
+    );
+  }
+  const keys = Object.keys(input).sort();
+  if (keys.length !== 2 || keys[0] !== "expr" || keys[1] !== "exprVersion") {
+    throw new Error(
+      `${context}: an SCP expression envelope must have exactly the keys \`exprVersion\` and \`expr\`; got [${Object.keys(input).join(", ")}].`
+    );
+  }
+  if (input.exprVersion !== EXPR_VERSION) {
+    throw new Error(
+      `${context}: unsupported exprVersion ${JSON.stringify(input.exprVersion)} \u2014 this build understands exprVersion ${EXPR_VERSION} only (fail-closed).`
+    );
+  }
+  return {
+    exprVersion: EXPR_VERSION,
+    expr: canonicalizeNode(input.expr, context, "$")
+  };
+}
+function isScpExprConditionInput(condition) {
+  return "scpExpr" in condition;
+}
+function conditionHasScp(condition) {
+  return condition?.kind === "scpExpr";
+}
+function operationsContainScpNodes(doc) {
+  for (const command of Object.values(doc.commands)) {
+    if (conditionHasScp(command.condition)) return true;
+  }
+  for (const transaction of Object.values(doc.transactions ?? {})) {
+    for (const item of transaction.items) {
+      if (item.guard !== void 0 || conditionHasScp(item.condition)) return true;
+    }
+  }
+  for (const contract of Object.values(doc.contracts ?? {})) {
+    if (contract.kind !== "command") continue;
+    for (const method of Object.values(contract.methods)) {
+      if (method.guard !== void 0) return true;
+    }
+  }
+  return false;
+}
+function operationsSpecVersion(doc) {
+  return operationsContainScpNodes(doc) ? SPEC_VERSION_SCP : SPEC_VERSION;
+}
+
+export {
+  SPEC_VERSION,
+  SPEC_VERSION_SCP,
+  SPEC_VERSION_SUPPORTED,
+  EXPR_VERSION,
+  MARKER_ROW_ENTITY,
+  isTransactionRef,
+  when,
+  isTransactionDefinition,
+  isMultiWriteBody,
+  SCP_LOWERED_MARKER,
+  canonicalizeExpressionSpec,
+  isScpExprConditionInput,
+  operationsContainScpNodes,
+  operationsSpecVersion
+};

package/dist/chunk-LGHSZIEE.js

@@ -0,0 +1,187 @@
+import {
+  evaluateKey
+} from "./chunk-I4LEJ4TF.js";
+import {
+  SPEC_VERSION
+} from "./chunk-L4QRCHRQ.js";
+import {
+  MetadataRegistry
+} from "./chunk-L2NEDS7U.js";
+import {
+  TableMapping
+} from "./chunk-XTWXMOHD.js";
+
+// src/spec/manifest.ts
+var DYNAMO_TYPE_TO_FIELD_TYPE = {
+  S: "string",
+  N: "number",
+  BOOL: "boolean",
+  B: "binary",
+  SS: "stringSet",
+  NS: "numberSet",
+  L: "list",
+  M: "map"
+};
+function sortedRecord(record) {
+  const out = {};
+  for (const key of Object.keys(record).sort()) {
+    out[key] = record[key];
+  }
+  return out;
+}
+function buildKey(key) {
+  if (!key) return null;
+  const { pk, sk } = evaluateKey(key.segmented, "param");
+  return {
+    inputFields: [...key.inputFieldNames],
+    pkTemplate: pk,
+    skTemplate: sk ?? null
+  };
+}
+function buildGsis(metadata) {
+  return [...metadata.gsiDefinitions].sort((a, b) => a.indexName.localeCompare(b.indexName)).map((gsi) => {
+    const { pk, sk } = evaluateKey(gsi.segmented, "param");
+    return {
+      indexName: gsi.indexName,
+      unique: gsi.unique,
+      inputFields: [...gsi.inputFieldNames],
+      pkTemplate: pk,
+      skTemplate: sk ?? null,
+      // Purely-documentary GSI description (issue #166); emitted only when declared
+      // so an undescribed index is byte-identical to the pre-#166 manifest.
+      ...gsi.description !== void 0 ? { description: gsi.description } : {}
+    };
+  });
+}
+function buildRelations(metadata) {
+  const relations = {};
+  for (const rel of metadata.relations) {
+    const targetClass = rel.targetFactory();
+    relations[rel.propertyName] = {
+      type: rel.type,
+      target: targetClass.name,
+      keyBinding: { ...rel.keyBinding },
+      // List-valued source descriptor for a `refs` relation (issue #197); emitted
+      // only for `refs` so a scalar-keyed relation is byte-identical to the pre-#197
+      // manifest.
+      ...rel.refs !== void 0 ? { refs: { ...rel.refs } } : {},
+      // Purely-documentary relation description (issue #166); emitted only when
+      // declared so an undescribed relation is byte-identical to the pre-#166 manifest.
+      ...rel.options?.description !== void 0 ? { description: rel.options.description } : {}
+    };
+  }
+  return sortedRecord(relations);
+}
+function buildFields(metadata) {
+  const fields = {};
+  for (const field of metadata.fields) {
+    const format = field.options?.format;
+    const description = field.options?.description;
+    fields[field.propertyName] = {
+      type: DYNAMO_TYPE_TO_FIELD_TYPE[field.dynamoType],
+      ...format ? { format } : {},
+      ...description !== void 0 ? { description } : {}
+    };
+  }
+  return sortedRecord(fields);
+}
+function buildManifestEntity(metadata) {
+  return buildEntity(metadata);
+}
+function buildEntity(metadata) {
+  return {
+    table: metadata.tableName,
+    physicalName: TableMapping.resolve(metadata.tableName),
+    prefix: metadata.prefix,
+    fields: buildFields(metadata),
+    key: buildKey(metadata.primaryKey),
+    gsis: buildGsis(metadata),
+    relations: buildRelations(metadata),
+    ...metadata.description !== void 0 ? { description: metadata.description } : {},
+    // TTL (issue #172, Epic #167 — C4): a physical-schema fact carried on the
+    // manifest so the CFn emitter can render `TimeToLiveSpecification`. Absent
+    // when no `@ttl` field is declared (byte-identical to the pre-#172 manifest).
+    ...metadata.ttlAttribute !== void 0 ? { ttlAttribute: metadata.ttlAttribute } : {}
+  };
+}
+function buildManifest(registry = MetadataRegistry) {
+  const all = registry.getAll();
+  const entitiesByName = /* @__PURE__ */ new Map();
+  for (const [cls, metadata] of all) {
+    entitiesByName.set(cls.name, metadata);
+  }
+  const entities = {};
+  const tables = {};
+  const ttlByPhysicalTable = /* @__PURE__ */ new Map();
+  for (const name of [...entitiesByName.keys()].sort()) {
+    const metadata = entitiesByName.get(name);
+    entities[name] = buildEntity(metadata);
+    const physicalName = TableMapping.resolve(metadata.tableName);
+    tables[metadata.tableName] = {
+      physicalName
+    };
+    if (metadata.ttlAttribute !== void 0) {
+      const existing = ttlByPhysicalTable.get(physicalName);
+      if (existing && existing.attr !== metadata.ttlAttribute) {
+        throw new Error(
+          `Manifest build: physical table '${physicalName}' has more than one TTL attribute \u2014 entity '${existing.entity}' declares \`@ttl\` on '${existing.attr}' and entity '${name}' on '${metadata.ttlAttribute}'. DynamoDB allows exactly one TTL attribute per table; align the \`@ttl\` attribute across all entities sharing this table (or drop one).`
+        );
+      }
+      if (!existing) {
+        ttlByPhysicalTable.set(physicalName, {
+          entity: name,
+          attr: metadata.ttlAttribute
+        });
+      }
+    }
+  }
+  return {
+    version: SPEC_VERSION,
+    tables: sortedRecord(tables),
+    entities
+  };
+}
+
+// src/spec/prepared-artifact.ts
+var PREPARED_FORMAT_VERSION = "2";
+function canonicalJson(value) {
+  return JSON.stringify(value, (_k, v) => {
+    if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      const sorted = {};
+      for (const key of Object.keys(v).sort()) {
+        sorted[key] = v[key];
+      }
+      return sorted;
+    }
+    return v;
+  });
+}
+var FNV64_OFFSET_BASIS = 0xcbf29ce484222325n;
+var FNV64_PRIME = 0x100000001b3n;
+var U64_MASK = 0xffffffffffffffffn;
+function fnv1a64Hex(input) {
+  let hash = FNV64_OFFSET_BASIS;
+  for (let i = 0; i < input.length; i++) {
+    const unit = input.charCodeAt(i);
+    hash ^= BigInt(unit & 255);
+    hash = hash * FNV64_PRIME & U64_MASK;
+    hash ^= BigInt(unit >>> 8);
+    hash = hash * FNV64_PRIME & U64_MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+function entityFingerprint(metadata) {
+  return fnv1a64Hex(canonicalJson(buildManifestEntity(metadata)));
+}
+function planFingerprint(plan) {
+  return fnv1a64Hex(canonicalJson(plan));
+}
+
+export {
+  buildManifestEntity,
+  buildManifest,
+  PREPARED_FORMAT_VERSION,
+  canonicalJson,
+  entityFingerprint,
+  planFingerprint
+};