The interface was shaped by a caller that is gone

# Self-authored for the EML case corpus (no external origin). Six features of
# this interface exist because of one integration. That integration was retired
# two years ago. What still depends on each is computed below.
#
# Shaping the interface around the caller was right. There was one consumer, its
# needs were real and specific, and designing for a hypothetical second consumer
# instead of the actual first one is how interfaces end up serving nobody.
#
# When that consumer goes, its requirements do not leave with it. They are now
# properties of a published interface that other callers have arrived at and
# written against, so each one is either dead weight or has been picked up by
# somebody who never needed it in the first place.
#
# Each feature is checked against the callers that exist now.

# [feature, why it exists, current callers using it, cost to keep]
[["synchronous mode", "the retired integration could not poll", 0, 3], ["the flat response shape", "their parser was hand-written", 4, 1], ["the legacy date format", "their platform predated ISO", 1, 2], ["batch size capped at 50", "their gateway timed out", 0, 2], ["the duplicated id field", "they read one and wrote the other", 2, 1], ["the sync-only error code", "their retry logic keyed on it", 0, 1]] => features

len(features) => n
0 => orphaned
0 => adopted
0 => orphan_cost
0 => total_cost
for f in features:
    total_cost + f[3] => total_cost
    if f[2] == 0:
        orphaned + 1 => orphaned
        orphan_cost + f[3] => orphan_cost
    else:
        adopted + 1 => adopted

"features shaped by the retired integration : " + str(n) ^0
"  now used by nobody      : " + str(orphaned) ^0
"  picked up by other callers : " + str(adopted) ^0
"" ^0

"feature                    exists because                        callers   cost" ^0
for f in features:
    "  " + f[0] + "   " + f[1] + "   " + str(f[2]) + "         " + str(f[3]) ^0
"" ^0

"maintenance cost per release : " + str(total_cost) ^0
if orphan_cost > 0:
    "  spent on features with no caller : " + str(orphan_cost) + ", which is " + str(int(orphan_cost * 100 / total_cost)) + "%" ^0
"" ^0

# ---- the adopted ones are the harder half ----
#
# A feature nobody uses can be removed. A feature somebody uses is now a
# promise, and the promise was made to a caller that no longer exists.

0 => adopted_callers
for f in features:
    if f[2] > 0:
        adopted_callers + f[2] => adopted_callers
"features other callers now depend on : " + str(adopted) ^0
"  callers depending on them : " + str(adopted_callers) ^0
for f in features:
    if f[2] > 0:
        "  " + f[0] + " : " + str(f[2]) + " caller(s), and it exists because " + f[1] ^0
"  none of those callers asked for the shape; they wrote against what was" ^0
"  there, which is what every caller does" ^0
"" ^0

# ---- what a redesign would have to argue ----

"removing an adopted feature" ^0
"  callers broken : " + str(adopted_callers) ^0
"  the original reason : gone" ^0
"  the current reason  : " + str(adopted_callers) + " callers, which is a reason that did not" ^0
"  exist when the feature was designed and is now the only one" ^0
"" ^0

"removing an orphaned feature" ^0
"  callers broken : 0" ^0
"  cost recovered : " + str(orphan_cost) + " per release" ^0
"  what stops it  : it is published, so removal is a version bump, and a" ^0
"  version bump costs every caller including the " + str(adopted_callers) + " who use other parts" ^0
"" ^0

# ---- how the reasons decayed ----

"what is recorded about why each feature exists" ^0
"  in the interface itself : nothing; a shape has no reason attached" ^0
"  in the design doc       : the integration's name, which now resolves to" ^0
"  nothing" ^0
"  the reason survived exactly as long as the people who were in the room" ^0
"" ^0

# ---- the control: a feature with more than one original caller ----
#
# Where two independent consumers needed the same thing, the requirement is a
# property of the domain rather than of one integration, and it survives either
# of them leaving.

"control - a feature two independent consumers asked for" ^0
"  original callers : 2" ^0
"  if one retires : the requirement still has a caller and a reason" ^0
"  the difference is not the design work; it is whether the reason was ever" ^0
"  attached to more than one party" ^0
"" ^0

"Designing for the actual caller was right and designing for a hypothetical" ^0
"one is how interfaces serve nobody. The caller left and its requirements" ^0
"stayed, and other callers have since written against them." ^0

