@xemahq/xema 0.59.0 → 0.60.1

package/edition/operation-requirements.mjs

@@ -1,282 +0,0 @@
-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

@@ -1,35 +0,0 @@
-// 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);
-  });
-}