@segmentstream-cloud/ontology 0.18.1 → 0.19.0

package/dist/action.d.ts

@@ -18,13 +18,15 @@ export interface ActionContext<Input, Prepared = undefined> extends PrepareConte
 /** What `prepare` may fail with: the action errors, and connection calls that failed. */
 export type PrepareError = ActionError | ConnectionError;
 /**
- * How an action behaves, as MCP tool annotations tell agents. Clients such as Claude ask the user
- * before they run a destructive tool. Without hints an action is taken as destructive and not
- * idempotent.
+ * How an action behaves. Agents confirm destructive or irreversible actions before preparation.
+ * Custom actions without safety labels require confirmation for backwards compatibility.
+ * Idempotence does not decide whether confirmation is needed.
  */
 export interface ActionHints {
-    /** Whether the action may overwrite or remove what someone decided. Default true. */
+    /** Whether the action destroys records or established decisions. Unlabelled actions default true. */
     readonly destructive?: boolean;
+    /** Whether the effect cannot be fully undone, such as sending a notification. Default false. */
+    readonly irreversible?: boolean;
     /** Whether running it again with the same input changes nothing more. Default false. */
     readonly idempotent?: boolean;
 }
@@ -79,7 +81,8 @@ interface ActionOptions<Input extends Schema.Top> {
     readonly permission?: string;
     /**
      * How the action behaves, for the agents that run it over MCP. Set `destructive: false` for an
-     * action that only adds or that history makes easy to reverse, and `idempotent: true` for one
+     * routine reversible action, `irreversible: true` for an effect without a complete undo, and
+     * `idempotent: true` for one
      * that a repeated call leaves as it was.
      */
     readonly hints?: ActionHints;

package/dist/analyze.js

@@ -641,8 +641,8 @@ function resolveActions(candidate, scope) {
     }
     return actions;
 }
