@dynamicalsystems/idl 0.6.1

package/src/kernel/ordinary-authority.v1.ts

@@ -0,0 +1,53 @@
+// dsg.kernel.ordinary-authority/1
+// Owner: dsg-kernel (K02, M029/M030). The canonical ordinary-rights
+// artifact: who may issue law, exactly what they may permit, for how long,
+// and under which three ceilings. Closed and versioned; every set is an
+// explicit allow-list, never an omitted-means-unlimited default. A
+// verified finite enroll_human_root intent binds this document's digest as
+// both plan and resource spec. The revocation view a standing-order check
+// runs against stays in the kernel: independently supplied input, not a
+// wire document.
+//
+// Lifted verbatim from dsg-kernel packages/signing/src/enrollment.ts at
+// 00b33ac1.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, Hex64, NonEmptyString, Orn, UtcSecond, type ProfileEntry } from "../primitives.js";
+
+export const ORDINARY_AUTHORITY_PROFILE = "dsg.kernel.ordinary-authority/1" as const;
+
+const names = Type.Array(NonEmptyString, { minItems: 1, uniqueItems: true });
+const ceilingValue = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+
+const OrdinaryAuthoritySchemaValue = closed({
+  version: Type.Literal(ORDINARY_AUTHORITY_PROFILE),
+  reference: NonEmptyString,
+  actor: Orn,
+  publicKeyHex: Hex64,
+  keyClass: Type.Union([Type.Literal("synthetic-test-only"), Type.Literal("human-authority")]),
+  designation: closed({
+    role: Type.Literal("law-issuer"),
+    designationReference: NonEmptyString,
+  }),
+  scope: closed({
+    scopeReference: NonEmptyString,
+    actions: names,
+    workloadClasses: names,
+    regions: names,
+  }),
+  validity: closed({ notBefore: UtcSecond, notAfter: UtcSecond }),
+  ceilings: closed({
+    gpuSecondsPerPersonUtcWeek: ceilingValue,
+    usdMicroUnitsPerPersonUtcMonth: ceilingValue,
+    usdMicroUnitsPerOrganizationUtcMonth: ceilingValue,
+  }),
+  revoked: Type.Boolean(),
+});
+export const OrdinaryAuthoritySchema: typeof OrdinaryAuthoritySchemaValue =
+  OrdinaryAuthoritySchemaValue;
+export type OrdinaryAuthority = Static<typeof OrdinaryAuthoritySchema>;
+
+export const ordinaryAuthorityV1: ProfileEntry = {
+  literal: ORDINARY_AUTHORITY_PROFILE,
+  rootShape: "authority",
+  shapes: { authority: OrdinaryAuthoritySchema },
+};

package/src/primitives.ts

@@ -0,0 +1,49 @@
+// The shared primitives every profile builds from. No profile defines its
+// own: a digest is Hex64 everywhere, a timestamp is UtcSecond everywhere,
+// an open object exists nowhere.
+import { type TObject, type TProperties, type TSchema, Type } from "@sinclair/typebox";
+import { ORN_PATTERN, SHA256_PATTERN } from "@dynamicalsystems/orn-schemas";
+
+/** Closed object: an extra field is a different protocol. */
+export const closed = <T extends TProperties>(properties: T): TObject<T> =>
+  Type.Object(properties, { additionalProperties: false });
+
+/** Lowercase sha256 hex. Every digest on the wire. */
+export const Hex64 = Type.String({ pattern: "^[0-9a-f]{64}$" });
+
+/** Exact UTC second, Z suffix, no fractional part. */
+export const UtcSecond = Type.String({
+  pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
+});
+
+export const NonEmptyString = Type.String({ minLength: 1 });
+
+export const SafeInt = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+
+/** An ORN, validated by the grammar dsg-orn owns. Built from the exported
+ * pattern, not the exported schema object: the upstream schemas carry
+ * JSON Schema $id metadata, and embedding the same $id in several route
+ * schemas makes validators refuse the duplicate. The pattern is the wire
+ * truth; the metadata is not. */
+export const Orn = Type.String({ pattern: ORN_PATTERN });
+
+/** The pair of an ORN and the sha256 pinning a version (dsg-orn Reference). */
+export const Reference = closed({
+  orn: Orn,
+  sha256: Type.String({ pattern: SHA256_PATTERN }),
+});
+
+/** One wire profile: the literal, and every top-level shape that crosses
+ * the seam it names. Shape names are stable identifiers ("request",
+ * "lease", "refusal"); vectors address a shape as "<literal>#<shape>". */
+export type ProfileEntry = {
+  readonly literal: `dsg.${string}.${string}/${number}`;
+  readonly shapes: Readonly<Record<string, TSchema>>;
+  /** Set ONLY when the wire cannot carry the literal as a field of any
+   * shape (a frozen /1); names exactly where the literal lives instead. */
+  readonly literalNote?: string;
+  /** Names the shape non-TS consumers validate a whole document against;
+   * the emitted JSON Schema gains a root $ref to it. Only meaningful for
+   * profiles with a single document root. */
+  readonly rootShape?: string;
+};

