@dynamicalsystems/idl 0.7.1 → 0.9.0

package/schema/dsg-run-run-summary-v1.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/DynamicalSystemsGroup/dsg-idl/schema/dsg-run-run-summary-v1.json",
+  "title": "dsg.run.run-summary/1",
+  "$defs": {
+    "summary": {
+      "additionalProperties": false,
+      "type": "object",
+      "required": ["profile", "runId", "experimentDigest", "requester", "decision", "waitingOn"],
+      "properties": {
+        "profile": {
+          "const": "dsg.run.run-summary/1",
+          "type": "string"
+        },
+        "runId": {
+          "minLength": 1,
+          "type": "string"
+        },
+        "experimentDigest": {
+          "pattern": "^[0-9a-f]{64}$",
+          "type": "string"
+        },
+        "requester": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "type": "object",
+              "required": ["principal", "displayName", "source"],
+              "properties": {
+                "principal": {
+                  "pattern": "^orn:[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*){3}:(?:[A-Za-z0-9\\-._~:/@]|%[0-9A-Fa-f]{2})+$",
+                  "type": "string"
+                },
+                "displayName": {
+                  "minLength": 1,
+                  "type": "string"
+                },
+                "source": {
+                  "minLength": 1,
+                  "type": "string"
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "decision": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "type": "object",
+              "required": ["outcome", "decider", "decidedAt", "cause", "byStandingOrder"],
+              "properties": {
+                "outcome": {
+                  "anyOf": [
+                    {
+                      "const": "approved",
+                      "type": "string"
+                    },
+                    {
+                      "const": "refused",
+                      "type": "string"
+                    }
+                  ]
+                },
+                "decider": {
+                  "additionalProperties": false,
+                  "type": "object",
+                  "required": ["principal", "displayName", "source"],
+                  "properties": {
+                    "principal": {
+                      "pattern": "^orn:[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*){3}:(?:[A-Za-z0-9\\-._~:/@]|%[0-9A-Fa-f]{2})+$",
+                      "type": "string"
+                    },
+                    "displayName": {
+                      "minLength": 1,
+                      "type": "string"
+                    },
+                    "source": {
+                      "minLength": 1,
+                      "type": "string"
+                    }
+                  }
+                },
+                "decidedAt": {
+                  "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$",
+                  "type": "string"
+                },
+                "cause": {
+                  "anyOf": [
+                    {
+                      "minLength": 1,
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "byStandingOrder": {
+                  "type": "boolean"
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "waitingOn": {
+          "anyOf": [
+            {
+              "minLength": 1,
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    }
+  },
+  "$ref": "#/$defs/summary"
+}

package/src/core/identity-binding.v1.ts

@@ -0,0 +1,26 @@
+// dsg.core.identity-binding/1
+// Owner: dsg-kernel. A binding is a signed act through the door.
+// The CLI signs; the plane forwards; the kernel verifies and appends.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, NonEmptyString, Orn, UtcSecond, type ProfileEntry } from "../primitives.js";
+
+export const IDENTITY_BINDING_PROFILE = "dsg.core.identity-binding/1" as const;
+export const GOOGLE_SIGN_IN_ISSUER = "https://accounts.google.com" as const;
+
+const IdentityBindingSchemaValue = closed({
+  profile: Type.Literal(IDENTITY_BINDING_PROFILE),
+  principal: Orn,
+  issuer: Type.Literal(GOOGLE_SIGN_IN_ISSUER),
+  subject: NonEmptyString,
+  decider: Orn,
+  boundAt: UtcSecond,
+  signature: NonEmptyString,
+});
+export const IdentityBindingSchema: typeof IdentityBindingSchemaValue = IdentityBindingSchemaValue;
+export type IdentityBinding = Static<typeof IdentityBindingSchema>;
+
+export const identityBindingV1: ProfileEntry = {
+  literal: IDENTITY_BINDING_PROFILE,
+  rootShape: "binding",
+  shapes: { binding: IdentityBindingSchema },
+};

package/src/core/refusal.v1.ts

@@ -0,0 +1,45 @@
+// dsg.core.refusal/1
+// Owner: shared. Kernel, plane, and console read this one envelope.
+// Identity ladder codes are identity-verifier-spec.md section 3.5.
+// Login and request codes are person-loop-spec.md sections 4.1 and 4.2.
+// The sentence is what a person hears; identifiers do not belong here.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, NonEmptyString, type ProfileEntry } from "../primitives.js";
+
+export const REFUSAL_PROFILE = "dsg.core.refusal/1" as const;
+
+const RefusalCodeSchemaValue = Type.Union([
+  Type.Literal("assertion_invalid"),
+  Type.Literal("audience_mismatch"),
+  Type.Literal("expired"),
+  Type.Literal("issuer_unknown"),
+  Type.Literal("transport_unverified"),
+  Type.Literal("relay_untrusted"),
+  Type.Literal("identity_unbound"),
+  Type.Literal("binding_expired"),
+  Type.Literal("principal_suspended"),
+  Type.Literal("not_dsg_account"),
+  Type.Literal("session_expired"),
+  Type.Literal("unknown_workload_class"),
+  Type.Literal("image_not_pinned"),
+  Type.Literal("not_a_requester"),
+  Type.Literal("document_invalid"),
+  Type.Literal("self_decision"),
+  Type.Literal("no_ceiling"),
+]);
+export const RefusalCodeSchema: typeof RefusalCodeSchemaValue = RefusalCodeSchemaValue;
+export type RefusalCode = Static<typeof RefusalCodeSchema>;
+
+const RefusalSchemaValue = closed({
+  profile: Type.Literal(REFUSAL_PROFILE),
+  code: RefusalCodeSchema,
+  sentence: NonEmptyString,
+});
+export const RefusalSchema: typeof RefusalSchemaValue = RefusalSchemaValue;
+export type Refusal = Static<typeof RefusalSchema>;
+
+export const refusalV1: ProfileEntry = {
+  literal: REFUSAL_PROFILE,
+  rootShape: "refusal",
+  shapes: { refusal: RefusalSchema },
+};

package/src/core/refusal.v2.ts

@@ -0,0 +1,47 @@
+// dsg.core.refusal/2
+// Owner: shared. Adds the two codes the shared authentication contract
+// requires: a validator that cannot answer fails closed and says so, and a
+// human confirmation outside its window is its own refusal, not a generic
+// expiry. /1 is frozen; this ships beside it.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, NonEmptyString, type ProfileEntry } from "../primitives.js";
+
+export const REFUSAL_V2_PROFILE = "dsg.core.refusal/2" as const;
+
+const RefusalCodeV2SchemaValue = Type.Union([
+  Type.Literal("assertion_invalid"),
+  Type.Literal("audience_mismatch"),
+  Type.Literal("expired"),
+  Type.Literal("issuer_unknown"),
+  Type.Literal("transport_unverified"),
+  Type.Literal("relay_untrusted"),
+  Type.Literal("identity_unbound"),
+  Type.Literal("binding_expired"),
+  Type.Literal("principal_suspended"),
+  Type.Literal("not_dsg_account"),
+  Type.Literal("session_expired"),
+  Type.Literal("unknown_workload_class"),
+  Type.Literal("image_not_pinned"),
+  Type.Literal("not_a_requester"),
+  Type.Literal("document_invalid"),
+  Type.Literal("self_decision"),
+  Type.Literal("no_ceiling"),
+  Type.Literal("validation_unavailable"),
+  Type.Literal("confirmation_expired"),
+]);
+export const RefusalCodeV2Schema: typeof RefusalCodeV2SchemaValue = RefusalCodeV2SchemaValue;
+export type RefusalCodeV2 = Static<typeof RefusalCodeV2Schema>;
+
+const RefusalV2SchemaValue = closed({
+  profile: Type.Literal(REFUSAL_V2_PROFILE),
+  code: RefusalCodeV2Schema,
+  sentence: NonEmptyString,
+});
+export const RefusalV2Schema: typeof RefusalV2SchemaValue = RefusalV2SchemaValue;
+export type RefusalV2 = Static<typeof RefusalV2Schema>;
+
+export const refusalV2: ProfileEntry = {
+  literal: REFUSAL_V2_PROFILE,
+  rootShape: "refusal",
+  shapes: { refusal: RefusalV2Schema },
+};

package/src/index.ts

@@ -1,4 +1,13 @@
-export { closed, Hex64, NonEmptyString, Orn, Reference, SafeInt, UtcSecond } from "./primitives.js";
+export {
+  closed,
+  Hex64,
+  NonEmptyString,
+  Orn,
+  PersonReference,
+  Reference,
+  SafeInt,
+  UtcSecond,
+} from "./primitives.js";
 export type { ProfileEntry } from "./primitives.js";
 export {
   DISPATCH_CONSUME_PROFILE,
@@ -76,6 +85,20 @@ export type {
   BootstrapIntent,
   SignedBootstrapIntent,
 } from "./kernel/bootstrap.v1.js";
+export {
+  STANDING_ORDER_ACTIVATION_EVENT_KIND,
+  STANDING_ORDER_ACTIVATION_PROFILE,
+  StandingOrderActivationEventSchema,
+  StandingOrderActivationSchema,
+  StandingOrderModeSchema,
+  SignedStandingOrderActivationSchema,
+} from "./kernel/standing-order-activation.v1.js";
+export type {
+  StandingOrderActivation,
+  StandingOrderActivationEvent,
+  StandingOrderMode,
+  SignedStandingOrderActivation,
+} from "./kernel/standing-order-activation.v1.js";
 export {
   ORDINARY_AUTHORITY_PROFILE,
   OrdinaryAuthoritySchema,
@@ -91,17 +114,49 @@ export {
   EventStreamSealSchema,
 } from "./run/event.v1.js";
 export type { Event, EventStreamSeal } from "./run/event.v1.js";
+export {
+  REQUEST_PROFILE,
+  ExperimentRefSchema,
+  RequestCeilingsSchema,
+  RunRequestSchema,
+} from "./run/request.v1.js";
+export type { ExperimentRef, RequestCeilings, RunRequest } from "./run/request.v1.js";
+export { DECISION_PROFILE, RunDecisionSchema } from "./run/decision.v1.js";
+export type { RunDecision } from "./run/decision.v1.js";
+export {
+  RUN_SUMMARY_PROFILE,
+  RunSummaryDecisionSchema,
+  RunSummarySchema,
+} from "./run/run-summary.v1.js";
+export type { RunSummary, RunSummaryDecision } from "./run/run-summary.v1.js";
+export { REFUSAL_PROFILE, RefusalCodeSchema, RefusalSchema } from "./core/refusal.v1.js";
+export type { Refusal, RefusalCode } from "./core/refusal.v1.js";
+export { REFUSAL_V2_PROFILE, RefusalCodeV2Schema, RefusalV2Schema } from "./core/refusal.v2.js";
+export type { RefusalCodeV2, RefusalV2 } from "./core/refusal.v2.js";
+export {
+  GOOGLE_SIGN_IN_ISSUER,
+  IDENTITY_BINDING_PROFILE,
+  IdentityBindingSchema,
+} from "./core/identity-binding.v1.js";
+export type { IdentityBinding } from "./core/identity-binding.v1.js";
 
 import type { ProfileEntry } from "./primitives.js";
 import { dispatchConsumeV1 } from "./kernel/dispatch-consume.v1.js";
 import { operationV1 } from "./run/operation.v1.js";
 import { eventV1 } from "./run/event.v1.js";
+import { requestV1 } from "./run/request.v1.js";
+import { decisionV1 } from "./run/decision.v1.js";
+import { runSummaryV1 } from "./run/run-summary.v1.js";
+import { refusalV1 } from "./core/refusal.v1.js";
+import { refusalV2 } from "./core/refusal.v2.js";
+import { identityBindingV1 } from "./core/identity-binding.v1.js";
 import { signedLawV1 } from "./infra/signed-law.v1.js";
 import { resourceDescriptorV1 } from "./infra/resource-descriptor.v1.js";
 import { adoptionFactV1 } from "./infra/adoption-fact.v1.js";
 import { revocationsV1 } from "./registry/revocations.v1.js";
 import { bootstrapV1 } from "./kernel/bootstrap.v1.js";
 import { ordinaryAuthorityV1 } from "./kernel/ordinary-authority.v1.js";
+import { standingOrderActivationV1 } from "./kernel/standing-order-activation.v1.js";
 
 /** Every profile this version of the package defines, keyed by literal.
  * Profile modules are added here as they are extracted; the rules test
@@ -111,10 +166,17 @@ export const PROFILES: Readonly<Record<string, ProfileEntry>> = {
   [dispatchConsumeV1.literal]: dispatchConsumeV1,
   [operationV1.literal]: operationV1,
   [eventV1.literal]: eventV1,
+  [requestV1.literal]: requestV1,
+  [decisionV1.literal]: decisionV1,
+  [runSummaryV1.literal]: runSummaryV1,
+  [refusalV1.literal]: refusalV1,
+  [refusalV2.literal]: refusalV2,
+  [identityBindingV1.literal]: identityBindingV1,
   [signedLawV1.literal]: signedLawV1,
   [resourceDescriptorV1.literal]: resourceDescriptorV1,
   [adoptionFactV1.literal]: adoptionFactV1,
   [revocationsV1.literal]: revocationsV1,
   [bootstrapV1.literal]: bootstrapV1,
   [ordinaryAuthorityV1.literal]: ordinaryAuthorityV1,
+  [standingOrderActivationV1.literal]: standingOrderActivationV1,
 };

package/src/kernel/standing-order-activation.v1.ts

@@ -0,0 +1,72 @@
+// dsg.kernel.standing-order-activation/1
+// Owner: dsg-kernel. The record event selects the one standing-order
+// activation that API and worker may resolve. The revocation reference is
+// the activation-time observation only; consumers must independently resolve
+// the current revocation head before every authority use.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, Orn, Reference, UtcSecond, type ProfileEntry } from "../primitives.js";
+
+export const STANDING_ORDER_ACTIVATION_PROFILE = "dsg.kernel.standing-order-activation/1" as const;
+export const STANDING_ORDER_ACTIVATION_EVENT_KIND = "standing_order_activated" as const;
+
+const StandingOrderModeSchemaValue = Type.Union([
+  Type.Literal("synthetic-test-only"),
+  Type.Literal("human-authority"),
+]);
+export const StandingOrderModeSchema: typeof StandingOrderModeSchemaValue =
+  StandingOrderModeSchemaValue;
+export type StandingOrderMode = Static<typeof StandingOrderModeSchema>;
+
+/** The immutable descriptor retained with the activation event. */
+const StandingOrderActivationSchemaValue = closed({
+  profile: Type.Literal(STANDING_ORDER_ACTIVATION_PROFILE),
+  /** Stable identity carried in the descriptor. The event's `activation`
+   * reference points to this descriptor, avoiding a digest cycle. */
+  activationId: Orn,
+  /** Compare-and-set precondition. Null is valid only for the first head. */
+  expectedPreviousActivation: Type.Union([Reference, Type.Null()]),
+  law: Reference,
+  enrollment: Reference,
+  intent: Reference,
+  roots: Reference,
+  /** Activation-time observation. It never substitutes for a current read. */
+  revocation: Reference,
+  actor: Orn,
+  mode: StandingOrderModeSchema,
+  activatedAt: UtcSecond,
+});
+export const StandingOrderActivationSchema: typeof StandingOrderActivationSchemaValue =
+  StandingOrderActivationSchemaValue;
+export type StandingOrderActivation = Static<typeof StandingOrderActivationSchema>;
+
+/** Append-only record event carrying the descriptor selected by the stream head. */
+const StandingOrderActivationEventSchemaValue = closed({
+  profile: Type.Literal(STANDING_ORDER_ACTIVATION_PROFILE),
+  kind: Type.Literal(STANDING_ORDER_ACTIVATION_EVENT_KIND),
+  stream: Orn,
+  /** Reference to the canonical descriptor artifact. */
+  activation: Reference,
+});
+export const StandingOrderActivationEventSchema: typeof StandingOrderActivationEventSchemaValue =
+  StandingOrderActivationEventSchemaValue;
+export type StandingOrderActivationEvent = Static<typeof StandingOrderActivationEventSchema>;
+
+/** Detached signature over the canonical activation descriptor bytes. */
+const SignedStandingOrderActivationSchemaValue = closed({
+  body: StandingOrderActivationSchema,
+  signer: Orn,
+  signature: Type.String({ pattern: "^[0-9a-f]{128}$" }),
+});
+export const SignedStandingOrderActivationSchema: typeof SignedStandingOrderActivationSchemaValue =
+  SignedStandingOrderActivationSchemaValue;
+export type SignedStandingOrderActivation = Static<typeof SignedStandingOrderActivationSchema>;
+
+export const standingOrderActivationV1: ProfileEntry = {
+  literal: STANDING_ORDER_ACTIVATION_PROFILE,
+  rootShape: "event",
+  shapes: {
+    activation: StandingOrderActivationSchema,
+    signed: SignedStandingOrderActivationSchema,
+    event: StandingOrderActivationEventSchema,
+  },
+};

package/src/primitives.ts

@@ -33,6 +33,14 @@ export const Reference = closed({
   sha256: Type.String({ pattern: SHA256_PATTERN }),
 });
 
+/** A person named on a run. Missing on the wire is null; readers print
+ * "Not recorded". Never inferred. */
+export const PersonReference = closed({
+  principal: Orn,
+  displayName: NonEmptyString,
+  source: NonEmptyString,
+});
+
 /** 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>". */

package/src/run/decision.v1.ts

@@ -0,0 +1,27 @@
+// dsg.run.decision/1
+// Owner: dsg-kernel (the decisions route verifies the signature against
+// the decider's recorded public key). A decision is a signature, not a
+// session. The requester may not decide their own run.
+import { type Static, Type } from "@sinclair/typebox";
+import { closed, Hex64, NonEmptyString, Orn, UtcSecond, type ProfileEntry } from "../primitives.js";
+
+export const DECISION_PROFILE = "dsg.run.decision/1" as const;
+
+const RunDecisionSchemaValue = closed({
+  profile: Type.Literal(DECISION_PROFILE),
+  runId: NonEmptyString,
+  requestDigest: Hex64,
+  decision: Type.Union([Type.Literal("approved"), Type.Literal("refused")]),
+  cause: Type.Union([NonEmptyString, Type.Null()]),
+  decidedAt: UtcSecond,
+  decider: Orn,
+  signature: NonEmptyString,
+});
+export const RunDecisionSchema: typeof RunDecisionSchemaValue = RunDecisionSchemaValue;
+export type RunDecision = Static<typeof RunDecisionSchema>;
+
+export const decisionV1: ProfileEntry = {
+  literal: DECISION_PROFILE,
+  rootShape: "decision",
+  shapes: { decision: RunDecisionSchema },
+};

package/src/run/request.v1.ts

@@ -0,0 +1,50 @@
+// dsg.run.request/1
+// Owner: dsg-run (POST /requests). The CLI builds this document from an
+// experiment; the plane fills the requester from the door's assertion and
+// never from a field on this shape.
+import { type Static, Type } from "@sinclair/typebox";
+import {
+  closed,
+  Hex64,
+  NonEmptyString,
+  Reference,
+  SafeInt,
+  type ProfileEntry,
+} from "../primitives.js";
+
+export const REQUEST_PROFILE = "dsg.run.request/1" as const;
+
+const ExperimentRefSchemaValue = closed({
+  digest: Hex64,
+  title: NonEmptyString,
+  workloadClass: NonEmptyString,
+});
+export const ExperimentRefSchema: typeof ExperimentRefSchemaValue = ExperimentRefSchemaValue;
+export type ExperimentRef = Static<typeof ExperimentRefSchema>;
+
+const RequestCeilingsSchemaValue = closed({
+  maxRunSeconds: SafeInt,
+  maxGpuSeconds: SafeInt,
+  maxParallelism: SafeInt,
+  costBoundMicroUsd: SafeInt,
+});
+export const RequestCeilingsSchema: typeof RequestCeilingsSchemaValue = RequestCeilingsSchemaValue;
+export type RequestCeilings = Static<typeof RequestCeilingsSchema>;
+
+const RunRequestSchemaValue = closed({
+  profile: Type.Literal(REQUEST_PROFILE),
+  experiment: ExperimentRefSchema,
+  workload: Reference,
+  inputs: Type.Array(Reference, { minItems: 1 }),
+  ceilings: RequestCeilingsSchema,
+  purpose: NonEmptyString,
+  window: NonEmptyString,
+});
+export const RunRequestSchema: typeof RunRequestSchemaValue = RunRequestSchemaValue;
+export type RunRequest = Static<typeof RunRequestSchema>;
+
+export const requestV1: ProfileEntry = {
+  literal: REQUEST_PROFILE,
+  rootShape: "request",
+  shapes: { request: RunRequestSchema },
+};

package/src/run/run-summary.v1.ts

@@ -0,0 +1,42 @@
+// dsg.run.run-summary/1
+// Owner: dsg-run (the plane writes it; the console and kernel status read
+// it). A gate with no decision is waiting, never approved or refused.
+import { type Static, Type } from "@sinclair/typebox";
+import {
+  closed,
+  Hex64,
+  NonEmptyString,
+  PersonReference,
+  UtcSecond,
+  type ProfileEntry,
+} from "../primitives.js";
+
+export const RUN_SUMMARY_PROFILE = "dsg.run.run-summary/1" as const;
+
+const RunSummaryDecisionSchemaValue = closed({
+  outcome: Type.Union([Type.Literal("approved"), Type.Literal("refused")]),
+  decider: PersonReference,
+  decidedAt: UtcSecond,
+  cause: Type.Union([NonEmptyString, Type.Null()]),
+  byStandingOrder: Type.Boolean(),
+});
+export const RunSummaryDecisionSchema: typeof RunSummaryDecisionSchemaValue =
+  RunSummaryDecisionSchemaValue;
+export type RunSummaryDecision = Static<typeof RunSummaryDecisionSchema>;
+
+const RunSummarySchemaValue = closed({
+  profile: Type.Literal(RUN_SUMMARY_PROFILE),
+  runId: NonEmptyString,
+  experimentDigest: Hex64,
+  requester: Type.Union([PersonReference, Type.Null()]),
+  decision: Type.Union([RunSummaryDecisionSchema, Type.Null()]),
+  waitingOn: Type.Union([NonEmptyString, Type.Null()]),
+});
+export const RunSummarySchema: typeof RunSummarySchemaValue = RunSummarySchemaValue;
+export type RunSummary = Static<typeof RunSummarySchema>;
+
+export const runSummaryV1: ProfileEntry = {
+  literal: RUN_SUMMARY_PROFILE,
+  rootShape: "summary",
+  shapes: { summary: RunSummarySchema },
+};