@sealant/api-contracts-next 0.0.0-next.0 → 0.39.0-next.682

package/dist/core-api/record-events.js

@@ -0,0 +1,193 @@
+/**
+ * Record-event taxonomy — the TYPED payload schemas behind `TimelineEntry.kind`/`ref` and
+ * `RunEvent.payloadCase`/`payload`.
+ *
+ * The execution record's event kinds come from the sealantd protocol (`@sealant/runtime-protocol`
+ * `EventEnvelope.payload` oneof); ingest stores each payload as jsonb with the oneof case name as
+ * the `kind`. These schemas describe that STORED/SERVED shape exactly:
+ *
+ *   - uint64/int64 protobuf fields are DECIMAL STRINGS (bigints are stringified at ingest so values
+ *     past 2^53 survive jsonb);
+ *   - protobuf enum fields are NUMBERS (`RuntimeState`, `ExitReason`, `StreamKind`, `FileChangeKind`,
+ *     `FileType`, `NetworkScheme`, `EventPriority` — same convention as the envelope's
+ *     `captureMethod`/`confidence`);
+ *   - proto3 `optional` fields are absent when unset; implicit scalars are always present;
+ *   - decode strips ingest artifacts (e.g. the protobuf `$typeName` marker).
+ *
+ * `decodeRecordEventPayload` folds a `(kind, ref)` pair into the discriminated union, degrading to
+ * the `unknown` case (with the raw kind + payload preserved) for kinds this contract version does
+ * not model or payloads that fail their schema — forward compatibility is a case, not an error.
+ *
+ * The kind list deliberately mirrors `payloadCaseValues` in `@sealant/telemetry` (guarded by a test
+ * there); this contract does not depend on the telemetry package.
+ */
+import { Schema } from "effect";
+/** Every event kind the platform records today, plus `unknown` for an unmodeled/absent oneof. */
+export const recordEventKindValues = [
+    "runtimeStateChanged",
+    "runtimeHeartbeat",
+    "processStarted",
+    "processExited",
+    "ioChunk",
+    "telemetryDropped",
+    "fileChange",
+    "fileWatchOverflow",
+    "fileSnapshotCompleted",
+    "fileDiffAvailable",
+    "networkRequest",
+    "networkSourceObserved",
+    "unknown",
+];
+export const recordEventKindSchema = Schema.Literals(recordEventKindValues);
+/** Decimal-string int64/uint64 (bigints are stringified at ingest). */
+const DecimalString = Schema.String;
+// ---------------------------------------------------------------------------------------------
+// Per-kind payload schemas (the jsonb `ref` / `payload` shape on the wire)
+// ---------------------------------------------------------------------------------------------
+/** `sealant.v1.RuntimeStateChanged` — `state` is a numeric `RuntimeState`. */
+export const runtimeStateChangedEventSchema = Schema.Struct({
+    state: Schema.Number,
+    reason: Schema.optional(Schema.String),
+});
+/** `sealant.v1.RuntimeHeartbeat` — `state` is a numeric `RuntimeState`. */
+export const runtimeHeartbeatEventSchema = Schema.Struct({
+    state: Schema.Number,
+});
+/** `sealant.v1.ProcessStarted` — a supervised process began executing. */
+export const processStartedEventSchema = Schema.Struct({
+    pid: Schema.Number,
+    pgid: Schema.Number,
+    pidfd: Schema.Boolean,
+    executable: Schema.String,
+    args: Schema.Array(Schema.String),
+    cwd: Schema.String,
+    /** Wall clock at start, microseconds (decimal-string int64). */
+    startedAt: DecimalString,
+});
+/** `sealant.v1.ProcessExited` — `reason` is a numeric `ExitReason`. */
+export const processExitedEventSchema = Schema.Struct({
+    exitCode: Schema.optional(Schema.Number),
+    signal: Schema.optional(Schema.Number),
+    reason: Schema.Number,
+    /** Wall-clock duration, microseconds (decimal-string uint64). */
+    durationMicros: DecimalString,
+});
+/**
+ * `sealant.v1.IoChunk`, as ingest stores it: raw bytes are offloaded to the artifact store and
+ * replaced by a content hash; byte-exact text is served by the scrollback endpoint, not the record.
+ * `stream` is a numeric `StreamKind` (stdout = 2, stderr = 3).
+ */
+export const ioChunkEventSchema = Schema.Struct({
+    stream: Schema.Number,
+    byteCount: DecimalString,
+    streamOffset: DecimalString,
+    contentAlgo: Schema.optional(Schema.String),
+    contentHash: Schema.optional(Schema.String),
+    transform: Schema.optional(Schema.Struct({
+        redacted: Schema.Boolean,
+        truncated: Schema.Boolean,
+        coalesced: Schema.Boolean,
+        originalByteCount: Schema.optional(DecimalString),
+    })),
+});
+/** `sealant.v1.TelemetryDropped` — `priority` is a numeric `EventPriority`. */
+export const telemetryDroppedEventSchema = Schema.Struct({
+    reason: Schema.String,
+    count: DecimalString,
+    priority: Schema.Number,
+});
+/** `sealant.v1.FileEntry` — `fileType` is a numeric `FileType`. */
+export const fileEntrySchema = Schema.Struct({
+    path: Schema.String,
+    fileType: Schema.Number,
+    size: DecimalString,
+    mtimeMicros: DecimalString,
+    mode: Schema.Number,
+    hash: Schema.optional(Schema.String),
+    symlinkTarget: Schema.optional(Schema.String),
+});
+/** `sealant.v1.FileChange` — `kind` is a numeric `FileChangeKind`. */
+export const fileChangeEventSchema = Schema.Struct({
+    kind: Schema.Number,
+    path: Schema.String,
+    renameFrom: Schema.optional(Schema.String),
+    entry: Schema.optional(fileEntrySchema),
+    certain: Schema.Boolean,
+});
+/** `sealant.v1.FileWatchOverflow` — changes under `root` may have been missed. */
+export const fileWatchOverflowEventSchema = Schema.Struct({
+    root: Schema.String,
+});
+/** `sealant.v1.FileSnapshotCompleted` */
+export const fileSnapshotCompletedEventSchema = Schema.Struct({
+    root: Schema.String,
+    fileCount: DecimalString,
+});
+/** `sealant.v1.FileDiffAvailable` — per-kind counts as decimal-string uint64. */
+export const fileDiffAvailableEventSchema = Schema.Struct({
+    added: DecimalString,
+    modified: DecimalString,
+    deleted: DecimalString,
+    renamed: DecimalString,
+});
+/** `sealant.v1.NetworkRequest` — `scheme` is a numeric `NetworkScheme`. */
+export const networkRequestEventSchema = Schema.Struct({
+    scheme: Schema.Number,
+    method: Schema.optional(Schema.String),
+    host: Schema.String,
+    port: Schema.Number,
+    path: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.Number),
+    bytesSent: DecimalString,
+    bytesReceived: DecimalString,
+    durationMicros: DecimalString,
+});
+/** `sealant.v1.NetworkSourceObserved` — a network source the run touched (the "sources" trail). */
+export const networkSourceObservedEventSchema = Schema.Struct({
+    host: Schema.String,
+    resolvedIps: Schema.Array(Schema.String),
+    port: Schema.Number,
+    scheme: Schema.optional(Schema.Number),
+    method: Schema.optional(Schema.String),
+    path: Schema.optional(Schema.String),
+    status: Schema.optional(Schema.Number),
+});
+/**
+ * Wraps one kind's schema into a total decoder: a payload that fails its schema degrades to the
+ * `unknown` case rather than throwing. The generic RETURN type (not a constrained construction)
+ * keeps kind/data correlated without casts.
+ */
+const eventCase = (kind, schema) => {
+    const decode = Schema.decodeUnknownSync(schema);
+    return (ref) => {
+        try {
+            return { kind, data: decode(ref) };
+        }
+        catch {
+            return { kind: "unknown", rawKind: kind, data: ref };
+        }
+    };
+};
+const decoders = {
+    runtimeStateChanged: eventCase("runtimeStateChanged", runtimeStateChangedEventSchema),
+    runtimeHeartbeat: eventCase("runtimeHeartbeat", runtimeHeartbeatEventSchema),
+    processStarted: eventCase("processStarted", processStartedEventSchema),
+    processExited: eventCase("processExited", processExitedEventSchema),
+    ioChunk: eventCase("ioChunk", ioChunkEventSchema),
+    telemetryDropped: eventCase("telemetryDropped", telemetryDroppedEventSchema),
+    fileChange: eventCase("fileChange", fileChangeEventSchema),
+    fileWatchOverflow: eventCase("fileWatchOverflow", fileWatchOverflowEventSchema),
+    fileSnapshotCompleted: eventCase("fileSnapshotCompleted", fileSnapshotCompletedEventSchema),
+    fileDiffAvailable: eventCase("fileDiffAvailable", fileDiffAvailableEventSchema),
+    networkRequest: eventCase("networkRequest", networkRequestEventSchema),
+    networkSourceObserved: eventCase("networkSourceObserved", networkSourceObservedEventSchema),
+};
+/**
+ * Folds a wire `(kind, ref)` pair — `TimelineEntry.kind`/`ref` or `RunEvent.payloadCase`/`payload` —
+ * into the discriminated {@link RecordEventPayload}. NEVER throws: unmodeled kinds and non-conforming
+ * payloads come back as the `unknown` case with the raw data preserved.
+ */
+export const decodeRecordEventPayload = (kind, ref) => {
+    const decoder = decoders[kind];
+    return decoder === undefined ? { kind: "unknown", rawKind: kind, data: ref } : decoder(ref);
+};