package/src/registry/revocations.v1.ts

@@ -0,0 +1,87 @@
+// dsg.registry.revocations/1
+// Owner: dsg-infra-module-registry (the S03 trust producer). Signed,
+// monotonically versioned revocation snapshots with retained trust
+// history; timestamps are epoch seconds by frozen choice of /1 (recorded
+// in FROZEN_EXEMPTIONS; exact-second strings would be a /2).
+// Lifted verbatim from dsg-infra-module-registry src/revocation.ts at
+// 1f8c994.
+import { Type, type Static } from "@sinclair/typebox";
+import type { ProfileEntry } from "../primitives.js";
+
+export const REVOCATIONS_PROFILE = "dsg.registry.revocations/1" as const;
+
+const closed = { additionalProperties: false };
+const text = Type.String({ minLength: 1 });
+const digest = Type.String({ pattern: "^[0-9a-f]{64}$" });
+const time = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+
+const RevocationSchemaValue = Type.Object(
+  {
+    domain: Type.Literal(REVOCATIONS_PROFILE),
+    version: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+    issuedAt: time,
+    expiresAt: time,
+    previousSha256: Type.Union([digest, Type.Null()]),
+    testOnly: Type.Literal(true),
+    signerKey: digest,
+    revoked: Type.Array(
+      Type.Object(
+        {
+          kind: Type.Union([
+            Type.Literal("principal"),
+            Type.Literal("standing-order"),
+            Type.Literal("law"),
+            Type.Literal("class"),
+            Type.Literal("key"),
+          ]),
+          id: text,
+          effectiveAt: time,
+          reason: text,
+        },
+        closed,
+      ),
+    ),
+    trustHistory: Type.Array(
+      Type.Object(
+        {
+          principal: text,
+          publicKey: digest,
+          role: Type.Union([
+            Type.Literal("human"),
+            Type.Literal("release"),
+            Type.Literal("collector"),
+          ]),
+          action: Type.Union([
+            Type.Literal("enroll"),
+            Type.Literal("rotate"),
+            Type.Literal("compromise"),
+          ]),
+          effectiveAt: time,
+          authoritySha256: digest,
+          replacesKey: Type.Union([digest, Type.Null()]),
+        },
+        closed,
+      ),
+    ),
+  },
+  closed,
+);
+export const RevocationSchema: typeof RevocationSchemaValue = RevocationSchemaValue;
+export type RevocationSnapshot = Static<typeof RevocationSchema>;
+
+const RevocationPointerSchemaValue = Type.Object(
+  {
+    version: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+    sha256: digest,
+    url: Type.String({ pattern: "^/revocations/v/[1-9][0-9]*/snapshot\\.json$" }),
+  },
+  closed,
+);
+export const RevocationPointerSchema: typeof RevocationPointerSchemaValue =
+  RevocationPointerSchemaValue;
+export type RevocationPointer = Static<typeof RevocationPointerSchema>;
+
+export const revocationsV1: ProfileEntry = {
+  literal: REVOCATIONS_PROFILE,
+  shapes: { snapshot: RevocationSchema, pointer: RevocationPointerSchema },
+};

