@codesoul-co/hypha-core / modules/artifact/events

• Package index: @codesoul-co/hypha-core
• Source: packages/core/src/modules/artifact/events.ts
• Exports: 16

Using this module

Use the Events module for creating, recording, or reading Event contracts. It exports 11 constants, 4 functions, 1 interface.

Import from the package entrypoint

import {
  artifactEventJsonSchemas,
  artifactEventPayloadJsonSchema,
  artifactEventPayloadRequirements,
  artifactEventPayloadSchema,
  artifactEventPublicationJsonSchema,
  artifactEventPublicationSchema,
  artifactFrameworkEventEnvelopeSchema,
  artifactFrameworkEventExample,
} from '@codesoul-co/hypha-core';

import type {
  ArtifactEventPayloadRequirement,
} from '@codesoul-co/hypha-core';

// The complete export list is documented below.

Usage patterns

• Use the 1 type/interface export as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 4 functions as direct operation entrypoints. Every overload, required/optional parameter, and return type is documented below.
• The 11 constant/enum exports provide stable values, schemas, definitions, or defaults. Reuse these exports instead of copying internal values into an application.

Runtime validation example

import { artifactEventPayloadSchema } from '@codesoul-co/hypha-core';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = artifactEventPayloadSchema.parse(input);

Parse untrusted configuration, network, or persisted input with the runtime schema before passing it to functions or classes that expect a validated contract.

Public exports