package/dist/core-api/registries.d.ts

@@ -0,0 +1,106 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const registryIdParamsSchema: Schema.Struct<{
+    readonly registryId: Schema.String;
+}>;
+export type RegistryIdParams = typeof registryIdParamsSchema.Type;
+export declare const registrySummarySchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly baseUrl: Schema.String;
+    readonly pushRegistry: Schema.String;
+    readonly hasBasicAuth: Schema.Boolean;
+}>;
+export type RegistrySummary = typeof registrySummarySchema.Type;
+export declare const registryPingSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly reachable: Schema.Literal<true>;
+}>;
+export type RegistryPing = typeof registryPingSchema.Type;
+export declare const registryExtensionSchema: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly url: Schema.optional<Schema.String>;
+    readonly description: Schema.optional<Schema.String>;
+    readonly endpoints: Schema.$Array<Schema.String>;
+}>;
+export declare const registryExtensionsResponseSchema: Schema.Struct<{
+    readonly extensions: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly url: Schema.optional<Schema.String>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly endpoints: Schema.$Array<Schema.String>;
+    }>>;
+}>;
+export type RegistryExtensionsResponse = typeof registryExtensionsResponseSchema.Type;
+export declare const registryTagsQuerySchema: Schema.Struct<{
+    readonly repository: Schema.String;
+}>;
+export type RegistryTagsQuery = typeof registryTagsQuerySchema.Type;
+export declare const registryTagsResponseSchema: Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly tags: Schema.$Array<Schema.String>;
+}>;
+export type RegistryTagsResponse = typeof registryTagsResponseSchema.Type;
+export declare const registryManifestQuerySchema: Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly reference: Schema.String;
+}>;
+export type RegistryManifestQuery = typeof registryManifestQuerySchema.Type;
+export declare const registryManifestResponseSchema: Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly reference: Schema.String;
+    readonly digest: Schema.optional<Schema.String>;
+    readonly contentType: Schema.Union<readonly [Schema.String, Schema.Null]>;
+    readonly manifest: Schema.Unknown;
+}>;
+export type RegistryManifestResponse = typeof registryManifestResponseSchema.Type;
+declare const RegistriesNotFoundError_base: Schema.Class<RegistriesNotFoundError, Schema.TaggedStruct<"RegistriesNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class RegistriesNotFoundError extends RegistriesNotFoundError_base {
+}
+declare const RegistriesBadGatewayError_base: Schema.Class<RegistriesBadGatewayError, Schema.TaggedStruct<"RegistriesBadGatewayError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class RegistriesBadGatewayError extends RegistriesBadGatewayError_base {
+}
+export declare const RegistriesGroup: HttpApiGroup.HttpApiGroup<"registries", HttpApiEndpoint.HttpApiEndpoint<"getRegistry", "GET", "/:registryId", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly registryId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly baseUrl: Schema.String;
+    readonly pushRegistry: Schema.String;
+    readonly hasBasicAuth: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof RegistriesNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getRegistryManifest", "GET", "/:registryId/manifest", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly registryId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly reference: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly reference: Schema.String;
+    readonly digest: Schema.optional<Schema.String>;
+    readonly contentType: Schema.Union<readonly [Schema.String, Schema.Null]>;
+    readonly manifest: Schema.Unknown;
+}>>, HttpApiEndpoint.Json<typeof RegistriesNotFoundError | typeof RegistriesBadGatewayError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listRegistryExtensions", "GET", "/:registryId/extensions", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly registryId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly extensions: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly url: Schema.optional<Schema.String>;
+        readonly description: Schema.optional<Schema.String>;
+        readonly endpoints: Schema.$Array<Schema.String>;
+    }>>;
+}>>, HttpApiEndpoint.Json<typeof RegistriesNotFoundError | typeof RegistriesBadGatewayError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listRegistryTags", "GET", "/:registryId/tags", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly registryId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly repository: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly repository: Schema.String;
+    readonly tags: Schema.$Array<Schema.String>;
+}>>, HttpApiEndpoint.Json<typeof RegistriesNotFoundError | typeof RegistriesBadGatewayError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"pingRegistry", "GET", "/:registryId/ping", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly registryId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly reachable: Schema.Literal<true>;
+}>>, HttpApiEndpoint.Json<typeof RegistriesNotFoundError | typeof RegistriesBadGatewayError>, never, never>, false>;
+export {};

