@plurnk/plurnk-contracts 3.1.0 → 3.2.0

package/dist/schema/FunctionalityMutationResult.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "$id": "https://schemas.plurnk.xyz/v0/FunctionalityMutationResult.json",
-    "description": "The outcome of add, enable, disable, or remove: the committed state of the one affected alias. 201 added, 200 settled, 202 awaiting a protocol continuation.",
+    "description": "The committed resource outcome of add, replace, enable, disable, or remove ({§functionality-mutation-status}): 202 when the resulting definition requires authorization; otherwise 201 when add or replace creates a local definition (including an inherited override), or 200 for assignment to an existing local definition and settled enable/disable/remove. Only replace may change a different local definition.",
     "title": "FunctionalityMutationResult",
     "type": "object",
     "additionalProperties": false,

package/dist/src/Functionality.d.ts

@@ -15,6 +15,9 @@ export interface FunctionalityDefinitionSource {
     readonly alias: string;
     readonly definition: object;
 }
+export interface FunctionalityAdmission extends FunctionalityDefinitionSource {
+    readonly preparation?: unknown;
+}
 export interface FunctionalityServiceDefinition extends FunctionalityDefinitionSource {
     readonly enabled: boolean;
     readonly provenance?: FunctionalityProvenance;
@@ -43,6 +46,7 @@ export interface FunctionalityDocument {
 export interface FunctionalityPreparation extends WorkspaceCapabilityIdentity {
     readonly enabled: ReadonlyMap<string, FunctionalityPreparedDefinition>;
     readonly previous: unknown | null;
+    readonly admission?: FunctionalityAdmission;
     readonly failure: "publish-unavailable" | "reject";
     readonly force?: string;
     progress(alias: string): void;
@@ -58,7 +62,7 @@ export interface FunctionalityPrepared<Runtime = never> {
 }
 export type WorkspaceCapabilityGate = "none" | "try" | "wait";
 export interface FunctionalityFamilyHandle {
-    invoke(verb: "list" | "discover" | "add" | "enable" | "disable" | "remove", params: unknown, identity: FunctionalityIdentity): Promise<{
+    invoke(verb: "list" | "discover" | "add" | "replace" | "enable" | "disable" | "remove", params: unknown, identity: FunctionalityIdentity): Promise<{
         readonly status: number;
         readonly body: unknown;
     }>;

package/dist/src/Functionality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Functionality.d.ts","sourceRoot":"","sources":["../../src/Functionality.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEtG,MAAM,WAAW,2BAA2B;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAKD,MAAM,WAAW,qBAAsB,SAAQ,2BAA2B;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAGD,MAAM,MAAM,0BAA0B,GAAG,MAAM,0BAA0B,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEzD,MAAM,WAAW,6BAA6B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC/B;AAID,MAAM,WAAW,8BAA+B,SAAQ,6BAA6B;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,uBAAuB,CAAC;IAE9C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,+BAA+B;IAC5C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,oBAAoB,GAC1B;IAAE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAC;AAEtG,MAAM,WAAW,qBAAqB;IAGlC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAyB,SAAQ,2BAA2B;IAEzE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;IAEvE,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IAGlC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,CAAC;IAGnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,IAAI,MAAM,IAAI,CAAC;CACxB;AAOD,MAAM,WAAW,qBAAqB,CAAC,OAAO,GAAG,KAAK;IAKlD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACrD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAMD,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAK9D,MAAM,WAAW,yBAAyB;IACtC,MAAM,CACF,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,EACnE,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,qBAAqB,GAChC,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAGhE,OAAO,CACH,QAAQ,EAAE,2BAA2B,EACrC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,uBAAuB,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GACpF,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB"}
+{"version":3,"file":"Functionality.d.ts","sourceRoot":"","sources":["../../src/Functionality.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-contracts",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Canonical PLURNK language contract, schemas, generated types, and runtime-neutral wire contracts",
   "keywords": [
     "plurnk",
@@ -68,5 +68,5 @@
   "devDependencies": {
     "json-schema-to-typescript": "^16.0.0"
   },
-  "gitHead": "70dd06512f02f66f94a1dae7702085f4980f1686"
+  "gitHead": "f96502a26d62a6f87b22950a9e2006348ac8a6bc"
 }

package/plurnk.md

@@ -1,13 +1,13 @@
-# Plurnk Annotated Operation Protocol
+# Plurnk Operation Protocol
 
 > [!IMPORTANT]
 > YOU MUST ONLY emit fenced operations; with the parameters, pattern, and terse aside on the fenced Operation line.
 
 > [!IMPORTANT]
-> YOU MUST emit at least one NOTE operation with a complete status summary and at least one other operation per turn.
+> YOU MUST record at least one NOTE along with other operations.
 
 > [!TIP]
-> All operations except for NOTEs are converted into log items.
+> All operations (except NOTE) are converted into log items.
 
 ## Syntax
 
@@ -17,7 +17,7 @@ body?
 
 ## Core Operations
 
-* NOTE: Persistent Internal Annotation Register. Emit NOTE for every fact, finding, conclusion, decision, and plan.
+* NOTE: Persistent Detailed Internal Register. Emit NOTE for every summary, finding, decision, and plan (and why).
 * FIND: List matching paths, or the match locations inside one path.
 * READ: Read files, entries, streams, or only the lines a pattern selects.
 * EDIT: Create a file or entry; replace existing text by scope or by pattern.
@@ -26,34 +26,40 @@ body?
 * KILL: Delete an entry, stop a process, or retire log items.
 * WORK: Delegate to a child worker (fresh log).
 * FORK: Delegate to a child worker (copied log).
-* WAIT: Yield to child workers and streams (You may include `[60]` to check in after 60 seconds).
-* SEND: Message endpoints, workers, or respond to Open Messages.
+* WAIT: Yield to child workers and streams (not the user). You may include `[60]` to check in after 60 seconds.
+* SEND: Message endpoints, workers, or Open Messages (when the path is omitted, the oldest Open Message).
 
 ## Loop Protocol
 
-```NOTE
-exampleLoader.py:58 reads the config before exampleInit() sets its path, so every test sees the defaults. Ruled out: the cache (cleared, same failure). Unverifiable: whether plugins rely on the early read; assuming not. Decision: read it inside exampleInit(). Next: EDIT line 58, then rerun exampleTest.py.
+```NOTE <!-- summary -->
+Configuration exampleLoader.py load-order bug identified; fix and regression test pending.
+```
+
+```NOTE <!-- finding -->
+exampleLoader.py:58 reads the config before exampleInit() sets its path, so every test sees the defaults.
+```
+
+```NOTE <!-- decision -->
+Move configuration reading in exampleLoader.py into exampleInit() so it uses the initialized path. Plugin dependence on the old order is still unverified.
+```
+
+```NOTE <!-- plan -->
+Edit exampleLoader.py, then rerun exampleTest.py.
 ```
 
 ```SEND
-This is an example of a continuing turn progress update response.
+This is an example of a continuing progress update response.
 ```
 
 ```SEND [200]
-This is an example of the final deliverable response.
+This is an example of a final deliverable response.
 ```
 
 > [!TIP]
-> SEND with the (path) to respond to a specific Open Message.
-
-> [!TIP]
-> Don't include a code (`[200]` or `[499]`) with a SEND unless it's the final deliverable response.
+> YOU SHOULD include the Open Message's (path) to complete `[200]` or cancel `[499]` specific Open Messages.
 
-> [!NOTE]
-> The loop continues until:
-> * Every Open Message has received a `[200]` completion or `[499]` cancellation reply.
-> * All required operation results have been observed.
-> * All work held by the loop has settled.
+> [!CAUTION]
+> The loop continues until every Open Message has a `[200]` or `[499]` reply, operation results have been observed, and work held by the loop has settled.
 
 ## Delegation (worker:///_plurnk/plurnk/delegation.md)