@sentropic/artifacts 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.2.6
+
+- Integrate part 1 with the source reads, sharing, terminal deletion, masking and
+  summaries published in 0.2.5. Apply `0005_metadata.sql` after 0004; it adds
+  editorial metadata and nullable release authors/lineage without backfilling history.
+- Add version history and revert as a new release on the same stable URL, preserving
+  current metadata and ACLs. The v2 profile uses `targetReleaseId` and paginated history.
+- Add full-bundle or exactly-once text edits, metadata on ensure/publish, and
+  transactional release CAS, metadata, references, quota and receipts.
+- Separate trusted `profileRevisionId`, `requireExpectedCurrentReleaseId` and
+  `resultEnvelopeVersion`. Compatible bindings keep root results; strict v2 retains
+  commit state, replay status and typed failures through mcp-platform 0.4.1.
+- Replay historical receipts before enforcing new preconditions or preparing edits.
+  Missing strict preconditions use the R2 `precondition_required` message and details.
+
+IMMO activates part 1 only after its qualified input and result switchovers.
+Artifacts 0.2.6 stays inside the existing cluster-mesh `>=0.2.0 <0.3.0` range;
+the API consumes the workspace package and retains its pinned APP-P1 profile.
+
+## 0.2.5
+
+- D1: Read verified author manifests and file bytes for the current or a selected
+  release, with path selection, source authorization, bounded snapshots and
+  separate provenance. Reject purged releases and mismatched record digests.
+- D2: Grant or revoke named read access and delete artifacts terminally with
+  host-approved confirmation, transactional receipts and idempotent replay.
+  Mask artifacts outside the caller's visibility as `not_found`.
+- D4: Enrich get/list results with binding names, dates, current release IDs,
+  digests, stable/pinned URLs, permissions and available optional metadata.
+
+Apply `0004_terminal_controls.sql` after migrations 0001–0003 before enabling
+the management capabilities.

package/README.md

@@ -1,5 +1,12 @@
 # @sentropic/artifacts — generic artifact contracts (L-5a)
 
+Publication profiles can set `requireExpectedCurrentReleaseId: true` to require an
+explicit UUID or `null` on publish/revert. Strict profiles reject writers without
+CAS. Omission remains supported in generic profiles. Replay the same caller key
+after an unknown commit outcome; changing files, edits, metadata or the precondition
+requires a new key. The `artifacts-outcome/v2` MCP envelope requires
+`@sentropic/mcp-platform >=0.4.1` and preserves commit state and typed error details.
+
 ## Shared PostgreSQL activation (UP-T, 0.2.3)
 
 W1.c/W3.a and Radar S1/A6 use the same imports:
@@ -314,7 +321,8 @@ The installed package includes SQL resources exported under
 ```js
 import { readFile } from 'node:fs/promises';
 
-const migrations = ['0001_artifacts.sql', '0002_lifecycle.sql'];
+const migrations = ['0001_artifacts.sql', '0002_lifecycle.sql', '0003_coordinator.sql',
+  '0004_terminal_controls.sql', '0005_metadata.sql'];
 for (const name of migrations) {
   const sql = await readFile(new URL(import.meta.resolve(
     `@sentropic/artifacts/migrations/${name}`,
@@ -324,8 +332,10 @@ for (const name of migrations) {
 ```
 
 Apply `0001_artifacts.sql` first to create the domain schema, then
-`0002_lifecycle.sql` to add lifecycle, sharing, sources and GC support, before
-using the Postgres store. The host owns migration credentials, serialization,
+`0002_lifecycle.sql` to add lifecycle, sharing, sources and GC support, then
+`0003_coordinator.sql`, `0004_terminal_controls.sql`, and `0005_metadata.sql`
+(artifact display metadata and nullable release lineage),
+before using the Postgres store. The host owns migration credentials, serialization,
 transactions and the migration journal; execute each version through that
 runner rather than running this read loop at application startup.
 
@@ -417,3 +427,41 @@ publication, use the current package version and this bootstrap sequence
 3. After that, merges to `main` touching the artifacts package publish
    through the `publish-artifacts` job (`make publish-artifacts`, OIDC +
    provenance), gated by `validate-artifacts`.