package/dist/core-api/registries.js

@@ -0,0 +1,85 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/unstable/httpapi";
+import { isOciReference, isOciRepository, OCI_REFERENCE_MESSAGE, OCI_REPOSITORY_MESSAGE, } from "./oci-names.js";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+/** Refused, never repaired: these become registry URL path segments (CORE-08). */
+const OciRepository = NonEmptyString.check(Schema.makeFilter((value) => isOciRepository(value) ? undefined : `repository ${OCI_REPOSITORY_MESSAGE}`));
+const OciReference = NonEmptyString.check(Schema.makeFilter((value) => isOciReference(value) ? undefined : `reference ${OCI_REFERENCE_MESSAGE}`));
+export const registryIdParamsSchema = Schema.Struct({
+    registryId: NonEmptyString,
+});
+export const registrySummarySchema = Schema.Struct({
+    name: NonEmptyString,
+    baseUrl: Schema.String,
+    pushRegistry: NonEmptyString,
+    hasBasicAuth: Schema.Boolean,
+});
+export const registryPingSchema = Schema.Struct({
+    name: NonEmptyString,
+    reachable: Schema.Literal(true),
+});
+export const registryExtensionSchema = Schema.Struct({
+    name: NonEmptyString,
+    url: Schema.optional(Schema.String),
+    description: Schema.optional(Schema.String),
+    endpoints: Schema.Array(Schema.String),
+});
+export const registryExtensionsResponseSchema = Schema.Struct({
+    extensions: Schema.Array(registryExtensionSchema),
+});
+export const registryTagsQuerySchema = Schema.Struct({
+    repository: OciRepository,
+});
+export const registryTagsResponseSchema = Schema.Struct({
+    repository: NonEmptyString,
+    tags: Schema.Array(Schema.String),
+});
+export const registryManifestQuerySchema = Schema.Struct({
+    repository: OciRepository,
+    reference: OciReference,
+});
+export const registryManifestResponseSchema = Schema.Struct({
+    repository: NonEmptyString,
+    reference: NonEmptyString,
+    digest: Schema.optional(Schema.String),
+    contentType: Schema.Union([Schema.String, Schema.Null]),
+    manifest: Schema.Unknown,
+});
+export class RegistriesNotFoundError extends Schema.TaggedErrorClass()("RegistriesNotFoundError", {
+    message: Schema.String,
+}, { httpApiStatus: 404 }) {
+}
+export class RegistriesBadGatewayError extends Schema.TaggedErrorClass()("RegistriesBadGatewayError", {
+    message: Schema.String,
+}, { httpApiStatus: 502 }) {
+}
+const registryIdParams = Schema.Struct({ registryId: NonEmptyString });
+export const RegistriesGroup = HttpApiGroup.make("registries")
+    .add(HttpApiEndpoint.get("getRegistry", "/:registryId", {
+    params: registryIdParams,
+    success: registrySummarySchema,
+    error: RegistriesNotFoundError,
+}))
+    .add(HttpApiEndpoint.get("pingRegistry", "/:registryId/ping", {
+    params: registryIdParams,
+    success: registryPingSchema,
+    error: [RegistriesNotFoundError, RegistriesBadGatewayError],
+}))
+    .add(HttpApiEndpoint.get("listRegistryExtensions", "/:registryId/extensions", {
+    params: registryIdParams,
+    success: registryExtensionsResponseSchema,
+    error: [RegistriesNotFoundError, RegistriesBadGatewayError],
+}))
+    .add(HttpApiEndpoint.get("listRegistryTags", "/:registryId/tags", {
+    params: registryIdParams,
+    query: registryTagsQuerySchema,
+    success: registryTagsResponseSchema,
+    error: [RegistriesNotFoundError, RegistriesBadGatewayError],
+}))
+    .add(HttpApiEndpoint.get("getRegistryManifest", "/:registryId/manifest", {
+    params: registryIdParams,
+    query: registryManifestQuerySchema,
+    success: registryManifestResponseSchema,
+    error: [RegistriesNotFoundError, RegistriesBadGatewayError],
+}))
+    .annotate(OpenApi.Description, "Registry metadata and OCI read operations.");