hclang 0.40.0 → 0.41.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1104,6 +1104,63 @@ export const HC_SOURCES = new Map([
1104
1104
  "; [Outer.ks(), Inner.ks()]",
1105
1105
  "# [[1, 1], [5, 5]]",
1106
1106
  "",
1107
+ "`A class answers a binary arithmetic operator on its instances by declaring a",
1108
+ "method under the operator's own name, + - * or /, the way it declares apply or",
1109
+ "toText (015.02). The operator resolves against its left operand's declared",
1110
+ "method and the global built-in, and never the lexical scope the operand was",
1111
+ "read from. A declared method takes the right operand and answers the result.`",
1112
+ "; .Vec [.n 3; .+ {.a (_^ .n); .b (_ .n); [.n (a + b)]}];",
1113
+ "; (Vec + [.n 4]).n",
1114
+ "# 7",
1115
+ "",
1116
+ "`The declared operator overrides the global built-in only when the aggregate is",
1117
+ "the left operand. Ordinary numeric arithmetic keeps the global operation.`",
1118
+ "; 2 + 3",
1119
+ "# 5",
1120
+ "",
1121
+ "`A declared operator resolves through the declared-parent chain, the same chain",
1122
+ "an aggregate's other methods come from, so a child inherits it.`",
1123
+ "; .AddBase [.n 0; .+ {.a (_^ .n); .b (_ .n); [.n (a + b)]}];",
1124
+ "; .AddKid [.^ AddBase; .n 10];",
1125
+ "; (AddKid + [.n 5]).n",
1126
+ "# 15",
1127
+ "",
1128
+ "`A lexical operator-named method in the surrounding scope does not shadow global",
1129
+ "arithmetic for an ordinary numeric left operand, which carries no lexical scope",
1130
+ "into the operator.`",
1131
+ "; .+ {999};",
1132
+ "; 2 + 3",
1133
+ "# 5",
1134
+ "",
1135
+ "`Nor does a receiver's own declared + shadow the global + used inside that",
1136
+ "receiver's other methods. A numeric load read back from the receiver and used",
1137
+ "with + takes the global operation, so there is no receiver-scope recursion or",
1138
+ "stack overflow. A lexical walk would find the class's own + and recur; before",
1139
+ "015.02 this spelling overflowed the stack.`",
1140
+ "; .Ring [.base 2; .+ {_ + 100}; .inc {(_^ .base) + 3}];",
1141
+ "; Ring.inc()",
1142
+ "# 5",
1143
+ "",
1144
+ "`The same receiver still answers + when it is itself the left operand, resolving",
1145
+ "its own declared method rather than the global built-in.`",
1146
+ "; Ring + 100",
1147
+ "# 200",
1148
+ "",
1149
+ "`The declared-operator hook is scoped to the arithmetic spellings + - * / only.",
1150
+ "A built-in operator outside that set, such as membership ~, is unaffected: a",
1151
+ "class that declares .~ does not intercept it, and the global operation answers",
1152
+ "for an aggregate and for a number alike.`",
1153
+ "; .Thing [.~ {999}; .v 5];",
1154
+ "; Thing ~ ([].<>)",
1155
+ "# <>",
1156
+ "; 5 ~ (0.<>)",
1157
+ "# <>",
1158
+ "",
1159
+ "`A named arithmetic spelling, 2 .+ 2, is ordinary application and not the binary",
1160
+ "operator, so it is unchanged.`",
1161
+ "; 2 .+ 2",
1162
+ "# 4",
1163
+ "",
1107
1164
  ].join("\n"),
1108
1165
  ],