+
+## Source and management capabilities
+
+Version 0.3.0 introduces D1, D2 and D4; see [CHANGELOG.md](./CHANGELOG.md).
+
+Hosts may explicitly select `artifacts_get_source`, `artifacts_set_access`, and
+`artifacts_delete` in their compiled profile. Configure `get_source` with empty
+limits/defaults, and `set_access`/`delete` with `idempotencyKeyMaxUnits: 256` and
+empty defaults. Existing profile selections remain explicit.
+
+`POST /get_source` accepts `artifactId`, optional `releaseId`, and optional unique
+`paths` (1–32 entries). Bind `publication.getRelease` and `sources.getSource` on
+the HTTP app. It returns the canonical manifest, verified author file bytes,
+and separate nullable `sourceRef`; readers need the distinct source permission.
+The snapshot is limited to 32 files and 262144 decoded bytes. Hosts must qualify
+a 2 MiB serialized MCP result budget before selecting this capability.
+
+`POST /set_access` grants or revokes a named principal's read access, requires a
+caller `idempotencyKey`, and keeps the artifact private. Bind
+`isApprovedAccount` to the host's principal policy. `POST /delete` also requires
+`expectedCurrentReleaseId` (nullable) and a trusted `management.confirmation`
+port. Its `request` method issues a challenge for the host management UI;
+`consume` verifies the human-approved proof, expiration and full command context
+on the supplied transaction. A caller boolean is never confirmation. Repeated
+successful deletes return the stored receipt without consuming proof again.
+
+Apply `migrations/0004_terminal_controls.sql` after `0001_artifacts.sql`,
+`0002_lifecycle.sql` and `0003_coordinator.sql` before activation.
+The default management writer uses the coordinator's PostgreSQL
+transaction; alternative stores implement `management.createUnit` with the same
+parent/ACL/current lock order and transactional effects. Terminal markers and
+SQL guards prevent restoration and later publication. Deletion reports
+`purgeState: "pending"`; physical purge belongs to host retention policy.
+
+Get/list include binding, creation/modification dates, current release, digest,
+host URLs and available metadata. Historical modification dates stay nullable.
+The PostgreSQL projection reads the optional metadata column added by the
+publication parity lane without requiring that column for older stores.

package/dist/adapters/postgres-management.d.ts

@@ -0,0 +1,4 @@
+import type { FinalizeTxClient } from '../server/commit/types.js';
+import type { ManagementUnit } from '../server/management.js';
+/** Parent lock serializes ACL inserts, lifecycle changes and publication FKs. */
+export declare function createPostgresManagementUnit(client: FinalizeTxClient): ManagementUnit;

package/dist/adapters/postgres-management.js

@@ -0,0 +1,36 @@
+/** Parent lock serializes ACL inserts, lifecycle changes and publication FKs. */
+export function createPostgresManagementUnit(client) {
+    return {
+        async lock(id) {
+            await client.query('SELECT id FROM artifacts.artifacts WHERE id = $1 FOR UPDATE', [id]);
+            await client.query('SELECT principal_id FROM artifacts.artifact_access WHERE artifact_id = $1 ORDER BY principal_id FOR UPDATE', [id]);
+            await client.query('SELECT release_id FROM artifacts.artifact_current WHERE artifact_id = $1 FOR UPDATE', [id]);
+        },
+        async read(id) {
+            const { rows } = await client.query(`SELECT a.owner_id, a.storage_scope_id, a.lifecycle_state, a.is_public, a.terminal_deleted_at, c.release_id
+         FROM artifacts.artifacts a LEFT JOIN artifacts.artifact_current c ON c.artifact_id = a.id WHERE a.id = $1`, [id]);
+            const row = rows[0];
+            if (!row)
+                return undefined;
+            const acl = { ownerId: row.owner_id, storageScopeId: row.storage_scope_id,
+                isPublic: row.is_public, withdrawn: row.lifecycle_state === 'withdrawn', grants: [] };
+            return { acl, state: row.lifecycle_state, terminal: row.terminal_deleted_at !== null,
+                currentReleaseId: row.release_id };
+        },
+        async setAccess(id, principalId, action, updatedAt) {
+            const changed = action === 'grant' ? await client.query(`INSERT INTO artifacts.artifact_access (artifact_id, principal_id, permission) VALUES ($1, $2, 'read')
+         ON CONFLICT (artifact_id, principal_id) DO NOTHING`, [id, principalId])
+                : await client.query('DELETE FROM artifacts.artifact_access WHERE artifact_id = $1 AND principal_id = $2', [id, principalId]);
+            await client.query(`UPDATE artifacts.artifacts SET is_public = false, updated_at = $2
+        WHERE id = $1 AND ($3::boolean OR is_public)`, [id, updatedAt, changed.rowCount > 0]);
+            const result = await client.query('SELECT principal_id, permission FROM artifacts.artifact_access WHERE artifact_id = $1 ORDER BY principal_id', [id]);
+            const stamp = await client.query('SELECT updated_at FROM artifacts.artifacts WHERE id = $1', [id]);
+            return { grants: result.rows.map((row) => ({ principalId: row.principal_id, grant: row.permission })),
+                updatedAt: stamp.rows[0]?.updated_at?.toISOString() ?? null };
+        },
+        async delete(id, deletedAt) {
+            await client.query(`UPDATE artifacts.artifacts SET lifecycle_state = 'deleted', terminal_deleted_at = $2,
+        updated_at = $2, is_public = false WHERE id = $1`, [id, deletedAt]);
+        },
+    };
+}