features = [["synchronous mode", "the retired integration could not poll", 0, 3], ["the flat response shape", "their parser was hand-written", 4, 1], ["the legacy date format", "their platform predated ISO", 1, 2], ["batch size capped at 50", "their gateway timed out", 0, 2], ["the duplicated id field", "they read one and wrote the other", 2, 1], ["the sync-only error code", "their retry logic keyed on it", 0, 1]]
n = len(features)
orphaned = 0
adopted = 0
orphan_cost = 0
total_cost = 0
for f in features:
    total_cost = total_cost + f[3]
    if f[2] == 0:
        orphaned = orphaned + 1
        orphan_cost = orphan_cost + f[3]
    else:
        adopted = adopted + 1
print("features shaped by the retired integration : " + str(n))
print("  now used by nobody      : " + str(orphaned))
print("  picked up by other callers : " + str(adopted))
print("")
print("feature                    exists because                        callers   cost")
for f in features:
    print("  " + f[0] + "   " + f[1] + "   " + str(f[2]) + "         " + str(f[3]))
print("")
print("maintenance cost per release : " + str(total_cost))
if orphan_cost > 0:
    print("  spent on features with no caller : " + str(orphan_cost) + ", which is " + str(int(orphan_cost * 100 / total_cost)) + "%")
print("")
adopted_callers = 0
for f in features:
    if f[2] > 0:
        adopted_callers = adopted_callers + f[2]
print("features other callers now depend on : " + str(adopted))
print("  callers depending on them : " + str(adopted_callers))
for f in features:
    if f[2] > 0:
        print("  " + f[0] + " : " + str(f[2]) + " caller(s), and it exists because " + f[1])
print("  none of those callers asked for the shape; they wrote against what was")
print("  there, which is what every caller does")
print("")
print("removing an adopted feature")
print("  callers broken : " + str(adopted_callers))
print("  the original reason : gone")
print("  the current reason  : " + str(adopted_callers) + " callers, which is a reason that did not")
print("  exist when the feature was designed and is now the only one")
print("")
print("removing an orphaned feature")
print("  callers broken : 0")
print("  cost recovered : " + str(orphan_cost) + " per release")
print("  what stops it  : it is published, so removal is a version bump, and a")
print("  version bump costs every caller including the " + str(adopted_callers) + " who use other parts")
print("")
print("what is recorded about why each feature exists")
print("  in the interface itself : nothing; a shape has no reason attached")
print("  in the design doc       : the integration's name, which now resolves to")
print("  nothing")
print("  the reason survived exactly as long as the people who were in the room")
print("")
print("control - a feature two independent consumers asked for")
print("  original callers : 2")
print("  if one retires : the requirement still has a caller and a reason")
print("  the difference is not the design work; it is whether the reason was ever")
print("  attached to more than one party")
print("")
print("Designing for the actual caller was right and designing for a hypothetical")
print("one is how interfaces serve nobody. The caller left and its requirements")
print("stayed, and other callers have since written against them.")

features shaped by the retired integration : 6
  now used by nobody      : 3
  picked up by other callers : 3

feature                    exists because                        callers   cost
  synchronous mode   the retired integration could not poll   0         3
  the flat response shape   their parser was hand-written   4         1
  the legacy date format   their platform predated ISO   1         2
  batch size capped at 50   their gateway timed out   0         2
  the duplicated id field   they read one and wrote the other   2         1
  the sync-only error code   their retry logic keyed on it   0         1

maintenance cost per release : 10
  spent on features with no caller : 6, which is 60%

features other callers now depend on : 3
  callers depending on them : 7
  the flat response shape : 4 caller(s), and it exists because their parser was hand-written
  the legacy date format : 1 caller(s), and it exists because their platform predated ISO
  the duplicated id field : 2 caller(s), and it exists because they read one and wrote the other
  none of those callers asked for the shape; they wrote against what was
  there, which is what every caller does

removing an adopted feature
  callers broken : 7
  the original reason : gone
  the current reason  : 7 callers, which is a reason that did not
  exist when the feature was designed and is now the only one

removing an orphaned feature
  callers broken : 0
  cost recovered : 6 per release
  what stops it  : it is published, so removal is a version bump, and a
  version bump costs every caller including the 7 who use other parts

what is recorded about why each feature exists
  in the interface itself : nothing; a shape has no reason attached
  in the design doc       : the integration's name, which now resolves to
  nothing
  the reason survived exactly as long as the people who were in the room

control - a feature two independent consumers asked for
  original callers : 2
  if one retires : the requirement still has a caller and a reason
  the difference is not the design work; it is whether the reason was ever
  attached to more than one party

Designing for the actual caller was right and designing for a hypothetical
one is how interfaces serve nobody. The caller left and its requirements
stayed, and other callers have since written against them.

Trace event types