package/src/run/contract-versions.ts

@@ -0,0 +1,13 @@
+// In-process contract versions of the dsg-run plane. Under ruling I7 these
+// are NOT profiles: an executor or provider adapter is a TypeScript plugin
+// interface inside one process, with no serialized shape or digest of its
+// own - its documents (operation requests, descriptors) already have
+// profiles. The literals live here so no consumer repo defines a
+// dsg.*.*/N string and the CI grep stays absolute. When R06 gives
+// executors a real serialized job document, THAT becomes a profile module
+// beside this file.
+export const EXECUTOR_PROTOCOL_VERSION = "dsg.run.executor/1" as const;
+export type ExecutorProtocolVersion = typeof EXECUTOR_PROTOCOL_VERSION;
+
+export const PROVIDER_PROTOCOL_VERSION = "dsg.run.provider/1" as const;
+export type ProviderProtocolVersion = typeof PROVIDER_PROTOCOL_VERSION;

package/src/run/operation.v1.ts

@@ -0,0 +1,158 @@
+// dsg.run.operation/1
+// Owner: dsg-run (the protocol listener accepts the request and answers
+// the receipt; the kernel validates, records and reads back).
+//
+// Closed, versioned compute-operation vocabulary shared by the kernel and
+// the dsg.run plane. The document is deliberately references-only: payload
+// bytes remain retained artifacts, while this request carries the immutable
+// identity, generation fence, law, reservation and plan digest.
+//
+// The envelope digest bound at dispatch (M010) is sha256 over the RFC 8785
+// canonical form of the complete OperationRequest; the digest vectors in
+// the conformance package pin that meaning.
+//
+// Lifted verbatim from dsg-kernel packages/core/src/operation.ts at commit
+// 0f8d64d7 (equal, field for field, to dsg-run service/src/protocol/
+// schemas.ts 134-246 - the R01 cross-validation held). Known /2 candidate,
+// kept loose here because a released /1 is frozen: acceptedAt is
+// minLength 1, not an exact UTC second, and the plane emits fractional
+// seconds today.
+import { type Static, Type } from "@sinclair/typebox";
+import {
+  closed,
+  Hex64,
+  NonEmptyString,
+  Reference,
+  SafeInt,
+  type ProfileEntry,
+} from "../primitives.js";
+
+export const OPERATION_PROFILE = "dsg.run.operation/1" as const;
+
+const ExecutionResourcesSchemaValue = closed({
+  maxGpuSeconds: SafeInt,
+  maxRunSeconds: SafeInt,
+  maxParallelism: SafeInt,
+});
+export const ExecutionResourcesSchema: typeof ExecutionResourcesSchemaValue =
+  ExecutionResourcesSchemaValue;
+export type ExecutionResources = Static<typeof ExecutionResourcesSchema>;
+
+const ExecutionLawSchemaValue = closed({
+  bundle: Reference,
+  registryRelease: Reference,
+});
+export const ExecutionLawSchema: typeof ExecutionLawSchemaValue = ExecutionLawSchemaValue;
+export type ExecutionLaw = Static<typeof ExecutionLawSchema>;
+
+const ExecutionDocumentSchemaValue = closed({
+  schemaVersion: Type.Literal(1),
+  classContract: Reference,
+  law: ExecutionLawSchema,
+  workload: Reference,
+  inputs: Type.Array(Reference),
+  resources: ExecutionResourcesSchema,
+  costBound: Reference,
+  placement: Reference,
+  results: Reference,
+  secrets: Type.Array(Reference),
+});
+export const ExecutionDocumentSchema: typeof ExecutionDocumentSchemaValue =
+  ExecutionDocumentSchemaValue;
+export type ExecutionDocument = Static<typeof ExecutionDocumentSchema>;
+
+const OperationBeforeSchemaValue = closed({
+  operationId: Type.Union([NonEmptyString, Type.Null()]),
+  planDigest: Type.Union([Hex64, Type.Null()]),
+});
+export const OperationBeforeSchema: typeof OperationBeforeSchemaValue = OperationBeforeSchemaValue;
+export type OperationBefore = Static<typeof OperationBeforeSchema>;
+
+const OperationRequestSchemaValue = closed({
+  profile: Type.Literal(OPERATION_PROFILE),
+  operationId: NonEmptyString,
+  case: Reference,
+  workspace: NonEmptyString,
+  expectedGeneration: SafeInt,
+  before: OperationBeforeSchema,
+  planDigest: Hex64,
+  document: ExecutionDocumentSchema,
+  authority: Reference,
+  reservation: Reference,
+});
+export const OperationRequestSchema: typeof OperationRequestSchemaValue =
+  OperationRequestSchemaValue;
+export type OperationRequest = Static<typeof OperationRequestSchema>;
+
+const AcceptedSchemaValue = closed({
+  profile: Type.Literal(OPERATION_PROFILE),
+  operationId: NonEmptyString,
+  actionId: NonEmptyString,
+  generation: SafeInt,
+  planDigest: Hex64,
+  acceptedAt: NonEmptyString,
+});
+export const AcceptedSchema: typeof AcceptedSchemaValue = AcceptedSchemaValue;
+export type Accepted = Static<typeof AcceptedSchema>;
+
+const OperationExecutionSchemaValue = Type.Union([
+  Type.Literal("queued"),
+  Type.Literal("running"),
+  Type.Literal("succeeded"),
+  Type.Literal("failed"),
+  Type.Literal("canceled"),
+  Type.Literal("unknown"),
+]);
+export const OperationExecutionSchema: typeof OperationExecutionSchemaValue =
+  OperationExecutionSchemaValue;
+export type OperationExecution = Static<typeof OperationExecutionSchema>;
+
+const OperationCleanupSchemaValue = Type.Union([
+  Type.Literal("pending"),
+  Type.Literal("present"),
+  Type.Literal("absent"),
+  Type.Literal("unknown"),
+]);
+export const OperationCleanupSchema: typeof OperationCleanupSchemaValue =
+  OperationCleanupSchemaValue;
+export type OperationCleanup = Static<typeof OperationCleanupSchema>;
+
+const OperationEvidenceSchemaValue = Type.Union([Type.Literal("pending"), Type.Literal("ready")]);
+export const OperationEvidenceSchema: typeof OperationEvidenceSchemaValue =
+  OperationEvidenceSchemaValue;
+export type OperationEvidence = Static<typeof OperationEvidenceSchema>;
+
+const OperationCostSchemaValue = Type.Union([
+  Type.Literal("reserved"),
+  Type.Literal("provisional"),
+  Type.Literal("reconciled"),
+]);
+export const OperationCostSchema: typeof OperationCostSchemaValue = OperationCostSchemaValue;
+export type OperationCost = Static<typeof OperationCostSchema>;
+
+const ReadbackSchemaValue = closed({
+  operationId: NonEmptyString,
+  generation: SafeInt,
+  planDigest: Hex64,
+  execution: OperationExecutionSchema,
+  cleanup: OperationCleanupSchema,
+  evidence: OperationEvidenceSchema,
+  evidenceRef: Type.Union([Reference, Type.Null()]),
+  cost: OperationCostSchema,
+});
+export const ReadbackSchema: typeof ReadbackSchemaValue = ReadbackSchemaValue;
+export type Readback = Static<typeof ReadbackSchema>;
+
+// I-001 names the status as the same closed readback shape. Keeping this
+// alias prevents callers from inventing a second status wire contract.
+export const OperationStatusSchema = ReadbackSchema;
+export type OperationStatus = Readback;
+
+export const operationV1: ProfileEntry = {
+  literal: OPERATION_PROFILE,
+  shapes: {
+    request: OperationRequestSchema,
+    accepted: AcceptedSchema,
+    readback: ReadbackSchema,
+  },
+};