package/dist/adapters/postgres.js

@@ -1,3 +1,4 @@
+import { ArtifactOperationError } from '../server/failures.js';
 /** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
 export function createPostgresLegacyArtifactRecords(pool) {
     return {
@@ -20,6 +21,9 @@ function toIntent(row) {
 }
 function toRelease(row) {
     return {
+        authorPrincipalId: row.author_principal_id ?? null,
+        parentReleaseId: row.parent_release_id ?? null,
+        revertedFromReleaseId: row.reverted_from_release_id ?? null,
         releaseId: row.id,
         artifactId: row.artifact_id,
         manifestDigest: row.manifest_digest,
@@ -34,8 +38,10 @@ export function createPostgresArtifactStore(pool) {
         async ensureArtifact(input) {
             const where = `WHERE storage_scope_id = $1 AND owner_id = $2 AND binding_name = $3`;
             const args = [input.storageScopeId, input.ownerId, input.bindingName];
-            const found = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            const found = await pool.query(`SELECT id, (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a ${where}`, args);
             if (found.rowCount !== 0 && found.rows[0] !== undefined) {
+                if (found.rows[0].terminal)
+                    throw new ArtifactOperationError('gone');
                 return { artifactId: found.rows[0].id, created: false };
             }
             const inserted = await pool.query(`INSERT INTO artifacts.artifacts (id, storage_scope_id, owner_id, binding_name, profile)
@@ -44,10 +50,12 @@ export function createPostgresArtifactStore(pool) {
             if (inserted.rowCount !== 0 && inserted.rows[0] !== undefined) {
                 return { artifactId: inserted.rows[0].id, created: true };
             }
-            const raced = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            const raced = await pool.query(`SELECT id, (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a ${where}`, args);
             const row = raced.rows[0];
             if (row === undefined)
                 throw new Error(`artifact binding lost for ${input.bindingName}`);
+            if (row.terminal)
+                throw new ArtifactOperationError('gone');
             return { artifactId: row.id, created: false };
         },
         async record(kind, payload) {
@@ -138,11 +146,14 @@ export function createPostgresArtifactStore(pool) {
             }
         },
         async getRelease(releaseId) {
-            const { rows } = await pool.query(`SELECT id, artifact_id, manifest_digest, manifest, state, created_at
-         FROM artifacts.releases WHERE id = $1`, [releaseId]);
+            const { rows } = await pool.query(`SELECT * FROM artifacts.releases WHERE id = $1`, [releaseId]);
             const row = rows[0];
             return row === undefined ? undefined : toRelease(row);
         },
+        async listReleases(artifactId) {
+            const { rows } = await pool.query(`SELECT * FROM artifacts.releases WHERE artifact_id = $1 ORDER BY created_at, id`, [artifactId]);
+            return rows.map(toRelease);
+        },
         async getCurrentReleaseId(artifactId) {
             const { rows } = await pool.query(`SELECT release_id FROM artifacts.artifact_current WHERE artifact_id = $1`, [artifactId]);
             return rows[0]?.release_id;
@@ -185,14 +196,17 @@ export function createPostgresArtifactStore(pool) {
             return rows.map((row) => row.digest);
         },
         async getArtifactAcl(artifactId) {
-            const { rows } = await pool.query(`SELECT owner_id, storage_scope_id, is_public, lifecycle_state
-         FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            const { rows } = await pool.query(`SELECT owner_id, storage_scope_id, is_public, lifecycle_state, binding_name, created_at,
+          to_jsonb(a)->>'updated_at' AS updated_at, to_jsonb(a)->'metadata' AS metadata
+         FROM artifacts.artifacts a WHERE id = $1`, [artifactId]);
             const row = rows[0];
             if (row === undefined)
                 return undefined;
             const grants = await pool.query(`SELECT principal_id, permission FROM artifacts.artifact_access
          WHERE artifact_id = $1 ORDER BY principal_id`, [artifactId]);
             return {
+                bindingName: row.binding_name, createdAt: row.created_at.toISOString(), updatedAt: row.updated_at,
+                ...(row.metadata ?? {}),
                 ownerId: row.owner_id,
                 storageScopeId: row.storage_scope_id,
                 isPublic: row.is_public,
@@ -201,14 +215,15 @@ export function createPostgresArtifactStore(pool) {
                     principalId: grant.principal_id,
                     grant: grant.permission,
                 })),
+                ...(row.metadata === null || Object.keys(row.metadata).length === 0 ? {} : { metadata: row.metadata }),
             };
         },
         async putArtifactAcl(artifactId, acl) {
-            await pool.query(`UPDATE artifacts.artifacts SET is_public = $2,
+            await pool.query(`UPDATE artifacts.artifacts SET is_public = $2, metadata = $4,
          lifecycle_state = CASE WHEN $3 THEN 'withdrawn'
            WHEN lifecycle_state = 'withdrawn' THEN 'active'
            ELSE lifecycle_state END
-         WHERE id = $1`, [artifactId, acl.isPublic, acl.withdrawn]);
+         WHERE id = $1`, [artifactId, acl.isPublic, acl.withdrawn, JSON.stringify(acl.metadata ?? {})]);
             await pool.query(`DELETE FROM artifacts.artifact_access WHERE artifact_id = $1`, [
                 artifactId,
             ]);
@@ -263,6 +278,13 @@ export function createPostgresArtifactStore(pool) {
             const { rows } = await pool.query(`SELECT lifecycle_state FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
             return rows[0]?.lifecycle_state ?? 'active';
         },
+        async isTerminal(artifactId) {
+            const { rows } = await pool.query("SELECT (to_jsonb(a)->>'terminal_deleted_at') IS NOT NULL AS terminal FROM artifacts.artifacts a WHERE id = $1", [artifactId]);
+            return rows[0]?.terminal === true;
+        },
+        async markTerminal(artifactId) {
+            await pool.query("UPDATE artifacts.artifacts SET terminal_deleted_at = coalesce(terminal_deleted_at, now()), lifecycle_state = 'deleted' WHERE id = $1", [artifactId]);
+        },
         async setArtifactState(artifactId, state) {
             const updated = await pool.query(`UPDATE artifacts.artifacts SET lifecycle_state = $2 WHERE id = $1`, [artifactId, state]);
             if ((updated.rowCount ?? 0) === 0)

package/dist/http.d.ts

@@ -7,6 +7,9 @@ import type { AclStore } from './server/access.js';
 import type { LifecycleService } from './server/lifecycle.js';
 import { type ArtifactInvocationContext, type ArtifactCommitCoordinator } from './server/commit/types.js';
 import { type ArtifactOutcome, type ArtifactHostFailureMapper } from './server/failures.js';
+import { type ManagementUnit, type ArtifactConfirmationPort } from './server/management.js';
+import type { FinalizeTxClient } from './server/commit/types.js';
+import type { SourceStore } from './server/sources.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 export interface HttpRequest {
     method: string;
@@ -37,9 +40,16 @@ export interface HttpAppDeps {
     ensureHost: GuardedEnsureHost;
     publication: Omit<GuardedPublicationDeps, 'coordinator' | 'limits'> & {
         getCurrent: PublicationService['getCurrent'];
+        getRelease: PublicationService['getRelease'];
+        listReleases: PublicationService['listReleases'];
+    };
+    sources?: Pick<SourceStore, 'getSource'>;
+    management?: {
+        createUnit?: (client: FinalizeTxClient) => ManagementUnit;
+        confirmation?: ArtifactConfirmationPort;
     };
     acls: AclStore;
-    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead'>;
+    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead' | 'getReleaseState'>;
     isApprovedAccount?: (principalId: string) => boolean;
     /** One trusted URL policy shared by HTTP and MCP receipts. */
     publicationUrls?: (artifactId: string, releaseId: string) => {