1109
1166
  [
@@ -1430,9 +1487,37 @@ export const HC_SOURCES = new Map([
1430
1487
  "",
1431
1488
  "**Scaling**, `d.scale_ k`: multiply both loads by a Count k, keeping the",
1432
1489
  "phase. It is the numerical shadow of Star: `(x * y).####` is",
1433
- "`x.####.scale_ (y.##)` for a nonempty host x. Scaling is a method because a",
1434
- "class cannot declare an operator, so `d * k` is ordinary Star, which refuses",
1435
- "an aggregate with properties.",
1490
+ "`x.####.scale_ (y.##)` for a nonempty host x. `scale_` stays, as the name the",
1491
+ "fourth hash and Star correspondence use; `d * k` now answers the same Demi",
1492
+ "through the operator below.",
1493
+ "",
1494
+ "**Arithmetic**, `d + x`, `d - x`, `d * k` and `d / n` (015.02). A class answers",
1495
+ "an operator by declaring a method under its name, found on the operand and its",
1496
+ "declared parents, the chain its other methods come from, so an operator in a",
1497
+ "method body keeps its global meaning rather than recurring into the class that",
1498
+ "is running. `+`, `-` and `*` **construct a fresh Demi state** from Size and",
1499
+ "Count observations of their operands, keeping Figure 008's distinction between",
1500
+ "construction and observation; `/` is the one that answers a Spin observation, a",
1501
+ "number rather than a Demi. None of the four is application: none flips the",
1502
+ "phase, and each answers a fresh value and leaves `d` as it was.",
1503
+ "",
1504
+ "- `d + x` deposits `x.##` on the **right**: `Demi [p, L, R + x.##]`. A sizeless",
1505
+ " host's failure is the answer, as it is for application.",
1506
+ "- `d - x` deposits on the **left**: `Demi [p, L + x.##, R]`. It is not",
1507
+ " subtraction: a deposit only ever adds, so a load never goes negative and",
1508
+ " stays a whole Count. Right deposition lowers the signed residual `L − R` and",
1509
+ " left deposition raises it, the reverse of ordinary signed-scalar `+` and `-`.",
1510
+ "- `d * k` scales both loads by an admissible Count k, `Demi [p, kL, kR]`, the",
1511
+ " same rule as `scale_`, refusing a non-Count with `$!!.invalid-scale`.",
1512
+ "- `d / n` observes Spin, the signed residual over a strictly positive Count,",
1513
+ " `(L − R) / n`. It answers a number, not a Demi, and keeps the typed divisor:",
1514
+ " a non-Count, including a negative, is a type error, and a zero divisor is",
1515
+ " `$!.division-by-zero`.",
1516
+ "",
1517
+ "None of these is sequential application: `d x` deposits in the active channel",
1518
+ "and flips the phase, while `+`, `-` and `*` choose a channel explicitly and",
1519
+ "keep it. So `+` and `-` reach states a run cannot, a phase-2 Demi with a load",
1520
+ "on the odd side, and `*` is the Star shadow, not a repeated deposit.",
1436
1521
  "",
1437
1522
  "**Text.** A Demi prints as what it is, an aggregate of fields and methods, and",
1438
1523
  "that reads back as the same Demi. As text it reads `Demi(<>,12,3)`, with the",
@@ -1457,6 +1542,14 @@ export const HC_SOURCES = new Map([
1457
1542
  " (s ~ (0.<>)) ? {((_^^ .phase) = 2) ? {@left (l + s); @phase 1;} : {@right (r + s); @phase 2;}; _^^} : {s}};",
1458
1543
  " .scale_ {.k _; .l (_^ .left); .r (_^ .right);",
1459
1544
  " (k ~ (0.<>)) ? {@left (l * k); @right (r * k); _^^} : {$!!.invalid-scale}};",
1545
+ " .+ {.s (_ .##); .p (_^ .phase); .l (_^ .left); .r (_^ .right);",
1546
+ " (s ~ (0.<>)) ? {Demi [p, l, (r + s)]} : {s}};",
1547
+ " .- {.s (_ .##); .p (_^ .phase); .l (_^ .left); .r (_^ .right);",
1548
+ " (s ~ (0.<>)) ? {Demi [p, (l + s), r]} : {s}};",
1549
+ " .* {.k _; .p (_^ .phase); .l (_^ .left); .r (_^ .right);",
1550
+ " (k ~ (0.<>)) ? {Demi [p, (l * k), (r * k)]} : {$!!.invalid-scale}};",
1551
+ " ./ {.n <(1).<>> _; .signed (_^ .###);",
1552
+ " (n .< 1) ? {signed / 0} : {signed / n}};",
1460
1553
  " .toText {“Demi(” (((_^ .phase) = 2) ? {“<>”} : {“()”}) “,” (_^ .left) “,” (_^ .right) “)”}",
1461
1554
  " ]} : {$!!.invalid-demi}} : {$!!.invalid-demi}};",
1462
1555
  "```",
@@ -1615,11 +1708,73 @@ export const HC_SOURCES = new Map([
1615
1708
  "; [([5, 3] * 3).#### = ([5, 3].####.scale_ 3), ([[[]], []] * [[], []]).#### = ([[[]], []].####.scale_ ([[], []].##))]",
1616
1709
  "# [<>, <>]",
1617
1710
  "```",
1618
- "No operator is overloaded: `+` is ordinary addition, which a Demi is not a",
1619
- "number for, and `*` is ordinary Star, which refuses an aggregate with fields",
1711
+ "## Arithmetic",
1712
+ "",
1713
+ "Four operators act on a Demi's state. `+`, `-` and `*` **construct a fresh",
1714
+ "Demi** from observations of their operands: `+` deposits on the right and `-`",
1715
+ "on the left, each by the operand's Size, keeping the phase, and `*` scales both",
1716
+ "loads by a Count. `/` is the one observation among them: it observes Spin and",
1717
+ "answers a number, not a Demi. Each answers a fresh value and leaves its operand",
1718
+ "as it was, so they compose by nesting",
1719
+ "```",
1720
+ "; .D (Demi [2, 5, 3]);",
1721
+ "; [“” (D + 4), “” (D - 4), “” (D * 3)]",
1722
+ "# [“Demi(<>,5,7)”, “Demi(<>,9,3)”, “Demi(<>,15,9)”]",
1723
+ "; [(D / 2), ((D + 4) / 2)]",
1724
+ "# [1, -1]",
1725
+ "; [“” ((D + 4) - 2), “” ((D - 2) + 4), “” ((D + 4) * 3)]",
1726
+ "# [“Demi(<>,7,7)”, “Demi(<>,7,7)”, “Demi(<>,15,21)”]",
1727
+ "; “” D",
1728
+ "# “Demi(<>,5,3)”",
1729
+ "```",
1730
+ "A deposit keeps the phase, including phase 1, where application would flip it,",
1731
+ "and a zero Size deposits nothing while still answering a Demi. The operand is",
1732
+ "measured by its Size, so any sized Frame deposits",
1733
+ "```",
1734
+ "; [(D + 4).#, (D - 4).#, (D * 3).#]",
1735
+ "# [2, 2, 2]",
1736
+ "; .P (Demi [1, 5, 3]);",
1737
+ "; [“” (P + 4), (P + 4).#, “” (P - 4)]",
1738
+ "# [“Demi((),5,7)”, 1, “Demi((),9,3)”]",
1739
+ "; [“” (D + 0), “” (D - 0), “” (D [3, 4])]",
1740
+ "# [“Demi(<>,5,3)”, “Demi(<>,5,3)”, “Demi((),12,3)”]",
1741
+ "```",
1742
+ "Deposit is not application and deposit is not subtraction. `D x` flips the",
1743
+ "phase and `D + x` does not, so they reach different states; `D - x` adds to the",
1744
+ "left load and never takes from the right, so a load stays a whole Count and the",
1745
+ "signed residual only rises",
1746
+ "```",
1747
+ "; [(D + 4).###, (D - 4).###, D.###]",
1748
+ "# [-2, 6, 2]",
1749
+ "; [((D 4).# = (D + 4).#), (D 4).###, (D + 4).###]",
1750
+ "# [(), 6, -2]",
1751
+ "```",
1752
+ "Order of a right then a left deposit does not matter, and scaling after a",
1753
+ "balanced deposit is the Star shadow of scaling first",
1754
+ "```",
1755
+ "; [((D + 4) - 2) = ((D - 2) + 4), ((D + 4) * 3) = ((D * 3) + 12)]",
1756
+ "# [<>, <>]",
1757
+ "```",
1758
+ "A sizeless host refuses, its failure the answer, as application refuses it.",
1759
+ "`*` keeps the `scale_` domain, refusing a non-Count, and never flips to Star on",
1760
+ "the aggregate. `/` keeps Spin's typed, strictly positive Count divisor: a",
1761
+ "non-Count, a negative among them, is a type error, and a zero divisor is",
1762
+ "division by zero, even for a zero residual",
1763
+ "```",
1764
+ "; [D + ([].nope), D - ([].nope)]",
1765
+ "# [$!.name-missing “..., $!.name-missing “...]",
1766
+ "; [D * (0 - 1), D * 2.5]",
1767
+ "# [$!!.invalid-scale, $!!.invalid-scale]",
1768
+ "; [D / 0, D / (0 - 1), D / 2.5]",
1769
+ "# [$!.division-by-zero /, $!.type-error .n <(1).<>> -1, $!.type-error .n <(1).<>> 2.5]",
1770
+ "; (Demi [2, 4, 4]) / 0",
1771
+ "# $!.division-by-zero /",
1772
+ "```",
1773
+ "The signed-scalar reading misleads: `+` lowers the residual and `-` raises it,",
1774
+ "so `D + 4` is not “larger” than `D`, and `D - 4` is not `D` made smaller",
1620
1775
  "```",
1621
- "; [e + 3, e * 3]",
1622
- "# [(), $!.star-metadata *]",
1776
+ "; [(D + 4).### .< D.###, (D - 4).### .> D.###]",
1777
+ "# [<>, <>]",
1623
1778
  "```",
1624
1779
  "## A precise regression: a load read at the wrong depth",
1625
1780
  "",
@@ -4134,7 +4289,43 @@ export const HC_SOURCES = new Map([
4134
4289
  "; join-name (.middle “Q”)",
4135
4290
  "# $!invalid-argument-list (.middle “Q”, $!missing-required-argument .last;)",
4136
4291
  "```",
4137
- "The return type is usually inferred, but can be specified explicitly using a trailing `^^`.",
4292
+ "The return type is usually inferred, but can be specified explicitly using a",
4293
+ "trailing `^^`. The result a successful call exposes must conform to that schema,",
4294
+ "and a result that does not is refused rather than returned:",
4295
+ "```",
4296
+ "; .small (.x) ^ {x} ^^ <1, 2, 3>;",
4297
+ "; small (.x 2)",
4298
+ "# 2",
4299
+ "; small (.x 9)",
4300
+ "# $!.type-error <1, 2, 3> 9",
4301
+ "```",
4302
+ "A return contract checks only the exposed result; it neither freezes, copies,",
4303
+ "nor converts the underlying object, and a closure whose body already failed",
4304
+ "surfaces that failure rather than a contract complaint.",
4305
+ "",
4306
+ "",
4307
+ "#### Effect Boundaries",
4308
+ "",
4309
+ "Where `^` and `^^` describe one call, the arrow `->` describes a continuing",
4310
+ "relationship. In `A -> B` the callback `B` is registered on the value `A`",
4311
+ "manages, and a later committed mutation of that value, by any actor through any",
4312
+ "alias, is a new invocation of `B`. The arrow is an effect boundary, not a write",
4313
+ "permission: it answers `A` unchanged and never grants the right to write it.",
4314
+ "Here each committed write of the cell bumps a shared counter the callback holds,",
4315
+ "while the cell itself keeps the value that was written to it:",
4316
+ "```",
4317
+ "; .log_ [.count 0; .tick_ {@count (count + 1);}];",
4318
+ "; .cell_ [.v 1; .put_ {@v _;}];",
4319
+ "; cell_ -> {log_.tick_ ()};",
4320
+ "; cell_.put_ 7;",
4321
+ "; cell_.v",
4322
+ "# 7",
4323
+ "; log_.count",
4324
+ "# 1",
4325
+ "```",
4326
+ "A refused or uncommitted write triggers nothing, and a functional update on an",
4327
+ "immutable handle writes a copy the arrow never observed, so only a real",
4328
+ "committed mutation of the managed value is a new consequence.",
4138
4329
  "",
4139
4330
  "",
4140
4331
  "#### Type Values",
@@ -0,0 +1,92 @@
1
+ /** Subscribers registered on one managed value, in registration order. */
2
+ const subscribers = new WeakMap();
3
+ /** Managed values whose callbacks are currently running, to bound reentrancy. */
4
+ const firing = new WeakSet();
5
+ /** Committed nested mutations of a firing value, each owed one more round. */
6
+ const pending = new Map();
7
+ /** The most delivery rounds one outermost commit may cause (nested included). */
8
+ export const EFFECT_DELIVERY_LIMIT = 65_536;
9
+ /**
10
+ * The invoker is installed once by the runtime so this module need not import
11
+ * closure machinery (which would close an import cycle through `frame.ts`).
12
+ * Until it is installed, a registered callback is simply not called.
13
+ */
14
+ let invoke;
15
+ /** Installs the one callback-invocation strategy (called at startup). */
16
+ export function installEffectInvoker(invoker) {
17
+ invoke = invoker;
18
+ }
19
+ /**
20
+ * Registers `callback` as an effect-boundary observer of `managed`.
21
+ *
22
+ * Idempotent per (managed, callback) pair so re-declaring the same arrow does
23
+ * not multiply invocations. Returns the managed value so the arrow operator can
24
+ * answer it unchanged.
25
+ */
26
+ export function registerEffect(managed, callback) {
27
+ const existing = subscribers.get(managed);
28
+ if (!existing) {
29
+ subscribers.set(managed, [callback]);
30
+ return managed;
31
+ }
32
+ if (!existing.includes(callback))
33
+ existing.push(callback);
34
+ return managed;
35
+ }
36
+ /** Whether a value carries any effect-boundary subscribers. */
37
+ export function hasEffectSubscribers(managed) {
38
+ return subscribers.has(managed);
39
+ }
40
+ /**
41
+ * Whether `observer` itself is registered on `managed` by an `A -> B` arrow,
42
+ * so a committed mutation of `managed` invokes it. Another callback on the
43
+ * same value does not count (PR #475 review).
44
+ */
45
+ export function isEffectObserver(managed, observer) {
46
+ return subscribers.get(managed)?.includes(observer) ?? false;
47
+ }
48
+ /**
49
+ * Notifies a managed value's subscribers that it committed a mutation.
50
+ *
51
+ * The single seam called from the mutation commit points. It is a no-op for the
52
+ * overwhelming majority of frames, which carry no subscribers, so ordinary
53
+ * construction and mutation pay only a `WeakMap.has` check. A commit to a value
54
+ * already firing is deferred to a later round rather than dropped.
55
+ */
56
+ export function notifyEffect(managed) {
57
+ if (!subscribers.has(managed) || !invoke)
58
+ return;
59
+ if (firing.has(managed)) {
60
+ pending.set(managed, (pending.get(managed) ?? 0) + 1);
61
+ return;
62
+ }
63
+ firing.add(managed);
64
+ let thrown;
65
+ try {
66
+ let due = 1;
67
+ for (let rounds = 1; due > 0; rounds++) {
68
+ if (rounds > EFFECT_DELIVERY_LIMIT) {
69
+ throw new RangeError(`$!.effect-delivery-limit ${EFFECT_DELIVERY_LIMIT}`);
70
+ }
71
+ due--;
72
+ // Snapshot each round, so an arrow registered by a callback joins the
73
+ // next round rather than the one being delivered.
74
+ for (const callback of [...subscribers.get(managed)]) {
75
+ try {
76
+ invoke(callback, managed);
77
+ }
78
+ catch (error) {
79
+ thrown ??= { error };
80
+ }
81
+ }
82
+ due += pending.get(managed) ?? 0;
83
+ pending.delete(managed);
84
+ }
85
+ }
86
+ finally {
87
+ firing.delete(managed);
88
+ pending.delete(managed);
89
+ }
90
+ if (thrown)
91
+ throw thrown.error;
92
+ }
@@ -249,6 +249,25 @@ export class FrameArray extends FrameList {
249
249
  }
250
250
  return undefined;
251
251
  }
252
+ /**
253
+ * The method this aggregate declares for the operator `key`, bound to it as
254
+ * the left operand, or undefined when it declares none (015.02).
255
+ *
256
+ * Found on the aggregate or its declared parents, the same class chain its
257
+ * other methods come from, and never in the scope around it, so an operator
258
+ * written inside a method body keeps its ordinary meaning rather than
259
+ * recurring into the class that is running. The method runs immutably, like a
260
+ * declared observation: a deposit answers a fresh instance, as a functional
261
+ * update does, and leaves the left operand unchanged.
262
+ */
263
+ declaredOperator(key) {
264
+ if (!FrameArray.OPERATOR_KEYS.includes(key))
265
+ return undefined;
266
+ const method = this.declaredMethod(key);
267
+ if (!method)
268
+ return undefined;
269
+ return new BoundMethod(method, this, false, methodEffect(key));
270
+ }
252
271
  /**
253
272
  * What this aggregate contributes when text receives it (#398).
254
273
  *
@@ -455,6 +474,26 @@ Object.defineProperty(FrameArray, "APPLICATION_KEYS", {
455
474
  writable: true,
456
475
  value: ["apply_", "apply"]
457
476
  });
477
+ /**
478
+ * The operators an aggregate may declare its own answer to (015.02).
479
+ *
480
+ * These are the ordinary binary arithmetic spellings. A class declares one
481
+ * as a method under the operator's own name, `+`, `-`, `*` or `/`, the way
482
+ * it declares `apply`, `#` or `toText`. The method takes the right operand
483
+ * and answers the operation's result, so the class decides what the operator
484
+ * means on its instances without any special case in the evaluator.
485
+ */
486
+ Object.defineProperty(FrameArray, "OPERATOR_KEYS", {
487
+ enumerable: true,
488
+ configurable: true,
489
+ writable: true,
490
+ value: [
491
+ "+",
492
+ "-",
493
+ "*",
494
+ "/",
495
+ ]
496
+ });
458
497
  /** The key an aggregate declares its readable text under (#398). */
459
498
  Object.defineProperty(FrameArray, "TEXT_KEY", {
460
499
  enumerable: true,
@@ -6,6 +6,7 @@ import { FrameSymbol } from "./frame-symbol.js";
6
6
  import { NilContext } from "./context.js";
7
7
  import { EvaluationScope } from "./evaluation-scope.js";
8
8
  import { renderSourceTerm } from "./frame-list.js";
9
+ import { isFrameMatcher } from "./frame-match.js";
9
10
  // Both maps describe per-evaluation bound copies. The parsed/shared closure is
10
11
  // never a key, so evaluating one template in two scopes cannot rebind either
11
12
  // result or mutate the template's lexical ancestry.
@@ -23,6 +24,16 @@ export class FrameLazy extends FrameExpr {
23
24
  writable: true,
24
25
  value: void 0
25
26
  });
27
+ // The optional `^^` output contract, complementary to the `^` input
28
+ // signature above. A declared return schema gates the body's result the way
29
+ // `signature` gates the argument, and nothing else: it is a type assertion
30
+ // on the exposed value, not a freeze, copy, conversion, or callback.
31
+ Object.defineProperty(this, "returnContract", {
32
+ enumerable: true,
33
+ configurable: true,
34
+ writable: true,
35
+ value: void 0
36
+ });
26
37
  }
27
38
  bindSignature(signature) {
28
39
  if (signature instanceof FrameGroup) {
@@ -30,6 +41,38 @@ export class FrameLazy extends FrameExpr {
30
41
  }
31
42
  return this;
32
43
  }
44
+ /**
45
+ * Records the `^^` return contract. The schema is kept as written and only
46
+ * consulted after the body runs, so copying the closure template, which the
47
+ * per-evaluation `bind` above does, carries the contract to the bound copy.
48
+ */
49
+ bindReturn(returnContract) {
50
+ this.returnContract = returnContract;
51
+ return this;
52
+ }
53
+ /** The declared `^^` output schema, or undefined when none was bound. */
54
+ returnSchema() {
55
+ return this.returnContract;
56
+ }
57
+ /**
58
+ * Checks a completed body result against the declared `^^` contract. An
59
+ * undeclared closure keeps HC's implicit constructive behavior and returns
60
+ * the result unchanged. A result that is already a failure is propagated
61
+ * without a second complaint, since the body never produced a value to
62
+ * expose. Otherwise a non-conforming result is refused as a `$!.type-error`,
63
+ * naming the declared schema and the offending value.
64
+ */
65
+ checkReturn(result) {
66
+ const contract = this.returnContract;
67
+ if (!contract)
68
+ return result;
69
+ if (result.is.error)
70
+ return result;
71
+ if (isFrameMatcher(contract) && !contract.match(result).matched) {
72
+ return Frame.error(`$!.type-error ${contract.toString()} ${result.toString()}`);
73
+ }
74
+ return result;
75
+ }
33
76
  string_open() {
34
77
  return FrameLazy.LAZY_BEGIN;
35
78
  }
@@ -144,7 +187,8 @@ export class FrameLazy extends FrameExpr {
144
187
  return prepared;
145
188
  const enclosing = capturedScopes.get(this) ?? this.legacyCapture();
146
189
  const scope = EvaluationScope.call(prepared, parameter, this, enclosing, receiverState);
147
- return FrameExpr.evaluateBody(this.data, scope, this.is.sequence === true);
190
+ const result = FrameExpr.evaluateBody(this.data, scope, this.is.sequence === true);
191
+ return this.checkReturn(result);
148
192
  }
149
193
  legacyCapture() {
150
194
  return this.up && !this.up.is.missing
@@ -14,7 +14,7 @@ import { FrameCurry } from "../ops/frame-curry.js";
14
14
  import { isFrameMatcher } from "./frame-match.js";
15
15
  import { NilContext } from "./context.js";
16
16
  import { EvaluationScope } from "./evaluation-scope.js";
17
- import { completeAtEnd, includeOrReserve, TIME_DELIMITER, } from "./atom-syntax.js";
17
+ import { completeAtEnd, includeOrEnd, includeOrReserve, TIME_DELIMITER, } from "./atom-syntax.js";
18
18
  import { ScanDisposition, } from "../scan.js";
19
19
  /**
20
20
  * The echo a declaration answers, which is a declaration and not an element.
@@ -448,7 +448,27 @@ export class FrameOperator extends FrameSymbol {
448
448
  return bound;
449
449
  }
450
450
  called_by(context) {
451
- const value = FrameSymbol.for(this.data).called_by(context);
451
+ // An operator resolves against its left operand and the global table only,
452
+ // never the lexical scope the operand was read from (015.02). A class may
453
+ // answer an operator on its own instances by declaring a method under the
454
+ // operator's name, found on the operand and its declared parents, the chain
455
+ // its other methods come from. Resolving nothing else keeps an operator
456
+ // written inside a method body meaning the global operation rather than
457
+ // recurring into the class that is running, which a lexical walk would do
458
+ // for a load read back from the receiver.
459
+ const left = context.referent();
460
+ if (left instanceof FrameArray) {
461
+ const declared = left.declaredOperator(this.data);
462
+ if (declared)
463
+ return declared;
464
+ }
465
+ const globals = Frame.globals;
466
+ const resolved = typeof globals.operation === "function"
467
+ ? globals.operation(this.data, context)
468
+ : Frame.missing;
469
+ const value = resolved.is.missing
470
+ ? FrameSymbol.for(this.data).called_by(context)
471
+ : resolved;
452
472
  return value instanceof FrameCurry && this.receiverState
453
473
  ? value.withReceiverState(this.receiverState)
454
474
  : value;
@@ -488,6 +508,15 @@ Object.defineProperty(FrameOperator, "SYNTAX", {
488
508
  SIGIL_STARTS: FrameOperator.SIGIL_STARTS,
489
509
  recognize: (symbol, source = "") => {
490
510
  const char = symbol.toString();
511
+ // `->` is one operator, the effect-boundary arrow (006.17 §3-4). The
512
+ // hyphen that opens it is an ordinary operator start; the `>` that would
513
+ // otherwise redispatch to schema syntax is swallowed here so `a -> b`
514
+ // lexes as subject, arrow, callback rather than `a -` then an
515
+ // unterminated `<...>`. Only a lone trailing `-` claims the `>`; a longer
516
+ // operator run ending in `-` keeps the old boundary.
517
+ if (char === ">" && source === "-") {
518
+ return includeOrEnd(true);
519
+ }
491
520
  // Comparison brackets belong to the schema syntax, not to an operator.
492
521
  if (char === "<" || char === ">") {
493
522
  return { disposition: ScanDisposition.CompleteRedispatch };
@@ -1,5 +1,6 @@
1
1
  import { NilContext } from "./context.js";
2
2
  import { renderNested } from "./stringify.js";
3
+ import { hasEffectSubscribers, notifyEffect } from "./effect-registry.js";
3
4
  /** Visibility levels for logical frame bindings. */
4
5
  export var Visibility;
5
6
  (function (Visibility) {
@@ -253,12 +254,24 @@ export class MetaFrame {
253
254
  }
254
255
  /**
255
256
  * set adds a new key-value pair to the current context.
257
+ *
258
+ * This is the single commit point for a named-property mutation, so it is
259
+ * where an `A -> B` effect boundary observes a *committed* change (006.17
260
+ * §3-4): after the write lands, any callback registered on this value is a
261
+ * new invocation. Firing is a no-op for the common case of a value with no
262
+ * subscribers (a `WeakMap.has` check), and is skipped for a write that does
263
+ * not change the stored value, so a re-assignment of the same frame is not a
264
+ * mutation.
256
265
  */
257
266
  set(key, value) {
258
267
  if (this.meta === NilContext) {
259
268
  this.meta = {};
260
269
  }
270
+ const previous = this.meta[key];
261
271
  this.meta[key] = value;
272
+ if (previous !== value && hasEffectSubscribers(this)) {
273
+ notifyEffect(this);
274
+ }
262
275
  return this;
263
276
  }
264
277
  /** Whether this frame carries an explicitly declared parent. */
@@ -1006,6 +1019,11 @@ export class Frame extends MetaFrame {
1006
1019
  replaced = true;
1007
1020
  }
1008
1021
  }
1022
+ // An element-plane commit is a mutation too; a copy-on-write install lands
1023
+ // on a fresh copy that carries no subscribers, so it never fires here.
1024
+ if (replaced && hasEffectSubscribers(this)) {
1025
+ notifyEffect(this);
1026
+ }
1009
1027
  return replaced;
1010
1028
  }
1011
1029
  static quantityOperator(argument) {
@@ -0,0 +1,46 @@
1
+ import { isEffectObserver } from "./effect-registry.js";
2
+ /** Builds a plan from an explicit value→partition-id map. */
3
+ export function partitionPlan(placement) {
4
+ const ids = new Map(placement);
5
+ return { partitionOf: (value) => ids.get(value) };
6
+ }
7
+ /** Whether two placements name different partitions (a proposed boundary). */
8
+ function crosses(a, b) {
9
+ // Unplaced values are local; a boundary exists only between two named,
10
+ // distinct partitions.
11
+ return a !== undefined && b !== undefined && a !== b;
12
+ }
13
+ /**
14
+ * Checks a partition plan: accepts local mutable dependencies and transactional
15
+ * dependencies anywhere, and rejects a cross-partition *mutable* dependency
16
+ * that lacks an explicit effect boundary on its managed value.
17
+ *
18
+ * `arrows` lets a static (pre-evaluation) caller declare the explicit
19
+ * `[managed, observer]` effect boundaries of a plan; when omitted, coverage is
20
+ * read from the live effect registry, so an `A -> C` that actually ran makes
21
+ * C's dependency on A legal, and nothing else.
22
+ */
23
+ export function checkPartitions(edges, plan, arrows) {
24
+ const isCovered = (managed, observer) => arrows
25
+ ? arrows.some(([a, c]) => a === managed && c === observer)
26
+ : isEffectObserver(managed, observer);
27
+ const errors = [];
28
+ for (const edge of edges) {
29
+ if (edge.kind !== "mutable")
30
+ continue; // transactional never needs a boundary
31
+ const from = plan.partitionOf(edge.observer);
32
+ const to = plan.partitionOf(edge.managed);
33
+ if (!crosses(from, to))
34
+ continue; // local mutable dependency is fine
35
+ if (isCovered(edge.managed, edge.observer))
36
+ continue; // its own arrow
37
+ errors.push({
38
+ managed: edge.managed,
39
+ observer: edge.observer,
40
+ fromPartition: from,
41
+ toPartition: to,
42
+ reason: "$!.partition-error cross-partition mutable dependency without an effect boundary",
43
+ });
44
+ }
45
+ return { ok: errors.length === 0, errors };
46
+ }
package/esm/lib/frames.js CHANGED
@@ -50,4 +50,6 @@ export { Frame, } from "./frames/frame.js";
50
50
  export { MetaFrame, Visibility } from "./frames/meta-frame.js";
51
51
  export { ScanDisposition, } from "./scan.js";
52
52
  export { contextEqual, contextString, NilContext, } from "./frames/context.js";
53
+ export { hasEffectSubscribers, installEffectInvoker, isEffectObserver, notifyEffect, registerEffect, } from "./frames/effect-registry.js";
54
+ export { checkPartitions, partitionPlan, } from "./frames/partition-check.js";
53
55
  Frame.globals = Ops;
@@ -17,6 +17,19 @@ export class FrameOps extends Frame {
17
17
  }
18
18
  return Frame.missing;
19
19
  }
20
+ /**
21
+ * The built-in operation for `key`, curried to `origin` as its left operand,
22
+ * or missing when there is no such operation (015.02).
23
+ *
24
+ * Operator dispatch resolves a left operand's own declared method first, then
25
+ * this global table, and never the lexical scope the operand was read from.
26
+ * That keeps an operator written inside a method body meaning the global
27
+ * operation rather than the class's own method for the same spelling.
28
+ */
29
+ operation(key, origin) {
30
+ const func = this.OpsDict[key];
31
+ return func != null ? this.curry(func, origin, key) : Frame.missing;
32
+ }
20
33
  toString() {
21
34
  return this.OpsDict.toString();
22
35
  }
@@ -3,6 +3,20 @@ import { Frame } from "../frames/frame.js";
3
3
  import { FrameLazy } from "../frames/frame-lazy.js";
4
4
  import { FrameLiteral } from "../frames/frame-symbol.js";
5
5
  import { isFrameMatcher } from "../frames/frame-match.js";
6
+ import { installEffectInvoker, registerEffect, } from "../frames/effect-registry.js";
7
+ // Install the one strategy the effect registry uses to invoke a registered
8
+ // callback. A callback is an ordinary closure, so a committed mutation calls it
9
+ // with the managed value as its argument — a *new invocation*, never an
10
+ // alteration of a value it returned earlier. Installed here, where FrameLazy is
11
+ // already imported, so `frame.ts` need not depend on closure machinery.
12
+ installEffectInvoker((callback, managed) => callback.call(managed, Frame.nil));
13
+ /** The closure a declaration echo now names, if it names one. */
14
+ const boundClosure = (source) => {
15
+ if (!(source instanceof FrameLiteral) || !source.binding)
16
+ return undefined;
17
+ const bound = source.binding.target.get(source.binding.key);
18
+ return bound instanceof FrameLazy ? bound : undefined;
19
+ };
6
20
  /** Test whether a value belongs to a first-class type or schema. */
7
21
  export const HasType = (source, type) => {
8
22
  if (type === Frame.all)
@@ -23,3 +37,45 @@ export const BindType = (source, body) => {
23
37
  }
24
38
  return source;
25
39
  };
40
+ /**
41
+ * Attach an output-type contract to a declared closure, the `^^` complement of
42
+ * the `^` input signature. The left operand is the declaration echo produced
43
+ * by `^` (or by the declaration itself), whose name now holds the closure; the
44
+ * right operand is the schema the closure's result must conform to. Binding a
45
+ * return contract neither freezes nor rewrites the closure beyond recording the
46
+ * schema it will check at call time, and the echo is returned unchanged so a
47
+ * `^^` can follow a `^` in one left-associative expression. A `^^` with no
48
+ * closure to bind, or a left operand that is not a live declaration, is left
49
+ * alone rather than erroring, matching how `^` ignores a shape it cannot bind.
50
+ */
51
+ export const BindReturn = (source, returnType) => {
52
+ const closure = boundClosure(source);
53
+ if (closure) {
54
+ closure.bindReturn(returnType);
55
+ }
56
+ return source;
57
+ };
58
+ /**
59
+ * Register an effect boundary: `A -> B` (occurrence/history 006.17 §3-4).
60
+ *
61
+ * `A` is the managed value on the left; `B` is the callback on the right. This
62
+ * records `B` as an observer of `A`'s managed referent so that a *subsequent
63
+ * committed mutation of that value, by any actor through any alias*, is a new
64
+ * invocation of `B`. The arrow is an effect boundary, not a write-authority
65
+ * boundary: registration neither grants nor withholds write permission, does
66
+ * not freeze/copy/convert `A`, and is independent of whether any handle to `A`
67
+ * is mutable.
68
+ *
69
+ * The managed identity is `A`'s referent — the same frame a mutating write
70
+ * lands its `set`/`replaceMember` on — so a handle (`a_`) and the value it
71
+ * wraps register one and the same subscription. The arrow answers `A`
72
+ * unchanged, so it composes left-associatively like `^`/`^^` and leaves the
73
+ * one-shot/return spellings untouched. A left operand with no mutable identity
74
+ * (a bare scalar) registers against its own frame; nothing fires until that
75
+ * frame is actually mutated, which a scalar never is.
76
+ */
77
+ export const Arrow = (source, callback) => {
78
+ const managed = source.referent();
79
+ registerEffect(managed, callback);
80
+ return source;
81
+ };
package/esm/lib/ops.js CHANGED
@@ -3,7 +3,7 @@ import { FrameOps } from "./ops/frame-ops.js";
3
3
  import { MapElements, MapMembers, ReduceElements, ReduceMembers, SpliceElements, } from "./ops/iterators.js";
4
4
  import { Add, Divide, Equals, GreaterThan, GreaterThanOrEqual, Identical, LessThan, LessThanOrEqual, Modulo, Multiply, Power, Subtract, TypeEquals, } from "./ops/math.js";
5
5
  import { IdenticalMember, Member, TypedMember } from "./ops/membership.js";
6
- import { BindType } from "./ops/type-operations.js";
6
+ import { Arrow, BindReturn, BindType } from "./ops/type-operations.js";
7
7
  export { FrameCurry } from "./ops/frame-curry.js";
8
8
  export const Ops = new FrameOps({
9
9
  "&": MapElements,
@@ -32,4 +32,6 @@ export const Ops = new FrameOps({
32
32
  "~~": TypedMember,
33
33
  "~~~": IdenticalMember,
34
34
  "^": BindType,
35
+ "^^": BindReturn,
36
+ "->": Arrow,
35
37
  });
@@ -1 +1 @@
1
- export const VERSION = "0.40.0";
1
+ export const VERSION = "0.41.1";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hclang",
3
- "version": "0.40.0",
3
+ "version": "0.41.1",
4
4
  "description": "Homoiconic C command-line interpreter and REPL",
5
5
  "keywords": [
6
6
  "language",