@opensoftware/contracts 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@opensoftware/contracts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "The shared formats of the open software factory: JSON Schemas, TypeScript types and the osf-contracts CLI.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sesigl/open-software-factory.git",
+    "directory": "contracts"
+  },
+  "type": "module",
+  "bin": {
+    "osf-contracts": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.schema.json": "./*.schema.json",
+    "./events/asyncapi.yaml": "./events/asyncapi.yaml",
+    "./openapi/*": "./openapi/*",
+    "./typespec/*": "./typespec/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "typespec",
+    "*/*.schema.json",
+    "events/*/*.schema.json",
+    "events/asyncapi.yaml",
+    "openapi"
+  ],
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "yaml": "2.9.1"
+  },
+  "devDependencies": {
+    "@asyncapi/parser": "3.6.6",
+    "@typespec/compiler": "1.17.0",
+    "@typespec/json-schema": "1.17.0",
+    "openapi-typescript": "7.13.0",
+    "@opensoftware/testkit": "0.0.0"
+  },
+  "scripts": {
+    "build": "node scripts/build.ts",
+    "lint": "biome check . && node scripts/build.ts --check",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:system": "vitest run",
+    "docs": "node ../tools/bin/osf.ts docs ."
+  }
 }

package/run-record/run-record.schema.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/run-record/run-record.schema.json",
+  "title": "RunRecord",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "resource": {
+      "type": "object",
+      "properties": {
+        "service.name": {
+          "type": "string"
+        },
+        "osf.run.id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "osf.work_item.id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "osf.factory.version": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$",
+          "description": "Commit of the factory definition the run used."
+        },
+        "osf.stage": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources."
+        },
+        "osf.requester.kind": {
+          "type": "string",
+          "enum": [
+            "person",
+            "trigger"
+          ],
+          "description": "Who caused something: a person, or an automated trigger such as a cron rule or an alert."
+        },
+        "osf.requester.id": {
+          "type": "string"
+        },
+        "osf.source": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "Where the run was started from, for example \"slack\", \"github\", \"cli\"."
+        },
+        "osf.origin.url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "osf.harness.name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{0,62}$",
+          "description": "Harness adapter, for example \"claude-code\"."
+        },
+        "osf.harness.version": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "service.name",
+        "osf.run.id",
+        "osf.work_item.id",
+        "osf.factory.version",
+        "osf.requester.kind",
+        "osf.requester.id",
+        "osf.source",
+        "osf.harness.name"
+      ],
+      "description": "Set at launch through OTEL_RESOURCE_ATTRIBUTES, so it is on every span of the run."
+    },
+    "span": {
+      "type": "object",
+      "properties": {
+        "gen_ai.operation.name": {
+          "type": "string",
+          "const": "invoke_agent"
+        },
+        "gen_ai.provider.name": {
+          "type": "string"
+        },
+        "gen_ai.agent.name": {
+          "type": "string"
+        },
+        "gen_ai.conversation.id": {
+          "type": "string",
+          "description": "The harness session ID."
+        },
+        "gen_ai.request.model": {
+          "type": "string"
+        },
+        "gen_ai.response.model": {
+          "type": "string"
+        },
+        "gen_ai.usage.input_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "gen_ai.usage.output_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "gen_ai.usage.cache_read.input_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "gen_ai.usage.cache_write.input_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "osf.outcome": {
+          "type": "string",
+          "enum": [
+            "succeeded",
+            "failed",
+            "cancelled"
+          ],
+          "description": "How a run ended."
+        },
+        "osf.cost.usd": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Cost of all model calls of the run, from the inference gateway."
+        },
+        "osf.transcript.uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Full transcript, stored when the run ends."
+        },
+        "osf.artifact.uris": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          },
+          "description": "Artifacts of the run: reports, screenshots, videos."
+        },
+        "osf.pull_request.urls": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "osf.issue.urls": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "osf.evidence_bundle.uri": {
+          "type": "string",
+          "format": "uri"
+        },
+        "osf.agent_trace.uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "Agent Trace record with line attribution of the run's changes."
+        }
+      },
+      "required": [
+        "gen_ai.operation.name",
+        "osf.outcome"
+      ],
+      "description": "Attributes of the root span of the run. GenAI names where a convention exists."
+    }
+  },
+  "required": [
+    "resource",
+    "span"
+  ],
+  "description": "The attributes of one run: the OTel resource of every span of the run, and the attributes of its root\n`invoke_agent` span. The run record travels as OTLP; this schema fixes the attribute names and types.\nRealizes SCN-FACTORY-DATA-001 (record shape) and SCN-FACTORY-RUNTIME-008 (attribution)."
+}

