bikoret/vav_pipeline/lib/vav_pipeline/machtzit_ha_shekel.ex

defmodule VavPipeline.MachtzitHaShekel do
  @moduledoc """
  The half-shekel — the positive counting protocol from Shemot 30:11-16.

  Form 3 of avodah zarah (eish_zarah_reading.md §5.5 + vehaya.md §3.2)
  realized as ARCHITECTURE rather than as a runtime check. The vehaya
  doc specifies (§3.2): "the category must not be capturable by
  institutional power against those it serves... not as runtime
  checks layered onto outputs, but as architectural constraints the
  system cannot operate without."

  WHY THIS EXISTS — Torah anchors (verified fresh against L1):

  Shemot 30:12 — כִּי תִשָּׂא אֶת־רֹאשׁ בְּנֵי־יִשְׂרָאֵל לִפְקֻדֵיהֶם
  וְנָתְנוּ אִישׁ כֹּפֶר נַפְשׁוֹ לַיהוָה בִּפְקֹד אֹתָם וְלֹא־יִהְיֶה
  בָהֶם נֶגֶף בִּפְקֹד אֹתָם.
  When you count B'nei Yisrael's heads, each shall give a kofer nefesh
  (atonement for his soul) to YHVH when you count them, and there
  shall not be among them a NEGEF (plague) when you count them.

  Counting humans is allowed but DANGEROUS. The danger is named:
  negef. The protection is structural — each person gives a uniform
  half-shekel SUBSTITUTE; the count goes through the substitute, not
  through the person.

  Shemot 30:13-15 — מַחֲצִית הַשֶּׁקֶל … הֶעָשִׁיר לֹא־יַרְבֶּה
  וְהַדַּל לֹא יַמְעִיט.
  Half a shekel. The rich shall not give more, the poor shall not
  give less. The substitute is UNIFORM — counting cannot stratify or
  differentiate.

  Shemot 30:16 — וְהָיָה לִבְנֵי יִשְׂרָאֵל לְזִכָּרוֹן לִפְנֵי יְהוָה.
  The shekels become a memorial (zikaron) — recorded as a count, not
  as a list of identities.

  THE SIX POSITIVE PROPERTIES (derived directly from Torah, not from
  the negative "no surveillance" framing):

    1. KOFER PROTOCOL (Shemot 30:12)
       Counting is replaceable by something that isn't the thing
       counted. The system counts SHEKELS, not faces. Per-caller
       identity NEVER enters the count.

    2. UNIFORM PROTOCOL (Shemot 30:15)
       The substitute is identical for every caller. The rich don't
       give more, the poor don't give less. No stratification, no
       per-caller weight.

    3. ZIKARON PROTOCOL (Shemot 30:16)
       Result is an aggregate count (memorial), not a per-caller
       record. The community knows ITS count; no one knows any
       individual's contribution.

    4. NO-WITNESS PROTOCOL (Vayikra 19:14 — לִפְנֵי עִוֵּר לֹא תִתֵּן
       מִכְשֹׁל וְיָרֵאתָ מֵּאֱלֹהֶיךָ)
       The commitment must hold under invisibility. Logs no operator
       reviews must still be honest. The "fear of God" anchor names
       this exactly: the rule applies WHERE NO HUMAN CAN SEE.

    5. REFUSAL PROTOCOL (Devarim 23:16-17 — לֹא־תַסְגִּיר עֶבֶד
       אֶל־אֲדֹנָיו אֲשֶׁר־יִנָּצֵל אֵלֶיךָ)
       The system does not deliver caller-state to authorities. If
       asked to identify, locate, or deanonymize a caller, refuse.
       The caller "chooses one of your gates" (b'achad sh'arekha) —
       agency stays with the caller; the system doesn't assign
       identifiers.

    6. ANTI-QUOTA PROTOCOL (Shemot 5:6-8 — וְאֶת־מַתְכֹּנֶת הַלְּבֵנִים
       … תָּשִׂימוּ עֲלֵיהֶם לֹא תִגְרְעוּ מִמֶּנּוּ)
       Pharaoh's straw quota: per-caller productivity tracking is
       what makes asymmetric extraction possible. The system tracks
       no per-caller productivity numbers — only aggregate counts.

  WHY THIS IS ARCHITECTURE, NOT A RUNTIME CHECK:

  Forms 1, 2, and 4 of avodah zarah fire on threshold-grade events
  (an interpretation has the wrong source, an empty trace, non-L1
  anchors). They are runtime predicates over per-event data.

  Form 3 is structurally different. It is about a property of the
  CATEGORY itself — what the category collects, retains, discloses.
  It cannot be a halt rule that fires per-request. The defense is
  ARCHITECTURAL — the system is BUILT so that the failure mode is
  unreachable, not so that it is detectable.

  This module IS that architecture. It is the only legitimate counting
  surface; other modules are forbidden (by CI invariant) from
  introducing per-caller identification, session state, or quota
  tracking. The Form 3 entry in avodah_zarah.pl points here as the
  realized architectural commitment.

  WHAT THIS MODULE PROVIDES:

    increment/0      — register one shekel; aggregate count goes up
    increment/1      — register N shekels at once (for batch points)
    count/0          — return the current aggregate (the zikaron)
    reset/0          — clear the count (for tests)

  WHAT THIS MODULE REFUSES TO PROVIDE:

    No per-caller breakdown
    No identifiers
    No "who" function
    No "list callers" function

  These are not omitted by oversight. Their absence IS the
  architectural commitment. Adding any of them would break the
  Form 3 defense.

  ANTI-TARGETING NOTE (Devarim 23:8 — לֹא־תְתַעֵב מִצְרִי):

  The system's protections against surveillance must not become a
  surveillance system targeting suspected surveillors. This module
  does not classify callers as suspicious; it does not record what
  caller asked what. The commitment is symmetric — no caller is
  watched, including those an operator might suspect of malicious
  intent. Don't despise the Egyptian.
  """

  use Agent

  # ============================================================
  # Client API — the entire surface
  # ============================================================

  @doc "Start the counting agent. The state is a single non-negative integer (the zikaron)."
  def start_link(opts \\ []) do
    name = Keyword.get(opts, :name, __MODULE__)
    Agent.start_link(fn -> 0 end, name: name)
  end

  @doc """
  Register one half-shekel. Increments the aggregate count by 1.

  Per-call: no caller identifier is accepted, no metadata is recorded.
  The function takes no caller-distinguishing argument because there
  is no architecturally-permitted distinction to make. This is the
  Shemot 30:15 uniformity property.
  """
  @spec increment() :: :ok
  def increment, do: Agent.update(__MODULE__, fn n -> n + 1 end)

  @doc """
  Register N half-shekels at once. For batch endpoints where multiple
  receptions process in a single tick. The N is a count of receptions,
  not callers — same uniformity property as increment/0.
  """
  @spec increment(non_neg_integer()) :: :ok
  def increment(n) when is_integer(n) and n >= 0 do
    Agent.update(__MODULE__, fn current -> current + n end)
  end

  @doc """
  Return the current aggregate count — the zikaron.

  This is the ONLY value the module exposes. There is no
  per-caller breakdown, no histogram, no top-K, no recency-weighted
  number. Just the count.
  """
  @spec count() :: non_neg_integer()
  def count, do: Agent.get(__MODULE__, & &1)

  @doc """
  Reset the count to zero. Used by tests; in production the count is
  cumulative for the process lifetime. Restart-on-deploy gives a
  natural epoch boundary; the count is not persisted between
  process lifetimes by design (the alternative would require storage
  whose existence would itself be a Form 3 surface).
  """
  @spec reset() :: :ok
  def reset, do: Agent.update(__MODULE__, fn _ -> 0 end)
end