@xemahq/edition-tooling 0.0.0-stage → 0.1.1

package/edition/operation-requirements.mjs

@@ -0,0 +1,282 @@
+import { createRequire } from 'node:module';
+
+import { kernelDistPath } from './edition-workspace.mjs';
+import { compareStrings } from './string-order.mjs';
+
+const requireFromHere = createRequire(import.meta.url);
+
+let kernelPrivilegeGrammars;
+let kernelAudienceGrammars;
+
+/**
+ * The kernel's ONE operation-id grammar (`OperationIdSchema`) and closed
+ * `PlatformSweep` vocabulary, from the distribution subpath: the only plane
+ * the edition protocol exposes to this library.
+ */
+function loadKernelPrivilegeGrammars() {
+  if (kernelPrivilegeGrammars) {return kernelPrivilegeGrammars;}
+  const mod = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  if (
+    typeof mod.OperationIdSchema?.safeParse !== 'function' ||
+    typeof mod.PlatformSweepSchema?.safeParse !== 'function' ||
+    typeof mod.DeclaredEventSubscriptionClauseSchema?.safeParse !== 'function' ||
+    typeof mod.canonicalEventSubscriptionClauses !== 'function'
+  ) {
+    throw new Error(
+      `Built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} does not export ` +
+        'OperationIdSchema, PlatformSweepSchema, DeclaredEventSubscriptionClauseSchema and canonicalEventSubscriptionClauses — the dist is stale; rebuild kernel-contracts at a commit that carries them.',
+    );
+  }
+  kernelPrivilegeGrammars = mod;
+  return mod;
+}
+
+/**
+ * The kernel's exact-audience and audience-namespace grammars, as ELEMENT schemas.
+ * The edition protocol exposes no subpath that exports the element grammars, so each is read
+ * from the one list schema the distribution subpath does export
+ * (`PlatformServiceSourceIdentitySchema.shape.requiresAudiences` / `.ownsAudienceNamespaces`):
+ * a value is graded as a one-element list, and the parsed element is returned.
+ */
+function loadKernelAudienceGrammars() {
+  if (kernelAudienceGrammars) {return kernelAudienceGrammars;}
+  const mod = requireFromHere(kernelDistPath('distribution', 'index.js'));
+  const shape = mod.PlatformServiceSourceIdentitySchema?.shape;
+  const elementSchema = (listField) => {
+    const list = shape?.[listField]?.unwrap?.();
+    if (typeof list?.safeParse !== 'function') {
+      throw new Error(
+        `Built kernel distribution module at ${kernelDistPath('distribution', 'index.js')} has no PlatformServiceSourceIdentitySchema.${listField} — ` +
+          'the dist is stale; rebuild kernel-contracts at a commit that carries the index-row audience fields.',
+      );
+    }
+    return {
+      safeParse: (value) => {
+        const parsed = list.safeParse([value]);
+        return parsed.success ? { success: true, data: parsed.data[0] } : parsed;
+      },
+    };
+  };
+  kernelAudienceGrammars = {
+    ExactAudienceSchema: elementSchema('requiresAudiences'),
+    AudienceNamespaceSchema: elementSchema('ownsAudienceNamespaces'),
+    PeerServiceNameSchema: elementSchema('optionalPeers'),
+  };
+  return kernelAudienceGrammars;
+}
+
+/**
+ * One component's declared privilege list, as the index carries it: sorted,
+ * unique, every entry graded by the kernel schema. `null` when undeclared. An
+ * empty list, a repeat or an invalid entry REFUSES naming the manifest: this
+ * reads the RAW manifest, and the kernel's component schema is not applied on
+ * this path.
+ */
+export function declaredPrivilegeList(component, where, field, schema, what) {
+  const declared = component[field];
+  if (declared === undefined) {return null;}
+  if (!Array.isArray(declared) || declared.length === 0) {
+    throw new Error(
+      `${where} declares ${field} that is not a non-empty array of ${what}s — ` +
+        'a list that names nothing states nothing, so omit the field',
+    );
+  }
+  const values = declared.map((value, position) => {
+    const parsed = schema.safeParse(value);
+    if (!parsed.success) {
+      throw new Error(
+        `${where} ${field}[${position}] ${JSON.stringify(value)} is not ${/^[aeiou]/.test(what) ? 'an' : 'a'} ${what}: ` +
+          parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return parsed.data;
+  });
+  const unique = [...new Set(values)];
+  if (unique.length !== values.length) {
+    const repeated = values.find((value, position) => values.indexOf(value) !== position);
+    throw new Error(`${where} ${field} names ${repeated} more than once`);
+  }
+  return unique.sort(compareStrings);
+}
+
+/**
+ * The service-to-service operations one workload component declares it needs
+ * (`requiresOperations`), graded by the kernel's one operation-id grammar.
+ * Declared INTENT only; the seal admits or refuses each (`admitOperationGrants`).
+ */
+export function componentOperationRequirements(component, where) {
+  const { OperationIdSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requiresOperations', OperationIdSchema, 'operation id');
+}
+
+/**
+ * The operations one workload component uses only when their owner is served
+ * (`optionalOperations`), graded exactly like `requiresOperations`. Declared
+ * INTENT only: the seal grants each one whose owner is served, leaves it
+ * ungranted when the owner is absent, and refuses one listed in both lists
+ * (`admitOperationGrants`).
+ */
+export function componentOptionalOperationRequirements(component, where) {
+  const { OperationIdSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'optionalOperations', OperationIdSchema, 'operation id');
+}
+
+/**
+ * The operations one workload component asks to exercise for the organization
+ * that installs its biome (`requestsInstalledOperations`), graded by the same
+ * operation-id grammar. Declared INTENT only; the lock admits the ceiling of
+ * the request (`admitInstalledOperationCeiling`), and an installed operation is
+ * never a deployment grant.
+ */
+export function componentInstalledOperationRequests(component, where) {
+  const { OperationIdSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requestsInstalledOperations', OperationIdSchema, 'operation id');
+}
+
+/**
+ * The organization sweeps one workload component declares it may hold
+ * (`requiresOrganizationSweeps`), each a member of the kernel's closed
+ * `PlatformSweep`. A sweep's reach is fixed by the kernel, never declared.
+ * Declared INTENT only; the seal admits or refuses each (`admitOrganizationSweeps`).
+ */
+export function componentOrganizationSweepRequirements(component, where) {
+  const { PlatformSweepSchema } = loadKernelPrivilegeGrammars();
+  return declaredPrivilegeList(component, where, 'requiresOrganizationSweeps', PlatformSweepSchema, 'platform sweep');
+}
+
+/**
+ * The exact audiences one workload component requires (`requiresAudiences`),
+ * graded by the kernel's exact-audience grammar (no wildcard, no prefix).
+ * Declared INTENT only; `admitExactAudiences` admits or refuses each.
+ */
+export function componentAudienceRequirements(component, where) {
+  const { ExactAudienceSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'requiresAudiences', ExactAudienceSchema, 'exact audience');
+}
+
+/**
+ * The audience namespaces one workload component owns (`ownsAudienceNamespaces`),
+ * graded by the kernel's namespace grammar.
+ */
+export function componentOwnedAudienceNamespaces(component, where) {
+  const { AudienceNamespaceSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'ownsAudienceNamespaces', AudienceNamespaceSchema, 'audience namespace');
+}
+
+/**
+ * The peer services one platform service uses only when they are served
+ * (`optionalPeers`, edition protocol v38), each graded by the kernel's peer
+ * service name grammar. Declared INTENT only; `null` when undeclared.
+ */
+export function componentOptionalPeers(component, where) {
+  const { PeerServiceNameSchema } = loadKernelAudienceGrammars();
+  return declaredPrivilegeList(component, where, 'optionalPeers', PeerServiceNameSchema, 'peer service name');
+}
+
+/**
+ * The event subscription clauses one workload component declares
+ * (`subscribesEvents`), each graded by the kernel's clause grammar and returned
+ * in the kernel's canonical order, as the lock carries them
+ * (`eventSubscriptionRequirements`). An empty list, a repeated clause or an
+ * invalid one REFUSES naming the manifest; `null` when undeclared. Declared
+ * INTENT only; the lock admits it (`admitEventSubscriptions`).
+ */
+export function componentEventSubscriptionRequirements(component, where) {
+  const { DeclaredEventSubscriptionClauseSchema, canonicalEventSubscriptionClauses } = loadKernelPrivilegeGrammars();
+  const declared = component.subscribesEvents;
+  if (declared === undefined) {return null;}
+  if (!Array.isArray(declared) || declared.length === 0) {
+    throw new Error(
+      `${where} declares subscribesEvents that is not a non-empty array of event subscription clauses — ` +
+        'a list that names nothing states nothing, so omit the field',
+    );
+  }
+  const clauses = declared.map((value, position) => {
+    const parsed = DeclaredEventSubscriptionClauseSchema.safeParse(value);
+    if (!parsed.success) {
+      throw new Error(
+        `${where} subscribesEvents[${position}] ${JSON.stringify(value)} is not an event subscription clause: ` +
+          parsed.error.issues.map((issue) => issue.message).join('; '),
+      );
+    }
+    return parsed.data;
+  });
+  const canonical = canonicalEventSubscriptionClauses(clauses);
+  if (canonical.length !== clauses.length) {
+    throw new Error(`${where} subscribesEvents lists the same clause more than once`);
+  }
+  return canonical;
+}
+
+/**
+ * Whether one workload component declares `relaysOrgContext`: the privilege to
+ * relay an organization context its caller handed it. The only legal value is
+ * `true` (the kernel's component grammar); absent means it does not relay.
+ * Declared INTENT only; the lock admits it (`admitOrgContextRelays`).
+ */
+export function componentRelaysOrgContext(component, where) {
+  const declared = component.relaysOrgContext;
+  if (declared === undefined) {return false;}
+  if (declared !== true) {
+    throw new Error(
+      `${where} declares relaysOrgContext ${JSON.stringify(declared)} — the only legal value is true; omit the field to not relay`,
+    );
+  }
+  return true;
+}
+
+/**
+ * The privilege declarations a component may carry only if it is a workload
+ * principal in the lock.
+ */
+export const PRINCIPAL_PRIVILEGE_FIELDS = Object.freeze([
+  'requiresOperations',
+  'optionalOperations',
+  'requestsInstalledOperations',
+  'relaysOrgContext',
+  'subscribesEvents',
+  'requiresOrganizationSweeps',
+  'requiresAudiences',
+  'ownsAudienceNamespaces',
+]);
+
+/**
+ * Thrown when a component that has no workload principal in the lock declares
+ * a privilege. A principal is a rostered image component: a service (under its
+ * `protocol.serviceName`) or a worker (under its key). A job, an imageless
+ * component or a content/web/adapter component is never one, so its
+ * declaration could never be admitted; it is refused rather than dropped.
+ */
+export class PrivilegeWithoutPrincipalError extends Error {
+  /**
+   * @param {string} manifest the manifest path
+   * @param {string} component the component key
+   * @param {string} field the privilege field it declares
+   */
+  constructor(manifest, component, field) {
+    super(
+      `${manifest}: xema.components[] "${component}" declares ${field}, but it has no ` +
+        'workload principal in the lock (only a service or worker image component is one), ' +
+        'so the declaration could never be admitted',
+    );
+    this.name = 'PrivilegeWithoutPrincipalError';
+    this.manifest = manifest;
+    this.component = component;
+    this.field = field;
+  }
+}
+
+/**
+ * Refuse every privilege declaration on a component outside `principals`
+ * (the components that become lock workloads). Never drops one silently.
+ */
+export function assertPrivilegesHavePrincipals(components, principals, manifest) {
+  for (const component of components) {
+    if (component === null || typeof component !== 'object' || principals.includes(component)) {continue;}
+    for (const field of PRINCIPAL_PRIVILEGE_FIELDS) {
+      if (component[field] !== undefined) {
+        throw new PrivilegeWithoutPrincipalError(manifest, String(component.key ?? component.name ?? '?'), field);
+      }
+    }
+  }
+}

package/edition/oras-process.mjs

@@ -0,0 +1,35 @@
+// oras-process — run the oras binary WITHOUT blocking the event loop.
+//
+// A blocking `execFileSync` turns every caller's worker pool into a queue of
+// one: six "concurrent" subjects still ran their registry calls one after the
+// other. This runner spawns the child and resolves on its exit, so the pool's
+// width is the real concurrency.
+
+import { execFile } from 'node:child_process';
+
+/**
+ * Run `file` with `args` (in `cwd` when given); resolve with stdout bytes. A failure rejects with the
+ * child's stderr text on `error.stderr` (a string), so the caller reads the
+ * registry status from what oras itself wrote.
+ */
+export function runExecutable(file, args, { input, env, cwd, timeoutMs, maxBufferBytes }) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      file,
+      args,
+      { env, ...(cwd === undefined ? {} : { cwd }), timeout: timeoutMs, maxBuffer: maxBufferBytes, encoding: 'buffer' },
+      (error, stdout, stderr) => {
+        if (error) {
+          error.stderr = stderr.toString('utf8');
+          reject(error);
+          return;
+        }
+        resolve(stdout);
+      },
+    );
+    // A child that exits without reading its stdin must not crash the process
+    // with EPIPE; the exit status already carries the failure.
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}