@sentropic/artifacts 0.0.0-stage → 0.1.0

package/dist/contracts.d.ts

@@ -0,0 +1,102 @@
+/**
+ * L-5a — artifact domain contracts (spec-v8 §9).
+ *
+ * Generic, host-independent state: StorageScope, Artifact, Binding, Release,
+ * File/BlobRef, Source, ACL, hostname reservation, Upload, BlobPin,
+ * ObjectIntent and operation idempotency. Schema types are independent of
+ * ORM rows; no server, driver or cluster-mesh imports; no eager storage
+ * connections or DDL on import. Identities are server-allocated UUIDs.
+ */
+export declare const ARTIFACT_SCHEMA_VERSIONS: readonly ["artifacts/v1"];
+export type ArtifactSchemaVersion = (typeof ARTIFACT_SCHEMA_VERSIONS)[number];
+/** Refuse unknown schema versions (fail-closed on version skew). */
+export declare function assertKnownSchemaVersion(version: unknown): asserts version is ArtifactSchemaVersion;
+/** True for server-allocated UUID identities. */
+export declare function isArtifactId(value: unknown): value is string;
+/** JSON value (undefined only as an absent property, never serialized). */
+export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+/**
+ * Content-addressed manifest: canonical bytes + SHA-256 digest, versioned
+ * schema. `digest` is optional: construction precedes sealing, so working
+ * documents carry no digest and sealed documents must verify against it.
+ */
+export interface CanonicalManifest {
+    schemaVersion: string;
+    digest?: string;
+    [key: string]: unknown;
+}
+/** Allocate a server-side identity (UUID v4). */
+export declare function createArtifactId(): string;
+/** Opaque storage scope isolating physical keys from org reindexing. */
+export interface StorageScope {
+    readonly storageScopeId: string;
+    readonly createdAt: string;
+}
+/** An artifact: one logical view across releases. */
+export interface Artifact {
+    readonly id: string;
+    readonly schemaVersion: ArtifactSchemaVersion;
+    readonly storageScopeId: string;
+    readonly ownerId: string;
+    readonly createdAt: string;
+    readonly deletedAt?: string;
+}
+/** A stable owner-scoped binding resolving to one artifact. */
+export interface Binding {
+    readonly binding: string;
+    readonly artifactId: string;
+    readonly ownerId: string;
+}
+/** An immutable release of an artifact's manifest + bytes. */
+export interface Release {
+    readonly id: string;
+    readonly artifactId: string;
+    readonly manifestDigest: string;
+    readonly createdAt: string;
+    readonly state: 'pending' | 'ready' | 'withdrawn' | 'purged';
+}
+/** A content blob referenced by digest. */
+export interface BlobRef {
+    readonly digest: string;
+    readonly size: number;
+    readonly mimeType: string;
+}
+/** Provenance of a release's sources. */
+export type ArtifactSource = {
+    readonly kind: 'inline-original';
+} | {
+    readonly kind: 'recipe';
+    readonly baseCommit: string;
+    readonly recipe: string;
+};
+/** Object-level access grant. */
+export interface AccessGrant {
+    readonly artifactId: string;
+    readonly subjectId: string;
+    readonly rights: readonly ('read' | 'source-export' | 'write')[];
+}
+/** A bounded upload session staging bytes before commit. */
+export interface Upload {
+    readonly id: string;
+    readonly artifactId: string;
+    readonly prefix: string;
+    readonly createdAt: string;
+    readonly state: 'open' | 'committed' | 'aborted';
+}
+/** A pin retaining a blob against concurrent GC. */
+export interface BlobPin {
+    readonly digest: string;
+    readonly artifactId: string;
+    readonly reason: 'release' | 'fork' | 'upload';
+}
+/** Recorded intent before every external object operation. */
+export interface ObjectIntent {
+    readonly idempotencyKey: string;
+    readonly artifactId: string;
+    readonly operation: string;
+    readonly recordedAt: string;
+    readonly state: 'recorded' | 'applied' | 'failed';
+}

package/dist/contracts.js

@@ -0,0 +1,25 @@
+/**
+ * L-5a — artifact domain contracts (spec-v8 §9).
+ *
+ * Generic, host-independent state: StorageScope, Artifact, Binding, Release,
+ * File/BlobRef, Source, ACL, hostname reservation, Upload, BlobPin,
+ * ObjectIntent and operation idempotency. Schema types are independent of
+ * ORM rows; no server, driver or cluster-mesh imports; no eager storage
+ * connections or DDL on import. Identities are server-allocated UUIDs.
+ */
+export const ARTIFACT_SCHEMA_VERSIONS = ['artifacts/v1'];
+/** Refuse unknown schema versions (fail-closed on version skew). */
+export function assertKnownSchemaVersion(version) {
+    if (!ARTIFACT_SCHEMA_VERSIONS.includes(version)) {
+        throw new Error(`unknown artifact schema version: ${String(version)}`);
+    }
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** True for server-allocated UUID identities. */
+export function isArtifactId(value) {
+    return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+/** Allocate a server-side identity (UUID v4). */
+export function createArtifactId() {
+    return crypto.randomUUID();
+}

package/dist/http.d.ts

@@ -0,0 +1,43 @@
+import type { ParameterSchema } from './parameters.js';
+import type { ArtifactService } from './server/service.js';
+import type { PublicationBlobStore, PublicationService } from './server/publication.js';
+import type { LifecycleService } from './server/lifecycle.js';
+import type { ForkService } from './server/fork.js';
+import { type AclStore } from './server/access.js';
+import { type SourceStore } from './server/sources.js';
+import type { StagingStore, UploadService } from './server/uploads.js';
+import type { TemplateCatalogPort } from './server/templates.js';
+export interface HttpRequest {
+    method: string;
+    path: string;
+    body: unknown;
+    actorId: string;
+}
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+}
+export interface HttpAppDeps {
+    parameterSchema: ParameterSchema;
+    artifacts: ArtifactService;
+    publication: PublicationService;
+    lifecycle: LifecycleService;
+    forks: ForkService;
+    acls: AclStore;
+    sources: SourceStore;
+    blobs: PublicationBlobStore;
+    isApprovedAccount?: (principalId: string) => boolean;
+    /** Bounded upload sessions (L-5e); upload routes refuse when unwired. */
+    uploads?: UploadService;
+    staging?: StagingStore;
+    /** Template kit + API guide catalog (L-5e); refuses when unwired. */
+    templates?: TemplateCatalogPort;
+}
+/** Stable error body for one status; internal messages never leave the app. */
+export declare function errorBody(status: number): {
+    error: string;
+};
+/** Create the HTTP app over injected services (no server, no fetch). */
+export declare function createHttpArtifactApp(deps: HttpAppDeps): {
+    handle(request: HttpRequest): Promise<HttpResponse>;
+};