Symbol	Kind	Signature	Description
artifactEventJsonSchemas	constant	const artifactEventJsonSchemas: Record<string, JsonSchema>	Artifact Event JSON Schemas constant exported by the modules/artifact/events module.
artifactEventPayloadJsonSchema	constant	const artifactEventPayloadJsonSchema: JsonSchema	JSON Schema for Artifact Event Payload.
artifactEventPayloadRequirements	constant	const artifactEventPayloadRequirements: { readonly 'artifact.create.requested': { readonly required: readonly ["operationId", "workspaceId", "profileRef"]; }; readonly 'artifact.created': { readonly required: readonly ["operationId", "artifactId", "versionId", "logicalArtifactId", "contentHash", "status"]; readonly status: "draft"; }; readonly 'artifact.deduplicated': { readonly required: readonly ["operationId", ...	Artifact Event Payload Requirements constant exported by the modules/artifact/events module.
artifactEventPayloadSchema	constant	const artifactEventPayloadSchema: z.ZodEffects<z.ZodObject<{ operationId: z.ZodOptional<z.ZodString>; artifactId: z.ZodOptional<z.ZodString>; versionId: z.ZodOptional<z.ZodString>; logicalArtifactId: z.ZodOptional<z.ZodString>; profileRef: z.ZodOptional<z.ZodObject<{ id: z.ZodString; version: z.ZodOptional<z.ZodString>; revision: z.ZodOptional<z.ZodString>; }, "strip", z.ZodTypeAny, { id: string; version?: string ...	Runtime schema for Artifact Event Payload.
artifactEventPublicationJsonSchema	constant	const artifactEventPublicationJsonSchema: JsonSchema	JSON Schema for Artifact Event Publication.
artifactEventPublicationSchema	constant	const artifactEventPublicationSchema: z.ZodObject<{ id: z.ZodString; type: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artif...	Runtime schema for Artifact Event Publication.
artifactFrameworkEventEnvelopeSchema	constant	const artifactFrameworkEventEnvelopeSchema: z.ZodObject<{ id: z.ZodString; type: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", ...	Runtime schema for Artifact Framework Event Envelope.
artifactFrameworkEventExample	constant	const artifactFrameworkEventExample: ArtifactFrameworkEvent<"artifact.created">	Valid example value for Artifact Framework Event.
artifactFrameworkEventJsonSchema	constant	const artifactFrameworkEventJsonSchema: JsonSchema	JSON Schema for Artifact Framework Event.
artifactFrameworkEventTypes	constant	const artifactFrameworkEventTypes: readonly ["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.lineage.rec...	Artifact Framework Event Types constant exported by the modules/artifact/events module.
artifactFrameworkEventTypeSchema	constant	const artifactFrameworkEventTypeSchema: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.linea...	Runtime schema for Artifact Framework Event Type.
createArtifactFrameworkEvent	function	createArtifactFrameworkEvent<TType extends ArtifactFrameworkEventType>(input: ArtifactEventCreateInput<TType>): ArtifactFrameworkEvent<TType>	Create Artifact Framework Event function with 1 public call signature; parameters and return types are listed below.
validateArtifactEventPayloadForType	function	validateArtifactEventPayloadForType<TType extends ArtifactFrameworkEventType>(type: TType, input: unknown): ArtifactEventPayloadMap[TType]	Validate Artifact Event Payload For Type function with 1 public call signature; parameters and return types are listed below.
validateArtifactEventPublication	function	validateArtifactEventPublication(input: unknown): ArtifactEventPublication	Validate Artifact Event Publication function with 1 public call signature; parameters and return types are listed below.
validateArtifactFrameworkEvent	function	validateArtifactFrameworkEvent(input: unknown): ArtifactFrameworkEvent	Validate Artifact Framework Event function with 1 public call signature; parameters and return types are listed below.
ArtifactEventPayloadRequirement	interface	interface ArtifactEventPayloadRequirement	Artifact Event Payload Requirement interface with 5 public fields or methods.

artifactEventJsonSchemas

Artifact Event JSON Schemas constant exported by the modules/artifact/events module.

• Kind: constant
• Import: import { artifactEventJsonSchemas } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactEventJsonSchemas: Record<string, JsonSchema>;

artifactEventPayloadJsonSchema

JSON Schema for Artifact Event Payload.

• Kind: constant
• Import: import { artifactEventPayloadJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactEventPayloadJsonSchema: JsonSchema;

artifactEventPayloadRequirements

Artifact Event Payload Requirements constant exported by the modules/artifact/events module.

• Kind: constant
• Import: import { artifactEventPayloadRequirements } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactEventPayloadRequirements: { readonly 'artifact.create.requested': { readonly required: readonly ["operationId", "workspaceId", "profileRef"]; }; readonly 'artifact.created': { readonly required: readonly ["operationId", "artifactId", "versionId", "logicalArtifactId", "contentHash", "status"]; readonly status: "draft"; }; readonly 'artifact.deduplicated': { readonly required: readonly ["operationId", "artifactId", "versionId", "contentHash", "deduplicated"]; readonly deduplicated: true; }; readonly 'artifact.create.failed': { readonly required: readonly ["operationId", "error"]; }; readonly 'artifact.read.requested': { readonly required: readonly ["artifactId"]; }; readonly 'artifact.read.completed': { readonly required: readonly ["artifactId", "versionId", "contentHash", "sizeBytes"]; }; readonly 'artifact.version.created': { readonly required: readonly ["operationId", "artifactId", "versionId", "logicalArtifactId", "contentHash", "status"]; }; readonly 'artifact.finalized': { readonly required: readonly ["operationId", "artifactId", "versionId", "status"]; readonly status: "final"; }; readonly 'artifact.archived': { readonly required: readonly ["operationId", "artifactId", "versionId", "status"]; readonly status: "archived"; }; readonly 'artifact.invalidated': { readonly required: readonly ["operationId", "artifactId", "versionId", "status"]; readonly status: "invalidated"; }; readonly 'artifact.delete.requested': { readonly required: readonly ["operationId", "artifactId"]; }; readonly 'artifact.delete.blocked': { readonly required: readonly ["operationId", "artifactId", "error"]; readonly errorCodes: readonly ["ARTIFACT_DELETE_BLOCKED"]; }; readonly 'artifact.deleted': { readonly required: readonly ["operationId", "artifactId", "status"]; readonly status: "deleted"; }; readonly 'artifact.delete.failed': { readonly required: readonly ["operationId", "artifactId", "error"]; }; readonly 'artifact.lineage.recorded': { readonly required: readonly ["artifactId", "artifactRefs"]; readonly nonEmptyArtifactRefs: true; }; readonly 'artifact.retention.expired': { readonly required: readonly ["artifactId", "versionId"]; }; readonly 'artifact.gc.completed': { readonly required: readonly ["operationId", "candidateObjects", "deletedObjects", "missingObjects", "reclaimedBytes"]; }; readonly 'artifact.gc.failed': { readonly required: readonly ["operationId", "error"]; }; };

artifactEventPayloadSchema

Runtime schema for Artifact Event Payload.

• Kind: constant
• Import: import { artifactEventPayloadSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

// Exact type resolved from the package entrypoint; see source for the compiler expansion.
export declare const artifactEventPayloadSchema: (typeof import('@codesoul-co/hypha-core'))['artifactEventPayloadSchema'];

This compiler-expanded constant type is compacted. Its public name, top-level type, and source location remain here; use the module’s exported interfaces, types, or runtime schema for input/output fields.

artifactEventPublicationJsonSchema

JSON Schema for Artifact Event Publication.

• Kind: constant
• Import: import { artifactEventPublicationJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactEventPublicationJsonSchema: JsonSchema;

artifactEventPublicationSchema

Runtime schema for Artifact Event Publication.

• Kind: constant
• Import: import { artifactEventPublicationSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactEventPublicationSchema: z.ZodObject<{ id: z.ZodString; type: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.lineage.recorded", "artifact.retention.expired", "artifact.gc.completed", "artifact.gc.failed"]>; timestamp: z.ZodString; workspaceId: z.ZodOptional<z.ZodString>; sessionId: z.ZodOptional<z.ZodString>; runId: z.ZodOptional<z.ZodString>; agentId: z.ZodOptional<z.ZodString>; payload: z.ZodEffects<z.ZodUnknown, {} | null, unknown>; }, "strict", z.ZodTypeAny, { type: "artifact.create.requested" | "artifact.created" | "artifact.deduplicated" | "artifact.create.failed" | "artifact.read.requested" | "artifact.read.completed" | "artifact.version.created" | "artifact.finalized" | "artifact.archived" | "artifact.invalidated" | "artifact.delete.requested" | "artifact.delete.blocked" | "artifact.deleted" | "artifact.delete.failed" | "artifact.lineage.recorded" | "artifact.retention.expired" | "artifact.gc.completed" | "artifact.gc.failed"; id: string; timestamp: string; payload: {} | null; workspaceId?: string | undefined; sessionId?: string | undefined; runId?: string | undefined; agentId?: string | undefined; }, { type: "artifact.create.requested" | "artifact.created" | "artifact.deduplicated" | "artifact.create.failed" | "artifact.read.requested" | "artifact.read.completed" | "artifact.version.created" | "artifact.finalized" | "artifact.archived" | "artifact.invalidated" | "artifact.delete.requested" | "artifact.delete.blocked" | "artifact.deleted" | "artifact.delete.failed" | "artifact.lineage.recorded" | "artifact.retention.expired" | "artifact.gc.completed" | "artifact.gc.failed"; id: string; timestamp: string; workspaceId?: string | undefined; sessionId?: string | undefined; runId?: string | undefined; agentId?: string | undefined; payload?: unknown; }>;

artifactFrameworkEventEnvelopeSchema

Runtime schema for Artifact Framework Event Envelope.

• Kind: constant
• Import: import { artifactFrameworkEventEnvelopeSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactFrameworkEventEnvelopeSchema: z.ZodObject<{ id: z.ZodString; type: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.lineage.recorded", "artifact.retention.expired", "artifact.gc.completed", "artifact.gc.failed"]>; workspaceId: z.ZodOptional<z.ZodString>; sessionId: z.ZodOptional<z.ZodString>; runId: z.ZodString; stepId: z.ZodOptional<z.ZodString>; agentId: z.ZodOptional<z.ZodString>; fsmState: z.ZodOptional<z.ZodString>; timestamp: z.ZodString; payload: z.ZodEffects<z.ZodUnknown, {} | null, unknown>; metadata: z.ZodOptional<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodUnknown>, Record<string, unknown>, Record<string, unknown>>>; }, "strict", z.ZodTypeAny, { type: "artifact.create.requested" | "artifact.created" | "artifact.deduplicated" | "artifact.create.failed" | "artifact.read.requested" | "artifact.read.completed" | "artifact.version.created" | "artifact.finalized" | "artifact.archived" | "artifact.invalidated" | "artifact.delete.requested" | "artifact.delete.blocked" | "artifact.deleted" | "artifact.delete.failed" | "artifact.lineage.recorded" | "artifact.retention.expired" | "artifact.gc.completed" | "artifact.gc.failed"; id: string; runId: string; timestamp: string; payload: {} | null; workspaceId?: string | undefined; metadata?: Record<string, unknown> | undefined; sessionId?: string | undefined; stepId?: string | undefined; agentId?: string | undefined; fsmState?: string | undefined; }, { type: "artifact.create.requested" | "artifact.created" | "artifact.deduplicated" | "artifact.create.failed" | "artifact.read.requested" | "artifact.read.completed" | "artifact.version.created" | "artifact.finalized" | "artifact.archived" | "artifact.invalidated" | "artifact.delete.requested" | "artifact.delete.blocked" | "artifact.deleted" | "artifact.delete.failed" | "artifact.lineage.recorded" | "artifact.retention.expired" | "artifact.gc.completed" | "artifact.gc.failed"; id: string; runId: string; timestamp: string; workspaceId?: string | undefined; metadata?: Record<string, unknown> | undefined; sessionId?: string | undefined; stepId?: string | undefined; agentId?: string | undefined; fsmState?: string | undefined; payload?: unknown; }>;

artifactFrameworkEventExample

Valid example value for Artifact Framework Event.

• Kind: constant
• Import: import { artifactFrameworkEventExample } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactFrameworkEventExample: ArtifactFrameworkEvent<"artifact.created">;

artifactFrameworkEventJsonSchema

JSON Schema for Artifact Framework Event.

• Kind: constant
• Import: import { artifactFrameworkEventJsonSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactFrameworkEventJsonSchema: JsonSchema;

artifactFrameworkEventTypes

Artifact Framework Event Types constant exported by the modules/artifact/events module.

• Kind: constant
• Import: import { artifactFrameworkEventTypes } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactFrameworkEventTypes: readonly ["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.lineage.recorded", "artifact.retention.expired", "artifact.gc.completed", "artifact.gc.failed"];

artifactFrameworkEventTypeSchema

Runtime schema for Artifact Framework Event Type.

• Kind: constant
• Import: import { artifactFrameworkEventTypeSchema } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare const artifactFrameworkEventTypeSchema: z.ZodEnum<["artifact.create.requested", "artifact.created", "artifact.deduplicated", "artifact.create.failed", "artifact.read.requested", "artifact.read.completed", "artifact.version.created", "artifact.finalized", "artifact.archived", "artifact.invalidated", "artifact.delete.requested", "artifact.delete.blocked", "artifact.deleted", "artifact.delete.failed", "artifact.lineage.recorded", "artifact.retention.expired", "artifact.gc.completed", "artifact.gc.failed"]>;

createArtifactFrameworkEvent

Create Artifact Framework Event function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { createArtifactFrameworkEvent } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare function createArtifactFrameworkEvent<TType extends ArtifactFrameworkEventType>(input: ArtifactEventCreateInput<TType>): ArtifactFrameworkEvent<TType>;

Call signature

createArtifactFrameworkEvent<TType extends ArtifactFrameworkEventType>(input: ArtifactEventCreateInput<TType>): ArtifactFrameworkEvent<TType>

Parameters

Parameter	Type	Required	Description
input	ArtifactEventCreateInput<TType>	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ArtifactFrameworkEvent<TType>
• Description: The return contract is defined by the type shown above.

validateArtifactEventPayloadForType

Validate Artifact Event Payload For Type function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateArtifactEventPayloadForType } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare function validateArtifactEventPayloadForType<TType extends ArtifactFrameworkEventType>(type: TType, input: unknown): ArtifactEventPayloadMap[TType];

Call signature

validateArtifactEventPayloadForType<TType extends ArtifactFrameworkEventType>(type: TType, input: unknown): ArtifactEventPayloadMap[TType]

Parameters

Parameter	Type	Required	Description
type	TType	Yes	Required parameter; accepted values are defined by the type column.
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ArtifactEventPayloadMap[TType]
• Description: The return contract is defined by the type shown above.

validateArtifactEventPublication

Validate Artifact Event Publication function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateArtifactEventPublication } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare function validateArtifactEventPublication(input: unknown): ArtifactEventPublication;

Call signature

validateArtifactEventPublication(input: unknown): ArtifactEventPublication

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ArtifactEventPublication
• Description: The return contract is defined by the type shown above.

validateArtifactFrameworkEvent

Validate Artifact Framework Event function with 1 public call signature; parameters and return types are listed below.

• Kind: function
• Import: import { validateArtifactFrameworkEvent } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export declare function validateArtifactFrameworkEvent(input: unknown): ArtifactFrameworkEvent;

Call signature

validateArtifactFrameworkEvent(input: unknown): ArtifactFrameworkEvent

Parameters

Parameter	Type	Required	Description
input	unknown	Yes	Required parameter; accepted values are defined by the type column.

Returns

• Type: ArtifactFrameworkEvent
• Description: The return contract is defined by the type shown above.

ArtifactEventPayloadRequirement

Artifact Event Payload Requirement interface with 5 public fields or methods.

• Kind: interface
• Import: import type { ArtifactEventPayloadRequirement } from '@codesoul-co/hypha-core';
• Source module: modules/artifact/events

Declaration

export interface ArtifactEventPayloadRequirement {
    required: readonly (keyof ArtifactEventPayload)[];
    status?: ArtifactEventPayload['status'];
    deduplicated?: true;
    nonEmptyArtifactRefs?: boolean;
    errorCodes?: readonly string[];
}

Contract members

Member	Kind	Signature	Description
deduplicated	property	deduplicated?: true	Public property; its type, readonly modifier and optionality are shown in the signature.
errorCodes	property	errorCodes?: readonly string[]	Public property; its type, readonly modifier and optionality are shown in the signature.
nonEmptyArtifactRefs	property	nonEmptyArtifactRefs?: boolean	Public property; its type, readonly modifier and optionality are shown in the signature.
required	property	required: readonly (keyof ArtifactEventPayload)[]	Public property; its type, readonly modifier and optionality are shown in the signature.
status	property	status?: import("/Users/erwin/Downloads/codespace/Hypha/packages/core/dist/index").ArtifactStatus	Public property; its type, readonly modifier and optionality are shown in the signature.