-const HINT_NAMES = ["destructive", "idempotent"];
-/** The action's `hints`: an object of booleans, `destructive` and `idempotent`. */
+const HINT_NAMES = ["destructive", "irreversible", "idempotent"];
+/** The action's `hints`: an object of booleans, `destructive`, `irreversible` and `idempotent`. */
 function resolveHints(path, action, report) {
     const declared = action.hints;
     if (declared === undefined) {

package/dist/manifest.d.ts

@@ -108,10 +108,11 @@ export declare const ActionManifest: Schema.Struct<{
     readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
     /**
      * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-     * declares hints; absent reads as destructive and not idempotent.
+     * declares hints; absent safety labels require agent confirmation for compatibility.
      */
     readonly hints: Schema.optionalKey<Schema.Struct<{
         readonly destructive: Schema.optionalKey<Schema.Boolean>;
+        readonly irreversible: Schema.optionalKey<Schema.Boolean>;
         readonly idempotent: Schema.optionalKey<Schema.Boolean>;
     }>>;
 }>;
@@ -244,10 +245,11 @@ export declare const EntityManifest: Schema.Struct<{
         readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
         /**
          * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-         * declares hints; absent reads as destructive and not idempotent.
+         * declares hints; absent safety labels require agent confirmation for compatibility.
          */
         readonly hints: Schema.optionalKey<Schema.Struct<{
             readonly destructive: Schema.optionalKey<Schema.Boolean>;
+            readonly irreversible: Schema.optionalKey<Schema.Boolean>;
             readonly idempotent: Schema.optionalKey<Schema.Boolean>;
         }>>;
     }>>;
@@ -391,10 +393,11 @@ export declare const OntologyManifestWire: Schema.encodeKeys<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -541,10 +544,11 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -690,10 +694,11 @@ export declare const OntologyManifest: Schema.Union<readonly [Schema.encodeKeys<
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             /**
              * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-             * declares hints; absent reads as destructive and not idempotent.
+             * declares hints; absent safety labels require agent confirmation for compatibility.
              */
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -789,6 +794,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly connections?: readonly string[] | undefined;
             readonly hints?: {
                 readonly destructive?: boolean | undefined;
+                readonly irreversible?: boolean | undefined;
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];
@@ -894,6 +900,7 @@ export declare const decodeManifestDocument: (value: unknown) => Effect.Effect<{
             readonly connections?: readonly string[] | undefined;
             readonly hints?: {
                 readonly destructive?: boolean | undefined;
+                readonly irreversible?: boolean | undefined;
                 readonly idempotent?: boolean | undefined;
             } | undefined;
         }[];

package/dist/manifest.js

@@ -104,10 +104,11 @@ export const ActionManifest = Schema.Struct({
     connections: Schema.optionalKey(Schema.Array(Schema.String)),
     /**
      * How the action behaves, as MCP tool annotations tell agents. Written only when the action
-     * declares hints; absent reads as destructive and not idempotent.
+     * declares hints; absent safety labels require agent confirmation for compatibility.
      */
     hints: Schema.optionalKey(Schema.Struct({
         destructive: Schema.optionalKey(Schema.Boolean),
+        irreversible: Schema.optionalKey(Schema.Boolean),
         idempotent: Schema.optionalKey(Schema.Boolean),
     })),
 });

package/dist/migrate/model.d.ts

@@ -128,6 +128,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly hints: Schema.optionalKey<Schema.Struct<{
                     readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                     readonly idempotent: Schema.optionalKey<Schema.Boolean>;
                 }>>;
             }>>;
@@ -240,6 +241,7 @@ export declare const MigrationPlan: Schema.Struct<{
                 readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
                 readonly hints: Schema.optionalKey<Schema.Struct<{
                     readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                    readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                     readonly idempotent: Schema.optionalKey<Schema.Boolean>;
                 }>>;
             }>>;

package/dist/service/mcp/tools.d.ts

@@ -6,6 +6,8 @@ import type { PlannedAction, PlannedEntity } from "../plan.js";
 export interface McpToolAnnotations {
     readonly readOnlyHint: boolean;
     readonly destructiveHint?: boolean;
+    /** Ontology extension: whether the action has an effect without a complete undo. */
+    readonly irreversibleHint?: boolean;
     readonly idempotentHint?: boolean;
     /** Whether the tool reaches beyond the ontology: true for actions that call connections. */
     readonly openWorldHint: boolean;

package/dist/service/mcp/tools.js

@@ -65,22 +65,28 @@ function historyInput(label) {
 const READ = { readOnlyHint: true, openWorldHint: false };
 /** The hints of generated actions, which only their name tells apart. */
 const GENERATED_HINTS = {
-    create: { destructive: false, idempotent: false },
-    update: { destructive: true, idempotent: true },
-    delete: { destructive: true, idempotent: true },
-    link: { destructive: false, idempotent: true },
-    unlink: { destructive: true, idempotent: true },
+    create: { destructive: false, irreversible: false, idempotent: false },
+    update: { destructive: false, irreversible: false, idempotent: true },
+    delete: { destructive: true, irreversible: false, idempotent: true },
+    link: { destructive: false, irreversible: false, idempotent: true },
+    unlink: { destructive: false, irreversible: false, idempotent: true },
 };
 /** MCP's defaults for a tool that writes: it may destroy, and repeating it may change more. */
-const AUTHORED_DEFAULT = { destructive: true, idempotent: false };
+const AUTHORED_DEFAULT = {
+    destructive: true,
+    irreversible: false,
+    idempotent: false,
+};
 function hintsOf(planned, { name, generated }) {
     if (generated) {
         return name.startsWith(GENERATED_UPSERT_PREFIX)
-            ? { destructive: true, idempotent: true }
+            ? { destructive: false, irreversible: false, idempotent: true }
             : (GENERATED_HINTS[name] ?? AUTHORED_DEFAULT);
     }
     const declared = planned.resolved.actions.find((candidate) => candidate.name === name)?.hints;
-    return { ...AUTHORED_DEFAULT, ...declared };
+    // A safety label classifies the action; idempotence alone does not opt out of confirmation.
+    const classified = declared?.destructive !== undefined || declared?.irreversible !== undefined;
+    return { ...AUTHORED_DEFAULT, ...(classified ? { destructive: false } : {}), ...declared };
 }
 /** How an agent reaches the records a relationship leads to, with the tools it has. */
 function relatedHint(planned, traversal) {
@@ -208,6 +214,7 @@ function actionTool(planned, plannedAction) {
         annotations: {
             readOnlyHint: false,
             destructiveHint: hints.destructive,
+            irreversibleHint: hints.irreversible,
             idempotentHint: hints.idempotent,
             openWorldHint: action.connections.length > 0,
         },

package/dist/service/schemas.d.ts

@@ -235,6 +235,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;
@@ -353,6 +354,7 @@ export declare const Catalog: Schema.decodeTo<Schema.Struct<{
             readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
             readonly hints: Schema.optionalKey<Schema.Struct<{
                 readonly destructive: Schema.optionalKey<Schema.Boolean>;
+                readonly irreversible: Schema.optionalKey<Schema.Boolean>;
                 readonly idempotent: Schema.optionalKey<Schema.Boolean>;
             }>>;
         }>>;

package/dist/storage/attachments.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { Effect } from "effect";
-import { acceptsBlobContentType, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
+import { acceptsBlobContentType, isBlobContentType, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES, } from "../blob.js";
 import { ActionRejected, Conflict, NotFound } from "../errors.js";
 import { canonicalJson } from "../manifest.js";
 import { actionInputJsonSchema } from "../runtime/generated-actions.js";
@@ -142,7 +142,7 @@ export function attachmentRuntime(ontology, sql, provider) {
             input.filename === "" ||
             input.filename.length > 255 ||
             /[\x00-\x1f\x7f/\\]/.test(input.filename) ||
-            !/^[\w.+-]+\/[\w.+-]+$/.test(input.contentType) ||
+            !isBlobContentType(input.contentType) ||
             !Number.isInteger(input.size) ||
             input.size <= 0 ||
             !SHA256.test(input.sha256)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",