package/score/score.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/sesigl/open-software-factory/main/contracts/score/score.schema.json",
+  "title": "Score",
+  "$comment": "Generated by `pnpm build` in contracts/ from typespec/. Do not edit.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Scorer name, for example \"redundant-tests\"."
+    },
+    "value": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "string"
+        }
+      ],
+      "description": "A number for NUMERIC, 0 or 1 for BOOLEAN, a string for CATEGORICAL."
+    },
+    "dataType": {
+      "type": "string",
+      "enum": [
+        "NUMERIC",
+        "BOOLEAN",
+        "CATEGORICAL"
+      ]
+    },
+    "traceId": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{32}$",
+      "description": "Trace of the run (the OTel trace ID)."
+    },
+    "observationId": {
+      "type": "string",
+      "description": "Span the score is about, when it is not the whole run."
+    },
+    "sessionId": {
+      "type": "string"
+    },
+    "comment": {
+      "type": "string",
+      "description": "The reason."
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "source": {
+      "type": "string",
+      "enum": [
+        "API",
+        "ANNOTATION"
+      ],
+      "description": "API for scorers, ANNOTATION for scores a person reviews."
+    },
+    "configId": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "osf.run.id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque."
+        },
+        "osf.scorer.version": {
+          "type": "string"
+        },
+        "osf.judge.model": {
+          "type": "string",
+          "description": "Judge model of an LLM scorer."
+        },
+        "osf.judge.cost.usd": {
+          "type": "number",
+          "minimum": 0,
+          "description": "Cost of the judge call."
+        }
+      },
+      "required": [
+        "osf.run.id"
+      ],
+      "unevaluatedProperties": {}
+    }
+  },
+  "required": [
+    "id",
+    "name",
+    "value",
+    "dataType",
+    "traceId",
+    "timestamp",
+    "metadata"
+  ],
+  "description": "The result of one scorer on one run. The fields are a subset of Langfuse's create-score request\n(POST /api/public/scores), so a score can be sent to Langfuse as is. Factory fields live in `metadata`."
+}

package/typespec/common.tsp

@@ -0,0 +1,62 @@
+import "@typespec/json-schema";
+
+using TypeSpec.JsonSchema;
+
+@jsonSchema
+namespace Osf.Contracts;
+
+/** A lowercase name: letters, digits and hyphens, starting with a letter. Agents, stages, adapters, sources. */
+@pattern("^[a-z][a-z0-9-]{0,62}$")
+scalar Name extends string;
+
+/** An identifier chosen by the producer. ULIDs are recommended; consumers treat it as opaque. */
+@minLength(1)
+@maxLength(128)
+scalar Identifier extends string;
+
+/** A Git commit hash, abbreviated (7+) or full. The factory version is the commit of the factory definition. */
+@pattern("^[0-9a-f]{7,40}$")
+scalar CommitHash extends string;
+
+/** A scenario ID as checked by SPEC, for example SCN-PROOF-004. */
+@pattern("^SCN-[A-Z][A-Z0-9]*(-[A-Z][A-Z0-9]*)*-[0-9]{3}$")
+scalar ScenarioId extends string;
+
+/** The version of a format inside its documents. Only 1 exists; a new major version of a format adds the next. */
+@extension("const", Json<1>)
+@minValue(1)
+scalar FormatVersion extends int32;
+
+/** An OpenTelemetry trace ID: 32 lowercase hex characters. */
+@pattern("^[0-9a-f]{32}$")
+scalar TraceId extends string;
+
+/** Who caused something: a person, or an automated trigger such as a cron rule or an alert. */
+enum ActorKind {
+  person,
+  trigger,
+}
+
+/** A person or trigger. RUNTIME-008: every run is attributed to one. */
+model Actor {
+  kind: ActorKind;
+
+  /** Stable ID in the source system, prefixed with the source, for example "slack:U024BE7LH". */
+  @minLength(1)
+  id: string;
+
+  /** Shown to people, for example "Varun". */
+  displayName?: string;
+}
+
+model Link {
+  url: url;
+  title?: string;
+}
+
+/** How a run ended. */
+enum RunOutcome {
+  succeeded,
+  failed,
+  cancelled,
+}

package/typespec/events.tsp

@@ -0,0 +1,134 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+import "./work-item.tsp";
+import "./score.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/**
+ * A CloudEvents 1.0 event in structured JSON mode. The same JSON is the NATS message body and the webhook body.
+ * `type` is the versioned event name; a breaking change gets a new name (`@v2`) next to the old one.
+ */
+model CloudEvent<Type extends string, Data> {
+  specversion: "1.0";
+
+  /** Unique per source. A consumer that sees the same source and id twice handles the event once. */
+  id: Identifier;
+
+  /** The producing module, for example "/osf/intake". */
+  @minLength(1)
+  source: string;
+
+  type: Type;
+  time: utcDateTime;
+
+  /** The ID of the thing the event is about: work item, gate, run, score or pull request. */
+  subject?: string;
+
+  datacontenttype?: "application/json";
+  dataschema?: url;
+
+  /** W3C trace context (CloudEvents distributed tracing extension). */
+  traceparent?: string;
+
+  data: Data;
+}
+
+/** intake: a work item was accepted. */
+model WorkReceived is CloudEvent<"work.received@v1", WorkItem>;
+
+/** foreman: a run ended. */
+model RunCompleted is CloudEvent<"run.completed@v1", RunCompletedData>;
+
+/** gatekeeper: a decision is needed before a stage starts. */
+model GateRequested is CloudEvent<"gate.requested@v1", GateRequestedData>;
+
+/** gatekeeper: a gate was decided. */
+model GateDecided is CloudEvent<"gate.decided@v1", GateDecidedData>;
+
+/** scorekit: a scorer scored a run. */
+model ScoreRecorded is CloudEvent<"score.recorded@v1", Score>;
+
+/** forge adapters: the factory opened a pull request. */
+model PrOpened is CloudEvent<"pr.opened@v1", PrOpenedData>;
+
+model RunCompletedData {
+  runId: Identifier;
+  workItemId: Identifier;
+  stage?: Name;
+  factoryVersion: CommitHash;
+  outcome: RunOutcome;
+  startedAt: utcDateTime;
+  endedAt: utcDateTime;
+  requester: Actor;
+  source: Name;
+
+  @minValue(0)
+  costUsd?: float64;
+
+  traceId?: TraceId;
+  pullRequests?: url[];
+  evidenceBundle?: url;
+}
+
+model GateRequestedData {
+  gateId: Identifier;
+  workItemId: Identifier;
+  runId?: Identifier;
+
+  /** The stage that waits. */
+  stage: Name;
+
+  /** Path to the policy in the factory definition. */
+  @minLength(1)
+  policy: string;
+
+  /** Approver groups picked by the policy. */
+  @minItems(1)
+  approvers: Name[];
+
+  /** What the approver is asked to decide, shown in the channel. */
+  @minLength(1)
+  summary: string;
+
+  links?: Link[];
+  expiresAt?: utcDateTime;
+}
+
+enum GateDecision {
+  approved,
+  rejected,
+  expired,
+}
+
+model GateDecidedData {
+  gateId: Identifier;
+  workItemId: Identifier;
+  decision: GateDecision;
+
+  /** The person who decided. Absent only when the gate expired. */
+  decidedBy?: Actor;
+
+  decidedAt: utcDateTime;
+  reason?: string;
+}
+
+model PrOpenedData {
+  url: url;
+  repository: url;
+
+  @minValue(1)
+  number: safeint;
+
+  @minLength(1)
+  title: string;
+
+  headBranch: string;
+  baseBranch: string;
+  headCommit: CommitHash;
+  author: Actor;
+  workItemId?: Identifier;
+  runId?: Identifier;
+}

package/typespec/evidence-bundle.tsp

@@ -0,0 +1,99 @@
+import "@typespec/json-schema";
+import "./common.tsp";
+
+using TypeSpec.JsonSchema;
+
+namespace Osf.Contracts;
+
+/** A path inside the bundle: relative, forward slashes, no "..". */
+@pattern("^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$")
+scalar BundlePath extends string;
+
+@pattern("^[0-9a-f]{64}$")
+scalar Sha256 extends string;
+
+/**
+ * `evidence.json` at the root of an evidence bundle: what was verified, against which scenario IDs, with which
+ * artifacts and result (P10).
+ */
+model EvidenceManifest {
+  /** Version of this format. */
+  manifestVersion: FormatVersion;
+
+  id: Identifier;
+  createdAt: utcDateTime;
+
+  /** The change that was verified. */
+  subject: EvidenceSubject;
+
+  runId?: Identifier;
+  workItemId?: Identifier;
+
+  /** The tool that wrote the bundle, for example proof 1.2.0. */
+  producer: Producer;
+
+  /** Passed only when every scenario passed. */
+  result: VerificationResult;
+
+  scenarios: ScenarioEvidence[];
+  artifacts: Artifact[];
+}
+
+model EvidenceSubject {
+  repository: url;
+  commit: CommitHash;
+  pullRequest?: url;
+}
+
+model Producer {
+  @minLength(1)
+  name: string;
+
+  @minLength(1)
+  version: string;
+}
+
+enum VerificationResult {
+  passed,
+  failed,
+}
+
+enum ScenarioResult {
+  passed,
+  failed,
+  skipped,
+}
+
+model ScenarioEvidence {
+  id: ScenarioId;
+  result: ScenarioResult;
+
+  /** Paths of the artifacts in this bundle that prove the scenario. */
+  artifacts: BundlePath[];
+
+  summary?: string;
+}
+
+enum ArtifactKind {
+  screenshot,
+  video,
+  `playwright-trace`,
+  junit,
+  log,
+  report,
+  other,
+}
+
+model Artifact {
+  path: BundlePath;
+  kind: ArtifactKind;
+
+  /** IANA media type, for example "image/png". */
+  @minLength(1)
+  mediaType: string;
+
+  sha256: Sha256;
+
+  @minValue(0)
+  bytes?: safeint;
+}